* [PATCH 9/9] media: docs: v4l2-controls: remove outdated paragraph
From: Luca Ceresoli @ 2019-06-13 14:18 UTC (permalink / raw)
To: linux-media
Cc: Luca Ceresoli, Mauro Carvalho Chehab, Hans Verkuil, linux-kernel,
linux-doc
In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net>
This paragraph was added by commit a42b57f5aacf ("V4L/DVB: Documentation:
add v4l2-controls.txt documenting the new controls API") back in 2010, when
the controls API has been improved. Nowadays it is a bit anachronistic, so
remove it.
The same information is stated in up-to-date wording a few paragraphs later
anyway:
> You’re done! And this is sufficient for most of the drivers we have. No
> need to do any validation of control values, or implement QUERYCTRL,
> QUERY_EXT_CTRL and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS
> are automatically supported.
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
Documentation/media/kapi/v4l2-controls.rst | 5 -----
1 file changed, 5 deletions(-)
diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst
index 407617b1d0ce..ebe2a55908be 100644
--- a/Documentation/media/kapi/v4l2-controls.rst
+++ b/Documentation/media/kapi/v4l2-controls.rst
@@ -98,11 +98,6 @@ For V4L2 drivers:
foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
-Finally, remove all control functions from your v4l2_ioctl_ops (if any):
-vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl,
-vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
-Those are now no longer needed.
-
For sub-device drivers:
.. code-block:: c
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v1 29/31] docs: nvdimm: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 20:41 UTC (permalink / raw)
To: Dan Williams
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Vishal Verma,
Dave Jiang, Keith Busch, Ira Weiny, linux-nvdimm
In-Reply-To: <CAPcyv4g08r6bK_SyTjzKFRM7=wpTQLdmHqRSGh7r-e9YD4tq5Q@mail.gmail.com>
Em Wed, 12 Jun 2019 12:04:12 -0700
Dan Williams <dan.j.williams@intel.com> escreveu:
> Hi Mauro,
>
> On Wed, Jun 12, 2019 at 11:38 AM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > Rename the mtd documentation files to ReST, add an
>
> s/mtd/nvdimm/
Sorry, cut and paste issue :-)
>
> > 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.
>
> Looks ok, but I was not able to apply this one in isolation to give it
> a try. Am I missing some pre-reqs compared to v5.2-rc4?
I wrote the patch before v5.2-rc1, but, as this series touches a lot
of stuff, it was rebased against today's linux-next (next-20190612).
I didn't notice an conflict on this specific file during the rebases
though.
There is a simple patch applied on linux-next after v5.2-rc4:
commit 3d9cf48b2ca257f1a249b347236098c3cf9d54f1
Author: Shiyang Ruan <ruansy.fnst@cn.fujitsu.com>
Date: Thu May 9 15:40:49 2019 +0800
Documentation: nvdimm: Fix typo
Remove the extra 'we '.
Signed-off-by: Shiyang Ruan <ruansy.fnst@cn.fujitsu.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Could this be the cause of the issue you're noticing when
trying to apply it?
As this is signed-off by Jon, I suspect it went via docs-next.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v1 09/31] docs: driver-model: convert docs to ReST and rename to *.rst
From: Jeff Kirsher @ 2019-06-12 20:21 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Linus Walleij, Bartosz Golaszewski, Jean Delvare, Guenter Roeck,
Greg Kroah-Hartman, Rafael J. Wysocki, David S. Miller,
Julia Lawall, Gilles Muller, Nicolas Palix, Michal Marek,
linux-gpio, linux-hwmon, intel-wired-lan, netdev, cocci
In-Reply-To: <c90bb60d65aaba4ce5957894cc6890ebe5048d95.1560364494.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 2657 bytes --]
On Wed, 2019-06-12 at 15:38 -0300, Mauro Carvalho Chehab wrote:
> Convert the various documents at the driver-model, preparing
> them to be part of the driver-api book.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> 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>
Acked-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
For the ice driver comment change.
> ---
> Documentation/driver-api/gpio/driver.rst | 2 +-
> .../driver-model/{binding.txt => binding.rst} | 20 +-
> .../driver-model/{bus.txt => bus.rst} | 69 ++--
> .../driver-model/{class.txt => class.rst} | 74 ++--
> ...esign-patterns.txt => design-patterns.rst} | 106 +++---
> .../driver-model/{device.txt => device.rst} | 57 +--
> .../driver-model/{devres.txt => devres.rst} | 50 +--
> .../driver-model/{driver.txt => driver.rst} | 112 +++---
> Documentation/driver-model/index.rst | 26 ++
> .../{overview.txt => overview.rst} | 37 +-
> .../{platform.txt => platform.rst} | 30 +-
> .../driver-model/{porting.txt => porting.rst} | 333 +++++++++---------
> Documentation/eisa.txt | 4 +-
> Documentation/hwmon/submitting-patches.rst | 2 +-
> drivers/base/platform.c | 2 +-
> drivers/gpio/gpio-cs5535.c | 2 +-
> drivers/net/ethernet/intel/ice/ice_main.c | 2 +-
> scripts/coccinelle/free/devm_free.cocci | 2 +-
> 18 files changed, 489 insertions(+), 441 deletions(-)
> rename Documentation/driver-model/{binding.txt => binding.rst} (92%)
> rename Documentation/driver-model/{bus.txt => bus.rst} (76%)
> rename Documentation/driver-model/{class.txt => class.rst} (75%)
> rename Documentation/driver-model/{design-patterns.txt => design-
> patterns.rst} (59%)
> rename Documentation/driver-model/{device.txt => device.rst} (71%)
> rename Documentation/driver-model/{devres.txt => devres.rst} (93%)
> rename Documentation/driver-model/{driver.txt => driver.rst} (75%)
> create mode 100644 Documentation/driver-model/index.rst
> rename Documentation/driver-model/{overview.txt => overview.rst} (90%)
> rename Documentation/driver-model/{platform.txt => platform.rst} (95%)
> rename Documentation/driver-model/{porting.txt => porting.rst} (62%)
[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
* Re: [PATCH v1 23/31] docs: laptops: convert to ReST
From: Andy Shevchenko @ 2019-06-12 20:19 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Mattia Dongili,
Arnd Bergmann, Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
Platform Driver
In-Reply-To: <7dd6dfc3b0771e1035134fcb8151f4231c078615.1560364494.git.mchehab+samsung@kernel.org>
On Wed, Jun 12, 2019 at 9:38 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Rename the laptops 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.
>
Thanks!
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/ABI/testing/sysfs-block-device | 2 +-
> .../ABI/testing/sysfs-platform-asus-laptop | 2 +-
> .../admin-guide/kernel-parameters.txt | 2 +-
> .../{asus-laptop.txt => asus-laptop.rst} | 92 ++--
> ...otection.txt => disk-shock-protection.rst} | 32 +-
> Documentation/laptops/index.rst | 17 +
> .../{laptop-mode.txt => laptop-mode.rst} | 509 +++++++++---------
> .../{sony-laptop.txt => sony-laptop.rst} | 58 +-
> .../laptops/{sonypi.txt => sonypi.rst} | 28 +-
> .../{thinkpad-acpi.txt => thinkpad-acpi.rst} | 363 ++++++++-----
> .../{toshiba_haps.txt => toshiba_haps.rst} | 47 +-
> Documentation/sysctl/vm.txt | 4 +-
> MAINTAINERS | 2 +-
> drivers/char/Kconfig | 2 +-
> drivers/platform/x86/Kconfig | 4 +-
> 15 files changed, 660 insertions(+), 504 deletions(-)
> rename Documentation/laptops/{asus-laptop.txt => asus-laptop.rst} (84%)
> rename Documentation/laptops/{disk-shock-protection.txt => disk-shock-protection.rst} (91%)
> create mode 100644 Documentation/laptops/index.rst
> rename Documentation/laptops/{laptop-mode.txt => laptop-mode.rst} (62%)
> rename Documentation/laptops/{sony-laptop.txt => sony-laptop.rst} (85%)
> rename Documentation/laptops/{sonypi.txt => sonypi.rst} (87%)
> rename Documentation/laptops/{thinkpad-acpi.txt => thinkpad-acpi.rst} (89%)
> rename Documentation/laptops/{toshiba_haps.txt => toshiba_haps.rst} (60%)
>
> diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
> index 82ef6eab042d..0d57bbb4fddc 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.txt
> + Documentation/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 cd9d667c3da2..d67fa4bafa70 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.txt
> + The DDD table can be found in Documentation/laptops/asus-laptop.rst
>
> What: /sys/devices/platform/asus_laptop/bluetooth
> Date: January 2007
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index 3faf37b8b001..7abe677f8c5e 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.txt
> + See Documentation/laptops/sonypi.rst
>
> spectre_v2= [X86] Control mitigation of Spectre variant 2
> (indirect branch speculation) vulnerability.
> diff --git a/Documentation/laptops/asus-laptop.txt b/Documentation/laptops/asus-laptop.rst
> similarity index 84%
> rename from Documentation/laptops/asus-laptop.txt
> rename to Documentation/laptops/asus-laptop.rst
> index 5f2858712aa0..95176321a25a 100644
> --- a/Documentation/laptops/asus-laptop.txt
> +++ b/Documentation/laptops/asus-laptop.rst
> @@ -1,6 +1,9 @@
> +==================
> Asus Laptop Extras
> +==================
>
> Version 0.1
> +
> August 6, 2009
>
> Corentin Chary <corentincj@iksaif.net>
> @@ -10,11 +13,12 @@ http://acpi4asus.sf.net/
> It may also support some MEDION, JVC or VICTOR laptops (such as MEDION 9675 or
> VICTOR XP7210 for example). It makes all the extra buttons generate input
> events (like keyboards).
> +
> On some models adds support for changing the display brightness and output,
> switching the LCD backlight on and off, and most importantly, allows you to
> blink those fancy LEDs intended for reporting mail and wireless status.
>
> -This driver supercedes the old asus_acpi driver.
> +This driver supersedes the old asus_acpi driver.
>
> Requirements
> ------------
> @@ -49,7 +53,7 @@ Usage
> see some lines like this :
>
> Asus Laptop Extras version 0.42
> - L2D model detected.
> + - L2D model detected.
>
> If it is not the output you have on your laptop, send it (and the laptop's
> DSDT) to me.
> @@ -68,9 +72,12 @@ Usage
> LEDs
> ----
>
> - You can modify LEDs be echoing values to /sys/class/leds/asus::*/brightness :
> + You can modify LEDs be echoing values to `/sys/class/leds/asus/*/brightness`::
> +
> echo 1 > /sys/class/leds/asus::mail/brightness
> +
> will switch the mail LED on.
> +
> You can also know if they are on/off by reading their content and use
> kernel triggers like disk-activity or heartbeat.
>
> @@ -81,7 +88,7 @@ Backlight
> /sys/class/backlight/asus-laptop/. Brightness Values are between 0 and 15.
>
> Wireless devices
> ----------------
> +----------------
>
> You can turn the internal Bluetooth adapter on/off with the bluetooth entry
> (only on models with Bluetooth). This usually controls the associated LED.
> @@ -93,18 +100,20 @@ Display switching
> Note: the display switching code is currently considered EXPERIMENTAL.
>
> Switching works for the following models:
> - L3800C
> - A2500H
> - L5800C
> - M5200N
> - W1000N (albeit with some glitches)
> - M6700R
> - A6JC
> - F3J
> +
> + - L3800C
> + - A2500H
> + - L5800C
> + - M5200N
> + - W1000N (albeit with some glitches)
> + - M6700R
> + - A6JC
> + - F3J
>
> Switching doesn't work for the following:
> - M3700N
> - L2X00D (locks the laptop under certain conditions)
> +
> + - M3700N
> + - L2X00D (locks the laptop under certain conditions)
>
> To switch the displays, echo values from 0 to 15 to
> /sys/devices/platform/asus-laptop/display. The significance of those values
> @@ -113,48 +122,51 @@ Display switching
> +-------+-----+-----+-----+-----+-----+
> | Bin | Val | DVI | TV | CRT | LCD |
> +-------+-----+-----+-----+-----+-----+
> - + 0000 + 0 + + + + +
> + | 0000 | 0 | | | | |
> +-------+-----+-----+-----+-----+-----+
> - + 0001 + 1 + + + + X +
> + | 0001 | 1 | | | | X |
> +-------+-----+-----+-----+-----+-----+
> - + 0010 + 2 + + + X + +
> + | 0010 | 2 | | | X | |
> +-------+-----+-----+-----+-----+-----+
> - + 0011 + 3 + + + X + X +
> + | 0011 | 3 | | | X | X |
> +-------+-----+-----+-----+-----+-----+
> - + 0100 + 4 + + X + + +
> + | 0100 | 4 | | X | | |
> +-------+-----+-----+-----+-----+-----+
> - + 0101 + 5 + + X + + X +
> + | 0101 | 5 | | X | | X |
> +-------+-----+-----+-----+-----+-----+
> - + 0110 + 6 + + X + X + +
> + | 0110 | 6 | | X | X | |
> +-------+-----+-----+-----+-----+-----+
> - + 0111 + 7 + + X + X + X +
> + | 0111 | 7 | | X | X | X |
> +-------+-----+-----+-----+-----+-----+
> - + 1000 + 8 + X + + + +
> + | 1000 | 8 | X | | | |
> +-------+-----+-----+-----+-----+-----+
> - + 1001 + 9 + X + + + X +
> + | 1001 | 9 | X | | | X |
> +-------+-----+-----+-----+-----+-----+
> - + 1010 + 10 + X + + X + +
> + | 1010 | 10 | X | | X | |
> +-------+-----+-----+-----+-----+-----+
> - + 1011 + 11 + X + + X + X +
> + | 1011 | 11 | X | | X | X |
> +-------+-----+-----+-----+-----+-----+
> - + 1100 + 12 + X + X + + +
> + | 1100 | 12 | X | X | | |
> +-------+-----+-----+-----+-----+-----+
> - + 1101 + 13 + X + X + + X +
> + | 1101 | 13 | X | X | | X |
> +-------+-----+-----+-----+-----+-----+
> - + 1110 + 14 + X + X + X + +
> + | 1110 | 14 | X | X | X | |
> +-------+-----+-----+-----+-----+-----+
> - + 1111 + 15 + X + X + X + X +
> + | 1111 | 15 | X | X | X | X |
> +-------+-----+-----+-----+-----+-----+
>
> In most cases, the appropriate displays must be plugged in for the above
> combinations to work. TV-Out may need to be initialized at boot time.
>
> Debugging:
> +
> 1) Check whether the Fn+F8 key:
> +
> a) does not lock the laptop (try a boot with noapic / nolapic if it does)
> b) generates events (0x6n, where n is the value corresponding to the
> configuration above)
> c) actually works
> +
> Record the disp value at every configuration.
> 2) Echo values from 0 to 15 to /sys/devices/platform/asus-laptop/display.
> Record its value, note any change. If nothing changes, try a broader range,
> @@ -164,7 +176,7 @@ Display switching
>
> Note: on some machines (e.g. L3C), after the module has been loaded, only 0x6n
> events are generated and no actual switching occurs. In such a case, a line
> - like:
> + like::
>
> echo $((10#$arg-60)) > /sys/devices/platform/asus-laptop/display
>
> @@ -180,15 +192,16 @@ LED display
> several items of information.
>
> LED display works for the following models:
> - W1000N
> - W1J
>
> - To control the LED display, use the following :
> + - W1000N
> + - W1J
> +
> + 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,
> - according to the tables below.
> + according to the tables below::
>
> DDD (digits)
> 000 to 999 = display digits
> @@ -208,8 +221,8 @@ LED display
> For example "echo 0x01000001 >/sys/devices/platform/asus-laptop/ledd"
> would display "DVD001".
>
> -Driver options:
> ----------------
> +Driver options
> +--------------
>
> Options can be passed to the asus-laptop driver using the standard
> module argument syntax (<param>=<value> when passing the option to the
> @@ -219,6 +232,7 @@ Driver options:
> wapf: WAPF defines the behavior of the Fn+Fx wlan key
> The significance of values is yet to be found, but
> most of the time:
> +
> - 0x0 should do nothing
> - 0x1 should allow to control the device with Fn+Fx key.
> - 0x4 should send an ACPI event (0x88) while pressing the Fn+Fx key
> @@ -237,7 +251,7 @@ Unsupported models
> - ASUS L7300G
> - ASUS L8400
>
> -Patches, Errors, Questions:
> +Patches, Errors, Questions
> --------------------------
>
> I appreciate any success or failure
> @@ -253,5 +267,5 @@ Patches, Errors, Questions:
> Any other comments or patches are also more than welcome.
>
> acpi4asus-user@lists.sourceforge.net
> +
> http://sourceforge.net/projects/acpi4asus
> -
> diff --git a/Documentation/laptops/disk-shock-protection.txt b/Documentation/laptops/disk-shock-protection.rst
> similarity index 91%
> rename from Documentation/laptops/disk-shock-protection.txt
> rename to Documentation/laptops/disk-shock-protection.rst
> index 0e6ba2663834..e97c5f78d8c3 100644
> --- a/Documentation/laptops/disk-shock-protection.txt
> +++ b/Documentation/laptops/disk-shock-protection.rst
> @@ -1,17 +1,18 @@
> +==========================
> Hard disk shock protection
> ==========================
>
> Author: Elias Oltmanns <eo@nebensachen.de>
> +
> Last modified: 2008-10-03
>
>
> -0. Contents
> ------------
> +.. 0. Contents
>
> -1. Intro
> -2. The interface
> -3. References
> -4. CREDITS
> + 1. Intro
> + 2. The interface
> + 3. References
> + 4. CREDITS
>
>
> 1. Intro
> @@ -36,8 +37,8 @@ that).
> ----------------
>
> For each ATA device, the kernel exports the file
> -block/*/device/unload_heads in sysfs (here assumed to be mounted under
> -/sys). Access to /sys/block/*/device/unload_heads is denied with
> +`block/*/device/unload_heads` in sysfs (here assumed to be mounted under
> +/sys). Access to `/sys/block/*/device/unload_heads` is denied with
> -EOPNOTSUPP if the device does not support the unload feature.
> Otherwise, writing an integer value to this file will take the heads
> of the respective drive off the platter and block all I/O operations
> @@ -54,18 +55,18 @@ cancel a previously set timeout and resume normal operation
> immediately by specifying a timeout of 0. Values below -2 are rejected
> with -EINVAL (see below for the special meaning of -1 and -2). If the
> timeout specified for a recent head park request has not yet expired,
> -reading from /sys/block/*/device/unload_heads will report the number
> +reading from `/sys/block/*/device/unload_heads` will report the number
> of milliseconds remaining until normal operation will be resumed;
> otherwise, reading the unload_heads attribute will return 0.
>
> For example, do the following in order to park the heads of drive
> -/dev/sda and stop all I/O operations for five seconds:
> +/dev/sda and stop all I/O operations for five seconds::
>
> -# echo 5000 > /sys/block/sda/device/unload_heads
> + # echo 5000 > /sys/block/sda/device/unload_heads
>
> -A simple
> +A simple::
>
> -# cat /sys/block/sda/device/unload_heads
> + # cat /sys/block/sda/device/unload_heads
>
> will show you how many milliseconds are left before normal operation
> will be resumed.
> @@ -112,9 +113,9 @@ unload_heads attribute. If you know that your device really does
> support the unload feature (for instance, because the vendor of your
> laptop or the hard drive itself told you so), then you can tell the
> kernel to enable the usage of this feature for that drive by writing
> -the special value -1 to the unload_heads attribute:
> +the special value -1 to the unload_heads attribute::
>
> -# echo -1 > /sys/block/sda/device/unload_heads
> + # echo -1 > /sys/block/sda/device/unload_heads
>
> will enable the feature for /dev/sda, and giving -2 instead of -1 will
> disable it again.
> @@ -135,6 +136,7 @@ for use. Please feel free to add projects that have been the victims
> of my ignorance.
>
> - http://www.thinkwiki.org/wiki/HDAPS
> +
> See this page for information about Linux support of the hard disk
> active protection system as implemented in IBM/Lenovo Thinkpads.
>
> diff --git a/Documentation/laptops/index.rst b/Documentation/laptops/index.rst
> new file mode 100644
> index 000000000000..001a30910d09
> --- /dev/null
> +++ b/Documentation/laptops/index.rst
> @@ -0,0 +1,17 @@
> +:orphan:
> +
> +==============
> +Laptop Drivers
> +==============
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + asus-laptop
> + disk-shock-protection
> + laptop-mode
> + lg-laptop
> + sony-laptop
> + sonypi
> + thinkpad-acpi
> + toshiba_haps
> diff --git a/Documentation/laptops/laptop-mode.txt b/Documentation/laptops/laptop-mode.rst
> similarity index 62%
> rename from Documentation/laptops/laptop-mode.txt
> rename to Documentation/laptops/laptop-mode.rst
> index 1c707fc9b141..c984c4262f2e 100644
> --- a/Documentation/laptops/laptop-mode.txt
> +++ b/Documentation/laptops/laptop-mode.rst
> @@ -1,8 +1,11 @@
> +===============================================
> How to conserve battery power using laptop-mode
> ------------------------------------------------
> +===============================================
>
> Document Author: Bart Samwel (bart@samwel.tk)
> +
> Date created: January 2, 2004
> +
> Last modified: December 06, 2004
>
> Introduction
> @@ -12,17 +15,16 @@ Laptop mode is used to minimize the time that the hard disk needs to be spun up,
> to conserve battery power on laptops. It has been reported to cause significant
> power savings.
>
> -Contents
> ---------
> +.. Contents
>
> -* Introduction
> -* Installation
> -* Caveats
> -* The Details
> -* Tips & Tricks
> -* Control script
> -* ACPI integration
> -* Monitoring tool
> + * Introduction
> + * Installation
> + * Caveats
> + * The Details
> + * Tips & Tricks
> + * Control script
> + * ACPI integration
> + * Monitoring tool
>
>
> Installation
> @@ -33,7 +35,7 @@ or anything. Simply install all the files included in this document, and
> laptop mode will automatically be started when you're on battery. For
> your convenience, a tarball containing an installer can be downloaded at:
>
> -http://www.samwel.tk/laptop_mode/laptop_mode/
> + http://www.samwel.tk/laptop_mode/laptop_mode/
>
> To configure laptop mode, you need to edit the configuration file, which is
> located in /etc/default/laptop-mode on Debian-based systems, or in
> @@ -209,7 +211,7 @@ Tips & Tricks
> this on powerbooks too. I hope that this is a piece of information that
> might be useful to the Laptop Mode patch or its users."
>
> -* In syslog.conf, you can prefix entries with a dash ``-'' to omit syncing the
> +* In syslog.conf, you can prefix entries with a dash `-` to omit syncing the
> file after every logging. When you're using laptop-mode and your disk doesn't
> spin down, this is a likely culprit.
>
> @@ -233,83 +235,82 @@ configuration file
> It should be installed as /etc/default/laptop-mode on Debian, and as
> /etc/sysconfig/laptop-mode on Red Hat, SUSE, Mandrake, and other work-alikes.
>
> ---------------------CONFIG FILE BEGIN-------------------------------------------
> -# Maximum time, in seconds, of hard drive spindown time that you are
> -# comfortable with. Worst case, it's possible that you could lose this
> -# amount of work if your battery fails you while in laptop mode.
> -#MAX_AGE=600
> +Config file::
>
> -# Automatically disable laptop mode when the number of minutes of battery
> -# that you have left goes below this threshold.
> -MINIMUM_BATTERY_MINUTES=10
> + # Maximum time, in seconds, of hard drive spindown time that you are
> + # comfortable with. Worst case, it's possible that you could lose this
> + # amount of work if your battery fails you while in laptop mode.
> + #MAX_AGE=600
>
> -# Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
> -# by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
> -# will read a complete MP3 at once, and will then spin down while the MP3/OGG is
> -# playing.
> -#READAHEAD=4096
> + # Automatically disable laptop mode when the number of minutes of battery
> + # that you have left goes below this threshold.
> + MINIMUM_BATTERY_MINUTES=10
>
> -# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
> -#DO_REMOUNTS=1
> + # Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
> + # by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
> + # will read a complete MP3 at once, and will then spin down while the MP3/OGG is
> + # playing.
> + #READAHEAD=4096
>
> -# And shall we add the "noatime" option to that as well? (1=yes)
> -#DO_REMOUNT_NOATIME=1
> + # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
> + #DO_REMOUNTS=1
>
> -# Dirty synchronous ratio. At this percentage of dirty pages the process
> -# which
> -# calls write() does its own writeback
> -#DIRTY_RATIO=40
> + # And shall we add the "noatime" option to that as well? (1=yes)
> + #DO_REMOUNT_NOATIME=1
>
> -#
> -# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
> -# exceeded, the kernel will wake flusher threads which will then reduce the
> -# amount of dirty memory to dirty_background_ratio. Set this nice and low,
> -# so once some writeout has commenced, we do a lot of it.
> -#
> -#DIRTY_BACKGROUND_RATIO=5
> + # Dirty synchronous ratio. At this percentage of dirty pages the process
> + # which
> + # calls write() does its own writeback
> + #DIRTY_RATIO=40
>
> -# kernel default dirty buffer age
> -#DEF_AGE=30
> -#DEF_UPDATE=5
> -#DEF_DIRTY_BACKGROUND_RATIO=10
> -#DEF_DIRTY_RATIO=40
> -#DEF_XFS_AGE_BUFFER=15
> -#DEF_XFS_SYNC_INTERVAL=30
> -#DEF_XFS_BUFD_INTERVAL=1
> + #
> + # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
> + # exceeded, the kernel will wake flusher threads which will then reduce the
> + # amount of dirty memory to dirty_background_ratio. Set this nice and low,
> + # so once some writeout has commenced, we do a lot of it.
> + #
> + #DIRTY_BACKGROUND_RATIO=5
>
> -# This must be adjusted manually to the value of HZ in the running kernel
> -# on 2.4, until the XFS people change their 2.4 external interfaces to work in
> -# centisecs. This can be automated, but it's a work in progress that still
> -# needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
> -# external interfaces, and that is currently always set to 100. So you don't
> -# need to change this on 2.6.
> -#XFS_HZ=100
> + # kernel default dirty buffer age
> + #DEF_AGE=30
> + #DEF_UPDATE=5
> + #DEF_DIRTY_BACKGROUND_RATIO=10
> + #DEF_DIRTY_RATIO=40
> + #DEF_XFS_AGE_BUFFER=15
> + #DEF_XFS_SYNC_INTERVAL=30
> + #DEF_XFS_BUFD_INTERVAL=1
>
> -# Should the maximum CPU frequency be adjusted down while on battery?
> -# Requires CPUFreq to be setup.
> -# See Documentation/admin-guide/pm/cpufreq.rst for more info
> -#DO_CPU=0
> + # This must be adjusted manually to the value of HZ in the running kernel
> + # on 2.4, until the XFS people change their 2.4 external interfaces to work in
> + # centisecs. This can be automated, but it's a work in progress that still
> + # needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
> + # external interfaces, and that is currently always set to 100. So you don't
> + # need to change this on 2.6.
> + #XFS_HZ=100
>
> -# When on battery what is the maximum CPU speed that the system should
> -# use? Legal values are "slowest" for the slowest speed that your
> -# CPU is able to operate at, or a value listed in:
> -# /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
> -# Only applicable if DO_CPU=1.
> -#CPU_MAXFREQ=slowest
> + # Should the maximum CPU frequency be adjusted down while on battery?
> + # Requires CPUFreq to be setup.
> + # See Documentation/admin-guide/pm/cpufreq.rst for more info
> + #DO_CPU=0
>
> -# Idle timeout for your hard drive (man hdparm for valid values, -S option)
> -# Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
> -#AC_HD=244
> -#BATT_HD=4
> + # When on battery what is the maximum CPU speed that the system should
> + # use? Legal values are "slowest" for the slowest speed that your
> + # CPU is able to operate at, or a value listed in:
> + # /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
> + # Only applicable if DO_CPU=1.
> + #CPU_MAXFREQ=slowest
>
> -# The drives for which to adjust the idle timeout. Separate them by a space,
> -# e.g. HD="/dev/hda /dev/hdb".
> -#HD="/dev/hda"
> + # Idle timeout for your hard drive (man hdparm for valid values, -S option)
> + # Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
> + #AC_HD=244
> + #BATT_HD=4
>
> -# Set the spindown timeout on a hard drive?
> -#DO_HD=1
> + # The drives for which to adjust the idle timeout. Separate them by a space,
> + # e.g. HD="/dev/hda /dev/hdb".
> + #HD="/dev/hda"
>
> ---------------------CONFIG FILE END---------------------------------------------
> + # Set the spindown timeout on a hard drive?
> + #DO_HD=1
>
>
> Control script
> @@ -318,125 +319,126 @@ Control script
> Please note that this control script works for the Linux 2.4 and 2.6 series (thanks
> to Kiko Piris).
>
> ---------------------CONTROL SCRIPT BEGIN----------------------------------------
> -#!/bin/bash
> +Control script::
>
> -# start or stop laptop_mode, best run by a power management daemon when
> -# ac gets connected/disconnected from a laptop
> -#
> -# install as /sbin/laptop_mode
> -#
> -# Contributors to this script: Kiko Piris
> -# Bart Samwel
> -# Micha Feigin
> -# Andrew Morton
> -# Herve Eychenne
> -# Dax Kelson
> -#
> -# Original Linux 2.4 version by: Jens Axboe
> + #!/bin/bash
>
> -#############################################################################
> + # start or stop laptop_mode, best run by a power management daemon when
> + # ac gets connected/disconnected from a laptop
> + #
> + # install as /sbin/laptop_mode
> + #
> + # Contributors to this script: Kiko Piris
> + # Bart Samwel
> + # Micha Feigin
> + # Andrew Morton
> + # Herve Eychenne
> + # Dax Kelson
> + #
> + # Original Linux 2.4 version by: Jens Axboe
>
> -# Source config
> -if [ -f /etc/default/laptop-mode ] ; then
> + #############################################################################
> +
> + # Source config
> + if [ -f /etc/default/laptop-mode ] ; then
> # Debian
> . /etc/default/laptop-mode
> -elif [ -f /etc/sysconfig/laptop-mode ] ; then
> + elif [ -f /etc/sysconfig/laptop-mode ] ; then
> # Others
> - . /etc/sysconfig/laptop-mode
> -fi
> + . /etc/sysconfig/laptop-mode
> + fi
>
> -# Don't raise an error if the config file is incomplete
> -# set defaults instead:
> + # Don't raise an error if the config file is incomplete
> + # set defaults instead:
>
> -# Maximum time, in seconds, of hard drive spindown time that you are
> -# comfortable with. Worst case, it's possible that you could lose this
> -# amount of work if your battery fails you while in laptop mode.
> -MAX_AGE=${MAX_AGE:-'600'}
> + # Maximum time, in seconds, of hard drive spindown time that you are
> + # comfortable with. Worst case, it's possible that you could lose this
> + # amount of work if your battery fails you while in laptop mode.
> + MAX_AGE=${MAX_AGE:-'600'}
>
> -# Read-ahead, in kilobytes
> -READAHEAD=${READAHEAD:-'4096'}
> + # Read-ahead, in kilobytes
> + READAHEAD=${READAHEAD:-'4096'}
>
> -# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
> -DO_REMOUNTS=${DO_REMOUNTS:-'1'}
> + # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
> + DO_REMOUNTS=${DO_REMOUNTS:-'1'}
>
> -# And shall we add the "noatime" option to that as well? (1=yes)
> -DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
> + # And shall we add the "noatime" option to that as well? (1=yes)
> + DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
>
> -# Shall we adjust the idle timeout on a hard drive?
> -DO_HD=${DO_HD:-'1'}
> + # Shall we adjust the idle timeout on a hard drive?
> + DO_HD=${DO_HD:-'1'}
>
> -# Adjust idle timeout on which hard drive?
> -HD="${HD:-'/dev/hda'}"
> + # Adjust idle timeout on which hard drive?
> + HD="${HD:-'/dev/hda'}"
>
> -# spindown time for HD (hdparm -S values)
> -AC_HD=${AC_HD:-'244'}
> -BATT_HD=${BATT_HD:-'4'}
> + # spindown time for HD (hdparm -S values)
> + AC_HD=${AC_HD:-'244'}
> + BATT_HD=${BATT_HD:-'4'}
>
> -# Dirty synchronous ratio. At this percentage of dirty pages the process which
> -# calls write() does its own writeback
> -DIRTY_RATIO=${DIRTY_RATIO:-'40'}
> + # Dirty synchronous ratio. At this percentage of dirty pages the process which
> + # calls write() does its own writeback
> + DIRTY_RATIO=${DIRTY_RATIO:-'40'}
>
> -# cpu frequency scaling
> -# See Documentation/admin-guide/pm/cpufreq.rst for more info
> -DO_CPU=${CPU_MANAGE:-'0'}
> -CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
> + # cpu frequency scaling
> + # See Documentation/admin-guide/pm/cpufreq.rst for more info
> + DO_CPU=${CPU_MANAGE:-'0'}
> + CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
>
> -#
> -# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
> -# exceeded, the kernel will wake flusher threads which will then reduce the
> -# amount of dirty memory to dirty_background_ratio. Set this nice and low,
> -# so once some writeout has commenced, we do a lot of it.
> -#
> -DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
> + #
> + # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
> + # exceeded, the kernel will wake flusher threads which will then reduce the
> + # amount of dirty memory to dirty_background_ratio. Set this nice and low,
> + # so once some writeout has commenced, we do a lot of it.
> + #
> + DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
>
> -# kernel default dirty buffer age
> -DEF_AGE=${DEF_AGE:-'30'}
> -DEF_UPDATE=${DEF_UPDATE:-'5'}
> -DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
> -DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
> -DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
> -DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
> -DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
> + # kernel default dirty buffer age
> + DEF_AGE=${DEF_AGE:-'30'}
> + DEF_UPDATE=${DEF_UPDATE:-'5'}
> + DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
> + DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
> + DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
> + DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
> + DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
>
> -# This must be adjusted manually to the value of HZ in the running kernel
> -# on 2.4, until the XFS people change their 2.4 external interfaces to work in
> -# centisecs. This can be automated, but it's a work in progress that still needs
> -# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
> -# interfaces, and that is currently always set to 100. So you don't need to
> -# change this on 2.6.
> -XFS_HZ=${XFS_HZ:-'100'}
> + # This must be adjusted manually to the value of HZ in the running kernel
> + # on 2.4, until the XFS people change their 2.4 external interfaces to work in
> + # centisecs. This can be automated, but it's a work in progress that still needs
> + # some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
> + # interfaces, and that is currently always set to 100. So you don't need to
> + # change this on 2.6.
> + XFS_HZ=${XFS_HZ:-'100'}
>
> -#############################################################################
> + #############################################################################
>
> -KLEVEL="$(uname -r |
> - {
> + KLEVEL="$(uname -r |
> + {
> IFS='.' read a b c
> echo $a.$b
> }
> -)"
> -case "$KLEVEL" in
> + )"
> + case "$KLEVEL" in
> "2.4"|"2.6")
> ;;
> *)
> echo "Unhandled kernel version: $KLEVEL ('uname -r' = '$(uname -r)')" >&2
> exit 1
> ;;
> -esac
> + esac
>
> -if [ ! -e /proc/sys/vm/laptop_mode ] ; then
> + if [ ! -e /proc/sys/vm/laptop_mode ] ; then
> echo "Kernel is not patched with laptop_mode patch." >&2
> exit 1
> -fi
> + fi
>
> -if [ ! -w /proc/sys/vm/laptop_mode ] ; then
> + if [ ! -w /proc/sys/vm/laptop_mode ] ; then
> echo "You do not have enough privileges to enable laptop_mode." >&2
> exit 1
> -fi
> + fi
>
> -# Remove an option (the first parameter) of the form option=<number> from
> -# a mount options string (the rest of the parameters).
> -parse_mount_opts () {
> + # Remove an option (the first parameter) of the form option=<number> from
> + # a mount options string (the rest of the parameters).
> + parse_mount_opts () {
> OPT="$1"
> shift
> echo ",$*," | sed \
> @@ -444,11 +446,11 @@ parse_mount_opts () {
> -e 's/,,*/,/g' \
> -e 's/^,//' \
> -e 's/,$//'
> -}
> + }
>
> -# Remove an option (the first parameter) without any arguments from
> -# a mount option string (the rest of the parameters).
> -parse_nonumber_mount_opts () {
> + # Remove an option (the first parameter) without any arguments from
> + # a mount option string (the rest of the parameters).
> + parse_nonumber_mount_opts () {
> OPT="$1"
> shift
> echo ",$*," | sed \
> @@ -456,20 +458,20 @@ parse_nonumber_mount_opts () {
> -e 's/,,*/,/g' \
> -e 's/^,//' \
> -e 's/,$//'
> -}
> + }
>
> -# Find out the state of a yes/no option (e.g. "atime"/"noatime") in
> -# fstab for a given filesystem, and use this state to replace the
> -# value of the option in another mount options string. The device
> -# is the first argument, the option name the second, and the default
> -# value the third. The remainder is the mount options string.
> -#
> -# Example:
> -# parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
> -#
> -# If fstab contains, say, "rw" for this filesystem, then the result
> -# will be "defaults,atime".
> -parse_yesno_opts_wfstab () {
> + # Find out the state of a yes/no option (e.g. "atime"/"noatime") in
> + # fstab for a given filesystem, and use this state to replace the
> + # value of the option in another mount options string. The device
> + # is the first argument, the option name the second, and the default
> + # value the third. The remainder is the mount options string.
> + #
> + # Example:
> + # parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
> + #
> + # If fstab contains, say, "rw" for this filesystem, then the result
> + # will be "defaults,atime".
> + parse_yesno_opts_wfstab () {
> L_DEV="$1"
> OPT="$2"
> DEF_OPT="$3"
> @@ -491,21 +493,21 @@ parse_yesno_opts_wfstab () {
> # option not specified in fstab -- choose the default.
> echo "$PARSEDOPTS1,$DEF_OPT"
> fi
> -}
> + }
>
> -# Find out the state of a numbered option (e.g. "commit=NNN") in
> -# fstab for a given filesystem, and use this state to replace the
> -# value of the option in another mount options string. The device
> -# is the first argument, and the option name the second. The
> -# remainder is the mount options string in which the replacement
> -# must be done.
> -#
> -# Example:
> -# parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
> -#
> -# If fstab contains, say, "commit=3,rw" for this filesystem, then the
> -# result will be "rw,commit=3".
> -parse_mount_opts_wfstab () {
> + # Find out the state of a numbered option (e.g. "commit=NNN") in
> + # fstab for a given filesystem, and use this state to replace the
> + # value of the option in another mount options string. The device
> + # is the first argument, and the option name the second. The
> + # remainder is the mount options string in which the replacement
> + # must be done.
> + #
> + # Example:
> + # parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
> + #
> + # If fstab contains, say, "commit=3,rw" for this filesystem, then the
> + # result will be "rw,commit=3".
> + parse_mount_opts_wfstab () {
> L_DEV="$1"
> OPT="$2"
> shift 2
> @@ -523,9 +525,9 @@ parse_mount_opts_wfstab () {
> # option not specified in fstab: set it to 0
> echo "$PARSEDOPTS1,$OPT=0"
> fi
> -}
> + }
>
> -deduce_fstype () {
> + deduce_fstype () {
> MP="$1"
> # My root filesystem unfortunately has
> # type "unknown" in /etc/mtab. If we encounter
> @@ -538,13 +540,13 @@ deduce_fstype () {
> exit 0
> fi
> done
> -}
> + }
>
> -if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
> + if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
> NOATIME_OPT=",noatime"
> -fi
> + fi
>
> -case "$1" in
> + case "$1" in
> start)
> AGE=$((100*$MAX_AGE))
> XFS_AGE=$(($XFS_HZ*$MAX_AGE))
> @@ -687,10 +689,9 @@ case "$1" in
> exit 1
> ;;
>
> -esac
> + esac
>
> -exit 0
> ---------------------CONTROL SCRIPT END------------------------------------------
> + exit 0
>
>
> ACPI integration
> @@ -701,78 +702,76 @@ kick off the laptop_mode script and run hdparm. The part that
> automatically disables laptop mode when the battery is low was
> written by Jan Topinski.
>
> ------------------/etc/acpi/events/ac_adapter BEGIN------------------------------
> -event=ac_adapter
> -action=/etc/acpi/actions/ac.sh %e
> -----------------/etc/acpi/events/ac_adapter END---------------------------------
> +/etc/acpi/events/ac_adapter::
>
> + event=ac_adapter
> + action=/etc/acpi/actions/ac.sh %e
>
> ------------------/etc/acpi/events/battery BEGIN---------------------------------
> -event=battery.*
> -action=/etc/acpi/actions/battery.sh %e
> -----------------/etc/acpi/events/battery END------------------------------------
> +/etc/acpi/events/battery::
>
> + event=battery.*
> + action=/etc/acpi/actions/battery.sh %e
>
> -----------------/etc/acpi/actions/ac.sh BEGIN-----------------------------------
> -#!/bin/bash
> +/etc/acpi/actions/ac.sh::
>
> -# ac on/offline event handler
> + #!/bin/bash
>
> -status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
> + # ac on/offline event handler
>
> -case $status in
> - "on-line")
> - /sbin/laptop_mode stop
> - exit 0
> - ;;
> - "off-line")
> - /sbin/laptop_mode start
> - exit 0
> - ;;
> -esac
> ----------------------------/etc/acpi/actions/ac.sh END--------------------------
> + status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
>
> + case $status in
> + "on-line")
> + /sbin/laptop_mode stop
> + exit 0
> + ;;
> + "off-line")
> + /sbin/laptop_mode start
> + exit 0
> + ;;
> + esac
>
> ----------------------------/etc/acpi/actions/battery.sh BEGIN-------------------
> -#! /bin/bash
>
> -# Automatically disable laptop mode when the battery almost runs out.
> +/etc/acpi/actions/battery.sh::
>
> -BATT_INFO=/proc/acpi/battery/$2/state
> + #! /bin/bash
>
> -if [[ -f /proc/sys/vm/laptop_mode ]]
> -then
> - LM=`cat /proc/sys/vm/laptop_mode`
> - if [[ $LM -gt 0 ]]
> - then
> - if [[ -f $BATT_INFO ]]
> + # Automatically disable laptop mode when the battery almost runs out.
> +
> + BATT_INFO=/proc/acpi/battery/$2/state
> +
> + if [[ -f /proc/sys/vm/laptop_mode ]]
> + then
> + LM=`cat /proc/sys/vm/laptop_mode`
> + if [[ $LM -gt 0 ]]
> then
> - # Source the config file only now that we know we need
> - if [ -f /etc/default/laptop-mode ] ; then
> - # Debian
> - . /etc/default/laptop-mode
> - elif [ -f /etc/sysconfig/laptop-mode ] ; then
> - # Others
> - . /etc/sysconfig/laptop-mode
> - fi
> - MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
> + if [[ -f $BATT_INFO ]]
> + then
> + # Source the config file only now that we know we need
> + if [ -f /etc/default/laptop-mode ] ; then
> + # Debian
> + . /etc/default/laptop-mode
> + elif [ -f /etc/sysconfig/laptop-mode ] ; then
> + # Others
> + . /etc/sysconfig/laptop-mode
> + fi
> + MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
>
> - ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
> - if [[ ACTION -eq "discharging" ]]
> - then
> - PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
> - REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
> - fi
> - if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
> - then
> - /sbin/laptop_mode stop
> - fi
> - else
> - logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
> + ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
> + if [[ ACTION -eq "discharging" ]]
> + then
> + PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
> + REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
> + fi
> + if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
> + then
> + /sbin/laptop_mode stop
> + fi
> + else
> + logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
> + fi
> fi
> - fi
> -fi
> ----------------------------/etc/acpi/actions/battery.sh END--------------------
> + fi
>
>
> Monitoring tool
> diff --git a/Documentation/laptops/sony-laptop.txt b/Documentation/laptops/sony-laptop.rst
> similarity index 85%
> rename from Documentation/laptops/sony-laptop.txt
> rename to Documentation/laptops/sony-laptop.rst
> index 978b1e615155..9edcc7f6612f 100644
> --- a/Documentation/laptops/sony-laptop.txt
> +++ b/Documentation/laptops/sony-laptop.rst
> @@ -1,7 +1,9 @@
> +=========================================
> Sony Notebook Control Driver (SNC) Readme
> ------------------------------------------
> - Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
> - Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
> +=========================================
> +
> + - Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
> + - Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
>
> This mini-driver drives the SNC and SPIC device present in the ACPI BIOS of the
> Sony Vaio laptops. This driver mixes both devices functions under the same
> @@ -10,6 +12,7 @@ obsoleted by sony-laptop now.
>
> Fn keys (hotkeys):
> ------------------
> +
> Some models report hotkeys through the SNC or SPIC devices, such events are
> reported both through the ACPI subsystem as acpi events and through the INPUT
> subsystem. See the logs of /proc/bus/input/devices to find out what those
> @@ -28,11 +31,14 @@ If your laptop model supports it, you will find sysfs files in the
> /sys/class/backlight/sony/
> directory. You will be able to query and set the current screen
> brightness:
> +
> + ====================== =========================================
> brightness get/set screen brightness (an integer
> between 0 and 7)
> actual_brightness reading from this file will query the HW
> to get real brightness value
> max_brightness the maximum brightness value
> + ====================== =========================================
>
>
> Platform specific:
> @@ -45,6 +51,8 @@ You then read/write integer values from/to those files by using
> standard UNIX tools.
>
> The files are:
> +
> + ====================== ==========================================
> brightness_default screen brightness which will be set
> when the laptop will be rebooted
> cdpower power on/off the internal CD drive
> @@ -53,21 +61,39 @@ The files are:
> (only in debug mode)
> bluetoothpower power on/off the internal bluetooth device
> fanspeed get/set the fan speed
> + ====================== ==========================================
>
> Note that some files may be missing if they are not supported
> by your particular laptop model.
>
> -Example usage:
> +Example usage::
> +
> # echo "1" > /sys/devices/platform/sony-laptop/brightness_default
> -sets the lowest screen brightness for the next and later reboots,
> +
> +sets the lowest screen brightness for the next and later reboots
> +
> +::
> +
> # echo "8" > /sys/devices/platform/sony-laptop/brightness_default
> -sets the highest screen brightness for the next and later reboots,
> +
> +sets the highest screen brightness for the next and later reboots
> +
> +::
> +
> # cat /sys/devices/platform/sony-laptop/brightness_default
> -retrieves the value.
> +
> +retrieves the value
> +
> +::
>
> # echo "0" > /sys/devices/platform/sony-laptop/audiopower
> -powers off the sound card,
> +
> +powers off the sound card
> +
> +::
> +
> # echo "1" > /sys/devices/platform/sony-laptop/audiopower
> +
> powers on the sound card.
>
>
> @@ -76,7 +102,8 @@ RFkill control:
> More recent Vaio models expose a consistent set of ACPI methods to
> control radio frequency emitting devices. If you are a lucky owner of
> such a laptop you will find the necessary rfkill devices under
> -/sys/class/rfkill. Check those starting with sony-* in
> +/sys/class/rfkill. Check those starting with sony-* in::
> +
> # grep . /sys/class/rfkill/*/{state,name}
>
>
> @@ -88,26 +115,29 @@ you are not afraid of any side effects doing strange things with
> your ACPI BIOS could have on your laptop), load the driver and
> pass the option 'debug=1'.
>
> -REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.
> +REPEAT:
> + **DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.**
>
> In your kernel logs you will find the list of all ACPI methods
> the SNC device has on your laptop.
>
> * For new models you will see a long list of meaningless method names,
> -reading the DSDT table source should reveal that:
> + reading the DSDT table source should reveal that:
> +
> (1) the SNC device uses an internal capability lookup table
> (2) SN00 is used to find values in the lookup table
> (3) SN06 and SN07 are used to call into the real methods based on
> offsets you can obtain iterating the table using SN00
> (4) SN02 used to enable events.
> +
> Some values in the capability lookup table are more or less known, see
> the code for all sony_call_snc_handle calls, others are more obscure.
>
> * For old models you can see the GCDP/GCDP methods used to pwer on/off
> -the CD drive, but there are others and they are usually different from
> -model to model.
> + the CD drive, but there are others and they are usually different from
> + model to model.
>
> -I HAVE NO IDEA WHAT THOSE METHODS DO.
> +**I HAVE NO IDEA WHAT THOSE METHODS DO.**
>
> The sony-laptop driver creates, for some of those methods (the most
> current ones found on several Vaio models), an entry under
> diff --git a/Documentation/laptops/sonypi.txt b/Documentation/laptops/sonypi.rst
> similarity index 87%
> rename from Documentation/laptops/sonypi.txt
> rename to Documentation/laptops/sonypi.rst
> index 606bdb9ce036..2a1975ed7ee4 100644
> --- a/Documentation/laptops/sonypi.txt
> +++ b/Documentation/laptops/sonypi.rst
> @@ -1,11 +1,13 @@
> +==================================================
> Sony Programmable I/O Control Device Driver Readme
> ---------------------------------------------------
> - Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
> - Copyright (C) 2001-2002 Alcôve <www.alcove.com>
> - Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
> - Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
> - Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
> - Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
> +==================================================
> +
> + - Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
> + - Copyright (C) 2001-2002 Alcôve <www.alcove.com>
> + - Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
> + - Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
> + - Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
> + - Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
>
> This driver enables access to the Sony Programmable I/O Control Device which
> can be found in many Sony Vaio laptops. Some newer Sony laptops (seems to be
> @@ -14,6 +16,7 @@ sonypi device and are not supported at all by this driver.
>
> It will give access (through a user space utility) to some events those laptops
> generate, like:
> +
> - jogdial events (the small wheel on the side of Vaios)
> - capture button events (only on Vaio Picturebook series)
> - Fn keys
> @@ -49,6 +52,7 @@ module argument syntax (<param>=<value> when passing the option to the
> module or sonypi.<param>=<value> on the kernel boot line when sonypi is
> statically linked into the kernel). Those options are:
>
> + =============== =======================================================
> minor: minor number of the misc device /dev/sonypi,
> default is -1 (automatic allocation, see /proc/misc
> or kernel logs)
> @@ -86,6 +90,8 @@ statically linked into the kernel). Those options are:
> will be tried. You can use the following bits to
> construct your own event mask (from
> drivers/char/sonypi.h):
> +
> + ======================== ======
> SONYPI_JOGGER_MASK 0x0001
> SONYPI_CAPTURE_MASK 0x0002
> SONYPI_FNKEY_MASK 0x0004
> @@ -100,22 +106,24 @@ statically linked into the kernel). Those options are:
> SONYPI_MEMORYSTICK_MASK 0x0800
> SONYPI_BATTERY_MASK 0x1000
> SONYPI_WIRELESS_MASK 0x2000
> + ======================== ======
>
> useinput: if set (which is the default) two input devices are
> created, one which interprets the jogdial events as
> mouse events, the other one which acts like a
> keyboard reporting the pressing of the special keys.
> + =============== =======================================================
>
> Module use:
> -----------
>
> In order to automatically load the sonypi module on use, you can put those
> -lines a configuration file in /etc/modprobe.d/:
> +lines a configuration file in /etc/modprobe.d/::
>
> alias char-major-10-250 sonypi
> options sonypi minor=250
>
> -This supposes the use of minor 250 for the sonypi device:
> +This supposes the use of minor 250 for the sonypi device::
>
> # mknod /dev/sonypi c 10 250
>
> @@ -148,5 +156,5 @@ Bugs:
> http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2
>
> - since all development was done by reverse engineering, there is
> - _absolutely no guarantee_ that this driver will not crash your
> + *absolutely no guarantee* that this driver will not crash your
> laptop. Permanently.
> diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.rst
> similarity index 89%
> rename from Documentation/laptops/thinkpad-acpi.txt
> rename to Documentation/laptops/thinkpad-acpi.rst
> index 75ef063622d2..19d52fc3c5e9 100644
> --- a/Documentation/laptops/thinkpad-acpi.txt
> +++ b/Documentation/laptops/thinkpad-acpi.rst
> @@ -1,12 +1,15 @@
> - ThinkPad ACPI Extras Driver
> +===========================
> +ThinkPad ACPI Extras Driver
> +===========================
>
> - Version 0.25
> - October 16th, 2013
> +Version 0.25
>
> - Borislav Deianov <borislav@users.sf.net>
> - Henrique de Moraes Holschuh <hmh@hmh.eng.br>
> - http://ibm-acpi.sf.net/
> +October 16th, 2013
>
> +- Borislav Deianov <borislav@users.sf.net>
> +- Henrique de Moraes Holschuh <hmh@hmh.eng.br>
> +
> +http://ibm-acpi.sf.net/
>
> This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
> supports various features of these laptops which are accessible
> @@ -91,7 +94,8 @@ yet ready or stabilized, it is expected that this interface will change,
> and any and all userspace programs must deal with it.
>
>
> -Notes about the sysfs interface:
> +Notes about the sysfs interface
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Unlike what was done with the procfs interface, correctness when talking
> to the sysfs interfaces will be enforced, as will correctness in the
> @@ -129,6 +133,7 @@ Driver version
> --------------
>
> procfs: /proc/acpi/ibm/driver
> +
> sysfs driver attribute: version
>
> The driver name and version. No commands can be written to this file.
> @@ -141,9 +146,13 @@ sysfs driver attribute: interface_version
>
> Version of the thinkpad-acpi sysfs interface, as an unsigned long
> (output in hex format: 0xAAAABBCC), where:
> - AAAA - major revision
> - BB - minor revision
> - CC - bugfix revision
> +
> + AAAA
> + - major revision
> + BB
> + - minor revision
> + CC
> + - bugfix revision
>
> The sysfs interface version changelog for the driver can be found at the
> end of this document. Changes to the sysfs interface done by the kernel
> @@ -170,6 +179,7 @@ Hot keys
> --------
>
> procfs: /proc/acpi/ibm/hotkey
> +
> sysfs device attribute: hotkey_*
>
> In a ThinkPad, the ACPI HKEY handler is responsible for communicating
> @@ -181,7 +191,7 @@ firmware will behave in many situations.
> The driver enables the HKEY ("hot key") event reporting automatically
> when loaded, and disables it when it is removed.
>
> -The driver will report HKEY events in the following format:
> +The driver will report HKEY events in the following format::
>
> ibm/hotkey HKEY 00000080 0000xxxx
>
> @@ -217,9 +227,10 @@ ThinkPads, it is still possible to support some extra hotkeys by
> polling the "CMOS NVRAM" at least 10 times per second. The driver
> attempts to enables this functionality automatically when required.
>
> -procfs notes:
> +procfs notes
> +^^^^^^^^^^^^
>
> -The following commands can be written to the /proc/acpi/ibm/hotkey file:
> +The following commands can be written to the /proc/acpi/ibm/hotkey file::
>
> echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
> echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
> @@ -227,7 +238,7 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file:
> echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
>
> The following commands have been deprecated and will cause the kernel
> -to log a warning:
> +to log a warning::
>
> echo enable > /proc/acpi/ibm/hotkey -- does nothing
> echo disable > /proc/acpi/ibm/hotkey -- returns an error
> @@ -237,7 +248,8 @@ maintain maximum bug-to-bug compatibility, it does not report any masks,
> nor does it allow one to manipulate the hot key mask when the firmware
> does not support masks at all, even if NVRAM polling is in use.
>
> -sysfs notes:
> +sysfs notes
> +^^^^^^^^^^^
>
> hotkey_bios_enabled:
> DEPRECATED, WILL BE REMOVED SOON.
> @@ -349,7 +361,8 @@ sysfs notes:
>
> This attribute has poll()/select() support.
>
> -input layer notes:
> +input layer notes
> +^^^^^^^^^^^^^^^^^
>
> A Hot key is mapped to a single input layer EV_KEY event, possibly
> followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
> @@ -362,11 +375,13 @@ remapping KEY_UNKNOWN keys.
>
> The events are available in an input device, with the following id:
>
> - Bus: BUS_HOST
> - vendor: 0x1014 (PCI_VENDOR_ID_IBM) or
> + ============== ==============================
> + Bus BUS_HOST
> + vendor 0x1014 (PCI_VENDOR_ID_IBM) or
> 0x17aa (PCI_VENDOR_ID_LENOVO)
> - product: 0x5054 ("TP")
> - version: 0x4101
> + product 0x5054 ("TP")
> + version 0x4101
> + ============== ==============================
>
> The version will have its LSB incremented if the keymap changes in a
> backwards-compatible way. The MSB shall always be 0x41 for this input
> @@ -380,9 +395,10 @@ backwards-compatible change for this input device.
>
> Thinkpad-acpi Hot Key event map (version 0x4101):
>
> +======= ======= ============== ==============================================
> ACPI Scan
> event code Key Notes
> -
> +======= ======= ============== ==============================================
> 0x1001 0x00 FN+F1 -
>
> 0x1002 0x01 FN+F2 IBM: battery (rare)
> @@ -426,7 +442,9 @@ event code Key Notes
> or toggle screen expand
>
> 0x1009 0x08 FN+F9 -
> - .. .. ..
> +
> +... ... ... ...
> +
> 0x100B 0x0A FN+F11 -
>
> 0x100C 0x0B FN+F12 Sleep to disk. You are always
> @@ -480,8 +498,11 @@ event code Key Notes
> 0x1018 0x17 THINKPAD ThinkPad/Access IBM/Lenovo key
>
> 0x1019 0x18 unknown
> -.. .. ..
> +
> +... ... ...
> +
> 0x1020 0x1F unknown
> +======= ======= ============== ==============================================
>
> The ThinkPad firmware does not allow one to differentiate when most hot
> keys are pressed or released (either that, or we don't know how to, yet).
> @@ -499,14 +520,17 @@ generate input device EV_KEY events.
> In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW
> events for switches:
>
> +============== ==============================================
> SW_RFKILL_ALL T60 and later hardware rfkill rocker switch
> SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A
> +============== ==============================================
>
> -Non hotkey ACPI HKEY event map:
> --------------------------------
> +Non hotkey ACPI HKEY event map
> +------------------------------
>
> Events that are never propagated by the driver:
>
> +====== ==================================================
> 0x2304 System is waking up from suspend to undock
> 0x2305 System is waking up from suspend to eject bay
> 0x2404 System is waking up from hibernation to undock
> @@ -519,10 +543,12 @@ Events that are never propagated by the driver:
> 0x6000 KEYBOARD: Numlock key pressed
> 0x6005 KEYBOARD: Fn key pressed (TO BE VERIFIED)
> 0x7000 Radio Switch may have changed state
> +====== ==================================================
>
>
> Events that are propagated by the driver to userspace:
>
> +====== =====================================================
> 0x2313 ALARM: System is waking up from suspend because
> the battery is nearly empty
> 0x2413 ALARM: System is waking up from hibernation because
> @@ -544,6 +570,7 @@ Events that are propagated by the driver to userspace:
> 0x6040 Nvidia Optimus/AC adapter related (TO BE VERIFIED)
> 0x60C0 X1 Yoga 2016, Tablet mode status changed
> 0x60F0 Thermal Transformation changed (GMTS, Windows)
> +====== =====================================================
>
> Battery nearly empty alarms are a last resort attempt to get the
> operating system to hibernate or shutdown cleanly (0x2313), or shutdown
> @@ -562,7 +589,8 @@ cycle, or a system shutdown. Obviously, something is very wrong if this
> happens.
>
>
> -Brightness hotkey notes:
> +Brightness hotkey notes
> +^^^^^^^^^^^^^^^^^^^^^^^
>
> Don't mess with the brightness hotkeys in a Thinkpad. If you want
> notifications for OSD, use the sysfs backlight class event support.
> @@ -579,7 +607,9 @@ Bluetooth
> ---------
>
> procfs: /proc/acpi/ibm/bluetooth
> +
> sysfs device attribute: bluetooth_enable (deprecated)
> +
> sysfs rfkill class: switch "tpacpi_bluetooth_sw"
>
> This feature shows the presence and current state of a ThinkPad
> @@ -588,22 +618,25 @@ Bluetooth device in the internal ThinkPad CDC slot.
> If the ThinkPad supports it, the Bluetooth state is stored in NVRAM,
> so it is kept across reboots and power-off.
>
> -Procfs notes:
> +Procfs notes
> +^^^^^^^^^^^^
>
> -If Bluetooth is installed, the following commands can be used:
> +If Bluetooth is installed, the following commands can be used::
>
> echo enable > /proc/acpi/ibm/bluetooth
> echo disable > /proc/acpi/ibm/bluetooth
>
> -Sysfs notes:
> +Sysfs notes
> +^^^^^^^^^^^
>
> If the Bluetooth CDC card is installed, it can be enabled /
> disabled through the "bluetooth_enable" thinkpad-acpi device
> attribute, and its current status can also be queried.
>
> enable:
> - 0: disables Bluetooth / Bluetooth is disabled
> - 1: enables Bluetooth / Bluetooth is enabled.
> +
> + - 0: disables Bluetooth / Bluetooth is disabled
> + - 1: enables Bluetooth / Bluetooth is enabled.
>
> Note: this interface has been superseded by the generic rfkill
> class. It has been deprecated, and it will be removed in year
> @@ -617,7 +650,7 @@ Video output control -- /proc/acpi/ibm/video
> --------------------------------------------
>
> This feature allows control over the devices used for video output -
> -LCD, CRT or DVI (if available). The following commands are available:
> +LCD, CRT or DVI (if available). The following commands are available::
>
> echo lcd_enable > /proc/acpi/ibm/video
> echo lcd_disable > /proc/acpi/ibm/video
> @@ -630,9 +663,10 @@ LCD, CRT or DVI (if available). The following commands are available:
> echo expand_toggle > /proc/acpi/ibm/video
> echo video_switch > /proc/acpi/ibm/video
>
> -NOTE: Access to this feature is restricted to processes owning the
> -CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
> -enough with some versions of X.org to crash it.
> +NOTE:
> + Access to this feature is restricted to processes owning the
> + CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
> + enough with some versions of X.org to crash it.
>
> Each video output device can be enabled or disabled individually.
> Reading /proc/acpi/ibm/video shows the status of each device.
> @@ -665,18 +699,21 @@ ThinkLight control
> ------------------
>
> procfs: /proc/acpi/ibm/light
> +
> sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED
>
> -procfs notes:
> +procfs notes
> +^^^^^^^^^^^^
>
> The ThinkLight status can be read and set through the procfs interface. A
> few models which do not make the status available will show the ThinkLight
> -status as "unknown". The available commands are:
> +status as "unknown". The available commands are::
>
> echo on > /proc/acpi/ibm/light
> echo off > /proc/acpi/ibm/light
>
> -sysfs notes:
> +sysfs notes
> +^^^^^^^^^^^
>
> The ThinkLight sysfs interface is documented by the LED class
> documentation, in Documentation/leds/leds-class.rst. The ThinkLight LED name
> @@ -691,6 +728,7 @@ CMOS/UCMS control
> -----------------
>
> procfs: /proc/acpi/ibm/cmos
> +
> sysfs device attribute: cmos_command
>
> This feature is mostly used internally by the ACPI firmware to keep the legacy
> @@ -707,16 +745,16 @@ The range of valid cmos command numbers is 0 to 21, but not all have an
> effect and the behavior varies from model to model. Here is the behavior
> on the X40 (tpb is the ThinkPad Buttons utility):
>
> - 0 - Related to "Volume down" key press
> - 1 - Related to "Volume up" key press
> - 2 - Related to "Mute on" key press
> - 3 - Related to "Access IBM" key press
> - 4 - Related to "LCD brightness up" key press
> - 5 - Related to "LCD brightness down" key press
> - 11 - Related to "toggle screen expansion" key press/function
> - 12 - Related to "ThinkLight on"
> - 13 - Related to "ThinkLight off"
> - 14 - Related to "ThinkLight" key press (toggle ThinkLight)
> + - 0 - Related to "Volume down" key press
> + - 1 - Related to "Volume up" key press
> + - 2 - Related to "Mute on" key press
> + - 3 - Related to "Access IBM" key press
> + - 4 - Related to "LCD brightness up" key press
> + - 5 - Related to "LCD brightness down" key press
> + - 11 - Related to "toggle screen expansion" key press/function
> + - 12 - Related to "ThinkLight on"
> + - 13 - Related to "ThinkLight off"
> + - 14 - Related to "ThinkLight" key press (toggle ThinkLight)
>
> The cmos command interface is prone to firmware split-brain problems, as
> in newer ThinkPads it is just a compatibility layer. Do not use it, it is
> @@ -748,9 +786,10 @@ are aware of the consequences are welcome to enabling it.
> Audio mute and microphone mute LEDs are supported, but currently not
> visible to userspace. They are used by the snd-hda-intel audio driver.
>
> -procfs notes:
> +procfs notes
> +^^^^^^^^^^^^
>
> -The available commands are:
> +The available commands are::
>
> echo '<LED number> on' >/proc/acpi/ibm/led
> echo '<LED number> off' >/proc/acpi/ibm/led
> @@ -760,23 +799,24 @@ The <LED number> range is 0 to 15. The set of LEDs that can be
> controlled varies from model to model. Here is the common ThinkPad
> mapping:
>
> - 0 - power
> - 1 - battery (orange)
> - 2 - battery (green)
> - 3 - UltraBase/dock
> - 4 - UltraBay
> - 5 - UltraBase battery slot
> - 6 - (unknown)
> - 7 - standby
> - 8 - dock status 1
> - 9 - dock status 2
> - 10, 11 - (unknown)
> - 12 - thinkvantage
> - 13, 14, 15 - (unknown)
> + - 0 - power
> + - 1 - battery (orange)
> + - 2 - battery (green)
> + - 3 - UltraBase/dock
> + - 4 - UltraBay
> + - 5 - UltraBase battery slot
> + - 6 - (unknown)
> + - 7 - standby
> + - 8 - dock status 1
> + - 9 - dock status 2
> + - 10, 11 - (unknown)
> + - 12 - thinkvantage
> + - 13, 14, 15 - (unknown)
>
> All of the above can be turned on and off and can be made to blink.
>
> -sysfs notes:
> +sysfs notes
> +^^^^^^^^^^^
>
> The ThinkPad LED sysfs interface is described in detail by the LED class
> documentation, in Documentation/leds/leds-class.rst.
> @@ -815,7 +855,7 @@ The BEEP method is used internally by the ACPI firmware to provide
> audible alerts in various situations. This feature allows the same
> sounds to be triggered manually.
>
> -The commands are non-negative integer numbers:
> +The commands are non-negative integer numbers::
>
> echo <number> >/proc/acpi/ibm/beep
>
> @@ -823,25 +863,26 @@ The valid <number> range is 0 to 17. Not all numbers trigger sounds
> and the sounds vary from model to model. Here is the behavior on the
> X40:
>
> - 0 - stop a sound in progress (but use 17 to stop 16)
> - 2 - two beeps, pause, third beep ("low battery")
> - 3 - single beep
> - 4 - high, followed by low-pitched beep ("unable")
> - 5 - single beep
> - 6 - very high, followed by high-pitched beep ("AC/DC")
> - 7 - high-pitched beep
> - 9 - three short beeps
> - 10 - very long beep
> - 12 - low-pitched beep
> - 15 - three high-pitched beeps repeating constantly, stop with 0
> - 16 - one medium-pitched beep repeating constantly, stop with 17
> - 17 - stop 16
> + - 0 - stop a sound in progress (but use 17 to stop 16)
> + - 2 - two beeps, pause, third beep ("low battery")
> + - 3 - single beep
> + - 4 - high, followed by low-pitched beep ("unable")
> + - 5 - single beep
> + - 6 - very high, followed by high-pitched beep ("AC/DC")
> + - 7 - high-pitched beep
> + - 9 - three short beeps
> + - 10 - very long beep
> + - 12 - low-pitched beep
> + - 15 - three high-pitched beeps repeating constantly, stop with 0
> + - 16 - one medium-pitched beep repeating constantly, stop with 17
> + - 17 - stop 16
>
>
> Temperature sensors
> -------------------
>
> procfs: /proc/acpi/ibm/thermal
> +
> sysfs device attributes: (hwmon "thinkpad") temp*_input
>
> Most ThinkPads include six or more separate temperature sensors but only
> @@ -850,10 +891,14 @@ feature shows readings from up to eight different sensors on older
> ThinkPads, and up to sixteen different sensors on newer ThinkPads.
>
> For example, on the X40, a typical output may be:
> -temperatures: 42 42 45 41 36 -128 33 -128
> +
> +temperatures:
> + 42 42 45 41 36 -128 33 -128
>
> On the T43/p, a typical output may be:
> -temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
> +
> +temperatures:
> + 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
>
> The mapping of thermal sensors to physical locations varies depending on
> system-board model (and thus, on ThinkPad model).
> @@ -863,46 +908,53 @@ tries to track down these locations for various models.
>
> Most (newer?) models seem to follow this pattern:
>
> -1: CPU
> -2: (depends on model)
> -3: (depends on model)
> -4: GPU
> -5: Main battery: main sensor
> -6: Bay battery: main sensor
> -7: Main battery: secondary sensor
> -8: Bay battery: secondary sensor
> -9-15: (depends on model)
> +- 1: CPU
> +- 2: (depends on model)
> +- 3: (depends on model)
> +- 4: GPU
> +- 5: Main battery: main sensor
> +- 6: Bay battery: main sensor
> +- 7: Main battery: secondary sensor
> +- 8: Bay battery: secondary sensor
> +- 9-15: (depends on model)
>
> For the R51 (source: Thomas Gruber):
> -2: Mini-PCI
> -3: Internal HDD
> +
> +- 2: Mini-PCI
> +- 3: Internal HDD
>
> For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
> http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
> -2: System board, left side (near PCMCIA slot), reported as HDAPS temp
> -3: PCMCIA slot
> -9: MCH (northbridge) to DRAM Bus
> -10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
> - card, under touchpad
> -11: Power regulator, underside of system board, below F2 key
> +
> +- 2: System board, left side (near PCMCIA slot), reported as HDAPS temp
> +- 3: PCMCIA slot
> +- 9: MCH (northbridge) to DRAM Bus
> +- 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
> + card, under touchpad
> +- 11: Power regulator, underside of system board, below F2 key
>
> The A31 has a very atypical layout for the thermal sensors
> (source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
> -1: CPU
> -2: Main Battery: main sensor
> -3: Power Converter
> -4: Bay Battery: main sensor
> -5: MCH (northbridge)
> -6: PCMCIA/ambient
> -7: Main Battery: secondary sensor
> -8: Bay Battery: secondary sensor
>
> +- 1: CPU
> +- 2: Main Battery: main sensor
> +- 3: Power Converter
> +- 4: Bay Battery: main sensor
> +- 5: MCH (northbridge)
> +- 6: PCMCIA/ambient
> +- 7: Main Battery: secondary sensor
> +- 8: Bay Battery: secondary sensor
> +
> +
> +Procfs notes
> +^^^^^^^^^^^^
>
> -Procfs notes:
> Readings from sensors that are not available return -128.
> No commands can be written to this file.
>
> -Sysfs notes:
> +Sysfs notes
> +^^^^^^^^^^^
> +
> Sensors that are not available return the ENXIO error. This
> status may change at runtime, as there are hotplug thermal
> sensors, like those inside the batteries and docks.
> @@ -921,6 +973,7 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec
>
> Use it to determine the register holding the fan
> speed on some models. To do that, do the following:
> +
> - make sure the battery is fully charged
> - make sure the fan is running
> - use above mentioned tool to read out the EC
> @@ -941,6 +994,7 @@ LCD brightness control
> ----------------------
>
> procfs: /proc/acpi/ibm/brightness
> +
> sysfs backlight device "thinkpad_screen"
>
> This feature allows software control of the LCD brightness on ThinkPad
> @@ -985,15 +1039,17 @@ brightness_enable=0 forces it to be disabled. brightness_enable=1
> forces it to be enabled when available, even if the standard ACPI
> interface is also available.
>
> -Procfs notes:
> +Procfs notes
> +^^^^^^^^^^^^
>
> - The available commands are:
> +The available commands are::
>
> echo up >/proc/acpi/ibm/brightness
> echo down >/proc/acpi/ibm/brightness
> echo 'level <level>' >/proc/acpi/ibm/brightness
>
> -Sysfs notes:
> +Sysfs notes
> +^^^^^^^^^^^
>
> The interface is implemented through the backlight sysfs class, which is
> poorly documented at this time.
> @@ -1038,6 +1094,7 @@ Volume control (Console Audio control)
> --------------------------------------
>
> procfs: /proc/acpi/ibm/volume
> +
> ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC"
>
> NOTE: by default, the volume control interface operates in read-only
> @@ -1053,7 +1110,8 @@ Software volume control should be done only in the main AC97/HDA
> mixer.
>
>
> -About the ThinkPad Console Audio control:
> +About the ThinkPad Console Audio control
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> ThinkPads have a built-in amplifier and muting circuit that drives the
> console headphone and speakers. This circuit is after the main AC97
> @@ -1092,13 +1150,14 @@ normal key presses to the operating system (thinkpad-acpi is not
> involved).
>
>
> -The ThinkPad-ACPI volume control:
> +The ThinkPad-ACPI volume control
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> The preferred way to interact with the Console Audio control is the
> ALSA interface.
>
> The legacy procfs interface allows one to read the current state,
> -and if volume control is enabled, accepts the following commands:
> +and if volume control is enabled, accepts the following commands::
>
> echo up >/proc/acpi/ibm/volume
> echo down >/proc/acpi/ibm/volume
> @@ -1137,13 +1196,15 @@ Fan control and monitoring: fan speed, fan enable/disable
> ---------------------------------------------------------
>
> procfs: /proc/acpi/ibm/fan
> -sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1,
> - pwm1_enable, fan2_input
> +
> +sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, pwm1_enable, fan2_input
> +
> sysfs hwmon driver attributes: fan_watchdog
>
> -NOTE NOTE NOTE: fan control operations are disabled by default for
> -safety reasons. To enable them, the module parameter "fan_control=1"
> -must be given to thinkpad-acpi.
> +NOTE NOTE NOTE:
> + fan control operations are disabled by default for
> + safety reasons. To enable them, the module parameter "fan_control=1"
> + must be given to thinkpad-acpi.
>
> This feature attempts to show the current fan speed, control mode and
> other fan data that might be available. The speed is read directly
> @@ -1154,7 +1215,8 @@ value on other models.
> Some Lenovo ThinkPads support a secondary fan. This fan cannot be
> controlled separately, it shares the main fan control.
>
> -Fan levels:
> +Fan levels
> +^^^^^^^^^^
>
> Most ThinkPad fans work in "levels" at the firmware interface. Level 0
> stops the fan. The higher the level, the higher the fan speed, although
> @@ -1209,9 +1271,10 @@ therefore, not suitable to protect against fan mode changes made through
> means other than the "enable", "disable", and "level" procfs fan
> commands, or the hwmon fan control sysfs interface.
>
> -Procfs notes:
> +Procfs notes
> +^^^^^^^^^^^^
>
> -The fan may be enabled or disabled with the following commands:
> +The fan may be enabled or disabled with the following commands::
>
> echo enable >/proc/acpi/ibm/fan
> echo disable >/proc/acpi/ibm/fan
> @@ -1219,7 +1282,7 @@ The fan may be enabled or disabled with the following commands:
> Placing a fan on level 0 is the same as disabling it. Enabling a fan
> will try to place it in a safe level if it is too slow or disabled.
>
> -The fan level can be controlled with the command:
> +The fan level can be controlled with the command::
>
> echo 'level <level>' > /proc/acpi/ibm/fan
>
> @@ -1231,7 +1294,7 @@ compatibility.
>
> On the X31 and X40 (and ONLY on those models), the fan speed can be
> controlled to a certain degree. Once the fan is running, it can be
> -forced to run faster or slower with the following command:
> +forced to run faster or slower with the following command::
>
> echo 'speed <speed>' > /proc/acpi/ibm/fan
>
> @@ -1241,13 +1304,14 @@ effect or the fan speed eventually settles somewhere in that range. The
> fan cannot be stopped or started with this command. This functionality
> is incomplete, and not available through the sysfs interface.
>
> -To program the safety watchdog, use the "watchdog" command.
> +To program the safety watchdog, use the "watchdog" command::
>
> echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
>
> If you want to disable the watchdog, use 0 as the interval.
>
> -Sysfs notes:
> +Sysfs notes
> +^^^^^^^^^^^
>
> The sysfs interface follows the hwmon subsystem guidelines for the most
> part, and the exception is the fan safety watchdog.
> @@ -1261,10 +1325,10 @@ to the firmware).
> Features not yet implemented by the driver return ENOSYS.
>
> hwmon device attribute pwm1_enable:
> - 0: PWM offline (fan is set to full-speed mode)
> - 1: Manual PWM control (use pwm1 to set fan level)
> - 2: Hardware PWM control (EC "auto" mode)
> - 3: reserved (Software PWM control, not implemented yet)
> + - 0: PWM offline (fan is set to full-speed mode)
> + - 1: Manual PWM control (use pwm1 to set fan level)
> + - 2: Hardware PWM control (EC "auto" mode)
> + - 3: reserved (Software PWM control, not implemented yet)
>
> Modes 0 and 2 are not supported by all ThinkPads, and the
> driver is not always able to detect this. If it does know a
> @@ -1304,7 +1368,9 @@ WAN
> ---
>
> procfs: /proc/acpi/ibm/wan
> +
> sysfs device attribute: wwan_enable (deprecated)
> +
> sysfs rfkill class: switch "tpacpi_wwan_sw"
>
> This feature shows the presence and current state of the built-in
> @@ -1316,22 +1382,24 @@ so it is kept across reboots and power-off.
> It was tested on a Lenovo ThinkPad X60. It should probably work on other
> ThinkPad models which come with this module installed.
>
> -Procfs notes:
> +Procfs notes
> +^^^^^^^^^^^^
>
> -If the W-WAN card is installed, the following commands can be used:
> +If the W-WAN card is installed, the following commands can be used::
>
> echo enable > /proc/acpi/ibm/wan
> echo disable > /proc/acpi/ibm/wan
>
> -Sysfs notes:
> +Sysfs notes
> +^^^^^^^^^^^
>
> If the W-WAN card is installed, it can be enabled /
> disabled through the "wwan_enable" thinkpad-acpi device
> attribute, and its current status can also be queried.
>
> enable:
> - 0: disables WWAN card / WWAN card is disabled
> - 1: enables WWAN card / WWAN card is enabled.
> + - 0: disables WWAN card / WWAN card is disabled
> + - 1: enables WWAN card / WWAN card is enabled.
>
> Note: this interface has been superseded by the generic rfkill
> class. It has been deprecated, and it will be removed in year
> @@ -1354,7 +1422,8 @@ sysfs rfkill class: switch "tpacpi_uwb_sw"
> This feature exports an rfkill controller for the UWB device, if one is
> present and enabled in the BIOS.
>
> -Sysfs notes:
> +Sysfs notes
> +^^^^^^^^^^^
>
> rfkill controller switch "tpacpi_uwb_sw": refer to
> Documentation/rfkill.txt for details.
> @@ -1368,11 +1437,11 @@ This sysfs attribute controls the keyboard "face" that will be shown on the
> Lenovo X1 Carbon 2nd gen (2014)'s adaptive keyboard. The value can be read
> and set.
>
> -1 = Home mode
> -2 = Web-browser mode
> -3 = Web-conference mode
> -4 = Function mode
> -5 = Layflat mode
> +- 1 = Home mode
> +- 2 = Web-browser mode
> +- 3 = Web-conference mode
> +- 4 = Function mode
> +- 5 = Layflat mode
>
> For more details about which buttons will appear depending on the mode, please
> review the laptop's user guide:
> @@ -1382,13 +1451,13 @@ Multiple Commands, Module Parameters
> ------------------------------------
>
> Multiple commands can be written to the proc files in one shot by
> -separating them with commas, for example:
> +separating them with commas, for example::
>
> echo enable,0xffff > /proc/acpi/ibm/hotkey
> echo lcd_disable,crt_enable > /proc/acpi/ibm/video
>
> Commands can also be specified when loading the thinkpad-acpi module,
> -for example:
> +for example::
>
> modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
>
> @@ -1397,14 +1466,16 @@ Enabling debugging output
> -------------------------
>
> The module takes a debug parameter which can be used to selectively
> -enable various classes of debugging output, for example:
> +enable various classes of debugging output, for example::
>
> modprobe thinkpad_acpi debug=0xffff
>
> will enable all debugging output classes. It takes a bitmask, so
> to enable more than one output class, just add their values.
>
> + ============= ======================================
> Debug bitmask Description
> + ============= ======================================
> 0x8000 Disclose PID of userspace programs
> accessing some functions of the driver
> 0x0001 Initialization and probing
> @@ -1415,6 +1486,7 @@ to enable more than one output class, just add their values.
> 0x0010 Fan control
> 0x0020 Backlight brightness
> 0x0040 Audio mixer/volume control
> + ============= ======================================
>
> There is also a kernel build option to enable more debugging
> information, which may be necessary to debug driver problems.
> @@ -1432,8 +1504,10 @@ the module parameter force_load=1. Regardless of whether this works or
> not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
>
>
> -Sysfs interface changelog:
> +Sysfs interface changelog
> +^^^^^^^^^^^^^^^^^^^^^^^^^
>
> +========= ===============================================================
> 0x000100: Initial sysfs support, as a single platform driver and
> device.
> 0x000200: Hot key support for 32 hot keys, and radio slider switch
> @@ -1485,3 +1559,4 @@ Sysfs interface changelog:
> 0x030000: Thermal and fan sysfs attributes were moved to the hwmon
> device instead of being attached to the backing platform
> device.
> +========= ===============================================================
> diff --git a/Documentation/laptops/toshiba_haps.txt b/Documentation/laptops/toshiba_haps.rst
> similarity index 60%
> rename from Documentation/laptops/toshiba_haps.txt
> rename to Documentation/laptops/toshiba_haps.rst
> index 0c1d88dedbde..11dfc428c080 100644
> --- a/Documentation/laptops/toshiba_haps.txt
> +++ b/Documentation/laptops/toshiba_haps.rst
> @@ -1,18 +1,19 @@
> -Kernel driver toshiba_haps
> +====================================
> Toshiba HDD Active Protection Sensor
> ====================================
>
> +Kernel driver: toshiba_haps
> +
> Author: Azael Avalos <coproscefalo@gmail.com>
>
>
> -0. Contents
> ------------
> +.. 0. Contents
>
> -1. Description
> -2. Interface
> -3. Accelerometer axes
> -4. Supported devices
> -5. Usage
> + 1. Description
> + 2. Interface
> + 3. Accelerometer axes
> + 4. Supported devices
> + 5. Usage
>
>
> 1. Description
> @@ -32,17 +33,20 @@ file to set the desired protection level or sensor sensibility.
> ------------
>
> This device comes with 3 methods:
> -_STA - Checks existence of the device, returning Zero if the device does not
> +
> +==== =====================================================================
> +_STA Checks existence of the device, returning Zero if the device does not
> exists or is not supported.
> -PTLV - Sets the desired protection level.
> -RSSS - Shuts down the HDD protection interface for a few seconds,
> +PTLV Sets the desired protection level.
> +RSSS Shuts down the HDD protection interface for a few seconds,
> then restores normal operation.
> +==== =====================================================================
>
> Note:
> -The presence of Solid State Drives (SSD) can make this driver to fail loading,
> -given the fact that such drives have no movable parts, and thus, not requiring
> -any "protection" as well as failing during the evaluation of the _STA method
> -found under this device.
> + The presence of Solid State Drives (SSD) can make this driver to fail loading,
> + given the fact that such drives have no movable parts, and thus, not requiring
> + any "protection" as well as failing during the evaluation of the _STA method
> + found under this device.
>
>
> 3. Accelerometer axes
> @@ -66,11 +70,18 @@ conventional HDD and not only SSD, or a combination of both HDD and SSD.
> --------
>
> The sysfs files under /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/ are:
> -protection_level - The protection_level is readable and writeable, and
> +
> +================ ============================================================
> +protection_level The protection_level is readable and writeable, and
> provides a way to let userspace query the current protection
> level, as well as set the desired protection level, the
> available protection levels are:
> - 0 - Disabled | 1 - Low | 2 - Medium | 3 - High
> -reset_protection - The reset_protection entry is writeable only, being "1"
> +
> + ============ ======= ========== ========
> + 0 - Disabled 1 - Low 2 - Medium 3 - High
> + ============ ======= ========== ========
> +
> +reset_protection The reset_protection entry is writeable only, being "1"
> the only parameter it accepts, it is used to trigger
> a reset of the protection interface.
> +================ ============================================================
> diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
> index 749322060f10..c5f0d44433a2 100644
> --- a/Documentation/sysctl/vm.txt
> +++ b/Documentation/sysctl/vm.txt
> @@ -102,7 +102,7 @@ Changing this takes effect whenever an application requests memory.
> 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.txt.
> +information on block I/O debugging is in Documentation/laptops/laptop-mode.rst.
>
> ==============================================================
>
> @@ -286,7 +286,7 @@ shared memory segment using hugetlb page.
> 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.txt.
> +controlled by this knob are discussed in Documentation/laptops/laptop-mode.rst.
>
> ==============================================================
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 73000e7d7f19..c63b1b9cbed4 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14753,7 +14753,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.txt
> +F: Documentation/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 466ebd84ad17..bb734066075f 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.txt>, and say Y or M here.
> + <file:Documentation/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 5d5cc6111081..e53c915761e7 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.txt> for more information.
> + Read <file:Documentation/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.txt> and
> + <file:Documentation/laptops/thinkpad-acpi.rst> and
> <http://ibm-acpi.sf.net/> .
>
> This driver was formerly known as ibm-acpi.
> --
> 2.21.0
>
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to howto.rst
From: Daniel Vetter @ 2019-06-12 19:45 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Maarten Lankhorst, Maxime Ripard,
Sean Paul, David Airlie, dri-devel
In-Reply-To: <20190612144015.033247db@coco.lan>
On Wed, Jun 12, 2019 at 7:40 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Em Tue, 11 Jun 2019 09:37:01 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
> > On Tue, 11 Jun 2019 06:02:15 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> >
> > > Jon, please correct me if I' wrong, bu I guess the plan is to place them
> > > somewhere under Documentation/admin-guide/.
> >
> > That makes sense to me.
> >
> > > If so, perhaps creating a Documentation/admin-guide/drm dir there and
> > > place docs like EDID/HOWTO.txt, svga.txt, etc would work.
> >
> > Maybe "graphics" or "display" rather than "drm", which may not entirely
> > applicable to all of those docs or as familiar to all admins?
>
> It is up to Daniel/David to decide. Personally, I agree with you that
> either "graphics" or "display" would be better at the admin guide.
We use Documentation/gpu already for the developer guide, I think
going with "gpu" on the admin guide for consistency would be good. I
do personally think that splitting out the admin guide makes sense, we
could also put some recommendations about access rights for drm device
nodes and stuff like that in there.
> > > Btw, that's one of the reasons[1] why I opted to keep the files where they
> > > are: properly organizing the converted documents call for such kind
> > > of discussions. On my experience, discussing names and directory locations
> > > can generate warm discussions and take a lot of time to reach consensus.
> >
> > Moving docs is a pain; my life would certainly be easier if I were happy
> > to just let everything lie where it fell :) But it's far from the hardest
> > problem we solve in kernel development, I assume we can figure it out.
>
> Yeah, it is doable. I'm happy to write the rename patches and even try
> to split some documents at the places I'm more familiar with, but, IMHO,
> we should do some discussions before some of such renames.
>
> For example, Daniel said that:
>
> > > > Yeah atm we're doing a bad job of keeping the kapi and uapi parts
> > > > separate. But the plan at least is to move all the gpu related uapi stuff
> > > > into Documentation/gpu/drm-uapi.rst. Not sure there's value in moving that
> > > > out of the gpu folder ...
>
> From the conversions I've made so far, almost all driver subsystems
> put everything under Documentation/<subsystem: kAPI, uAPI, admin info,
> driver-specific technical info.
>
> It should be doable to place kAPI and uAPI on different books, but there
> will be lots of cross-reference links between them, on properly-written
> docs.
I'm not sure it makes sense to split out the kapi and uapi sides of
the docs complete. For the admin guide I think one overall book
covering all subsystems is good. But someone creating a drm/kms
compositor is not going to be interested much into some special
options for networking protocol I think. For those I think focusing
more on the specific subsystem makes more sense (and easier to share
common concepts/diagrams between uapi and kapi of a given subsystem).
I do think for a given subsystem the uapi side should be clearly split
out (otherwise it's impossible to find for non-kernel people). And
currently drm falls short really badly on this. So maybe a good
argument for a uapi kernel directory would be to force that, but not
sure that's good enough of a reason.
-Daniel
> However, other admin-guide stuff under drivers are usually in the middle
> of the documents. For example, on media, we have some at the uAPI guide,
> like the Device Naming item:
>
> https://linuxtv.org/downloads/v4l-dvb-apis-new/uapi/v4l/open.html#device-naming
>
> But splitting it from uAPI guide is not an easy task.
>
> At the driver's specific documentation is even messier.
>
> Ok, splitting is doable, but require lots of dedication, and I'm not
> convinced if it would make much difference in practice.
>
> Thanks,
> Mauro
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
^ permalink raw reply
* Re: [PATCH v7 22/27] binfmt_elf: Extract .note.gnu.property from an ELF file
From: Yu-cheng Yu @ 2019-06-12 19:04 UTC (permalink / raw)
To: Dave Martin
Cc: Florian Weimer, x86, H. Peter Anvin, Thomas Gleixner, Ingo Molnar,
linux-kernel, linux-doc, linux-mm, linux-arch, linux-api,
Arnd Bergmann, Andy Lutomirski, Balbir Singh, Borislav Petkov,
Cyrill Gorcunov, Dave Hansen, Eugene Syromiatnikov, H.J. Lu,
Jann Horn, Jonathan Corbet, Kees Cook, Mike Kravetz, Nadav Amit,
Oleg Nesterov, Pavel Machek, Peter Zijlstra, Randy Dunlap,
Ravi V. Shankar, Vedvyas Shanbhogue
In-Reply-To: <20190612093238.GQ28398@e103592.cambridge.arm.com>
On Wed, 2019-06-12 at 10:32 +0100, Dave Martin wrote:
> On Tue, Jun 11, 2019 at 12:31:34PM -0700, Yu-cheng Yu wrote:
> > On Tue, 2019-06-11 at 12:41 +0100, Dave Martin wrote:
> > > On Mon, Jun 10, 2019 at 07:24:43PM +0200, Florian Weimer wrote:
> > > > * Yu-cheng Yu:
> > > >
> > > > > To me, looking at PT_GNU_PROPERTY and not trying to support anything
> > > > > is a
> > > > > logical choice. And it breaks only a limited set of toolchains.
> > > > >
> > > > > I will simplify the parser and leave this patch as-is for anyone who
> > > > > wants
> > > > > to
> > > > > back-port. Are there any objections or concerns?
> > > >
> > > > Red Hat Enterprise Linux 8 does not use PT_GNU_PROPERTY and is probably
> > > > the largest collection of CET-enabled binaries that exists today.
> > >
> > > For clarity, RHEL is actively parsing these properties today?
> > >
> > > > My hope was that we would backport the upstream kernel patches for CET,
> > > > port the glibc dynamic loader to the new kernel interface, and be ready
> > > > to run with CET enabled in principle (except that porting userspace
> > > > libraries such as OpenSSL has not really started upstream, so many
> > > > processes where CET is particularly desirable will still run without
> > > > it).
> > > >
> > > > I'm not sure if it is a good idea to port the legacy support if it's not
> > > > part of the mainline kernel because it comes awfully close to creating
> > > > our own private ABI.
> > >
> > > I guess we can aim to factor things so that PT_NOTE scanning is
> > > available as a fallback on arches for which the absence of
> > > PT_GNU_PROPERTY is not authoritative.
> >
> > We can probably check PT_GNU_PROPERTY first, and fallback (based on ld-linux
> > version?) to PT_NOTE scanning?
>
> For arm64, we can check for PT_GNU_PROPERTY and then give up
> unconditionally.
>
> For x86, we would fall back to PT_NOTE scanning, but this will add a bit
> of cost to binaries that don't have NT_GNU_PROPERTY_TYPE_0. The ld.so
> version doesn't tell you what ELF ABI a given executable conforms to.
>
> Since this sounds like it's largely a distro-specific issue, maybe there
> could be a Kconfig option to turn the fallback PT_NOTE scanning on?
Yes, I will make it a Kconfig option.
Yu-cheng
^ permalink raw reply
* Re: [PATCH v1 29/31] docs: nvdimm: convert to ReST
From: Dan Williams @ 2019-06-12 19:04 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Vishal Verma,
Dave Jiang, Keith Busch, Ira Weiny, linux-nvdimm
In-Reply-To: <075d5879142ff1b7ad16f5eccf4759d35ca02fd4.1560364494.git.mchehab+samsung@kernel.org>
Hi Mauro,
On Wed, Jun 12, 2019 at 11:38 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Rename the mtd documentation files to ReST, add an
s/mtd/nvdimm/
> 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.
Looks ok, but I was not able to apply this one in isolation to give it
a try. Am I missing some pre-reqs compared to v5.2-rc4?
^ permalink raw reply
* [PATCH v1 31/31] docs: mmc: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the mmc 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/mmc/index.rst | 13 +++++
.../{mmc-async-req.txt => mmc-async-req.rst} | 53 +++++++++++--------
.../{mmc-dev-attrs.txt => mmc-dev-attrs.rst} | 32 +++++++----
.../{mmc-dev-parts.txt => mmc-dev-parts.rst} | 13 ++---
.../mmc/{mmc-tools.txt => mmc-tools.rst} | 5 +-
5 files changed, 79 insertions(+), 37 deletions(-)
create mode 100644 Documentation/mmc/index.rst
rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%)
rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%)
rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%)
rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%)
diff --git a/Documentation/mmc/index.rst b/Documentation/mmc/index.rst
new file mode 100644
index 000000000000..3305478ddadb
--- /dev/null
+++ b/Documentation/mmc/index.rst
@@ -0,0 +1,13 @@
+:orphan:
+
+========================
+MMC/SD/SDIO card support
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ mmc-dev-attrs
+ mmc-dev-parts
+ mmc-async-req
+ mmc-tools
diff --git a/Documentation/mmc/mmc-async-req.txt b/Documentation/mmc/mmc-async-req.rst
similarity index 75%
rename from Documentation/mmc/mmc-async-req.txt
rename to Documentation/mmc/mmc-async-req.rst
index ae1907b10e4a..0f7197c9c3b5 100644
--- a/Documentation/mmc/mmc-async-req.txt
+++ b/Documentation/mmc/mmc-async-req.rst
@@ -1,13 +1,20 @@
+========================
+MMC Asynchronous Request
+========================
+
Rationale
=========
How significant is the cache maintenance overhead?
+
It depends. Fast eMMC and multiple cache levels with speculative cache
pre-fetch makes the cache overhead relatively significant. If the DMA
preparations for the next request are done in parallel with the current
transfer, the DMA preparation overhead would not affect the MMC performance.
+
The intention of non-blocking (asynchronous) MMC requests is to minimize the
time between when an MMC request ends and another MMC request begins.
+
Using mmc_wait_for_req(), the MMC controller is idle while dma_map_sg and
dma_unmap_sg are processing. Using non-blocking MMC requests makes it
possible to prepare the caches for next job in parallel with an active
@@ -17,6 +24,7 @@ MMC block driver
================
The mmc_blk_issue_rw_rq() in the MMC block driver is made non-blocking.
+
The increase in throughput is proportional to the time it takes to
prepare (major part of preparations are dma_map_sg() and dma_unmap_sg())
a request and how fast the memory is. The faster the MMC/SD is the
@@ -35,6 +43,7 @@ MMC core API extension
======================
There is one new public function mmc_start_req().
+
It starts a new MMC command request for a host. The function isn't
truly non-blocking. If there is an ongoing async request it waits
for completion of that request and starts the new one and returns. It
@@ -47,6 +56,7 @@ MMC host extensions
There are two optional members in the mmc_host_ops -- pre_req() and
post_req() -- that the host driver may implement in order to move work
to before and after the actual mmc_host_ops.request() function is called.
+
In the DMA case pre_req() may do dma_map_sg() and prepare the DMA
descriptor, and post_req() runs the dma_unmap_sg().
@@ -55,33 +65,34 @@ Optimize for the first request
The first request in a series of requests can't be prepared in parallel
with the previous transfer, since there is no previous request.
+
The argument is_first_req in pre_req() indicates that there is no previous
request. The host driver may optimize for this scenario to minimize
the performance loss. A way to optimize for this is to split the current
request in two chunks, prepare the first chunk and start the request,
and finally prepare the second chunk and start the transfer.
-Pseudocode to handle is_first_req scenario with minimal prepare overhead:
+Pseudocode to handle is_first_req scenario with minimal prepare overhead::
-if (is_first_req && req->size > threshold)
- /* start MMC transfer for the complete transfer size */
- mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
+ if (is_first_req && req->size > threshold)
+ /* start MMC transfer for the complete transfer size */
+ mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
- /*
- * Begin to prepare DMA while cmd is being processed by MMC.
- * The first chunk of the request should take the same time
- * to prepare as the "MMC process command time".
- * If prepare time exceeds MMC cmd time
- * the transfer is delayed, guesstimate max 4k as first chunk size.
- */
- prepare_1st_chunk_for_dma(req);
- /* flush pending desc to the DMAC (dmaengine.h) */
- dma_issue_pending(req->dma_desc);
+ /*
+ * Begin to prepare DMA while cmd is being processed by MMC.
+ * The first chunk of the request should take the same time
+ * to prepare as the "MMC process command time".
+ * If prepare time exceeds MMC cmd time
+ * the transfer is delayed, guesstimate max 4k as first chunk size.
+ */
+ prepare_1st_chunk_for_dma(req);
+ /* flush pending desc to the DMAC (dmaengine.h) */
+ dma_issue_pending(req->dma_desc);
- prepare_2nd_chunk_for_dma(req);
- /*
- * The second issue_pending should be called before MMC runs out
- * of the first chunk. If the MMC runs out of the first data chunk
- * before this call, the transfer is delayed.
- */
- dma_issue_pending(req->dma_desc);
+ prepare_2nd_chunk_for_dma(req);
+ /*
+ * The second issue_pending should be called before MMC runs out
+ * of the first chunk. If the MMC runs out of the first data chunk
+ * before this call, the transfer is delayed.
+ */
+ dma_issue_pending(req->dma_desc);
diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/mmc/mmc-dev-attrs.rst
similarity index 73%
rename from Documentation/mmc/mmc-dev-attrs.txt
rename to Documentation/mmc/mmc-dev-attrs.rst
index 4ad0bb17f343..4f44b1b730d6 100644
--- a/Documentation/mmc/mmc-dev-attrs.txt
+++ b/Documentation/mmc/mmc-dev-attrs.rst
@@ -1,3 +1,4 @@
+==================================
SD and MMC Block Device Attributes
==================================
@@ -6,23 +7,29 @@ SD or MMC device.
The following attributes are read/write.
- force_ro Enforce read-only access even if write protect switch is off.
+ ======== ===============================================
+ force_ro Enforce read-only access even if write protect switch is off.
+ ======== ===============================================
SD and MMC Device Attributes
============================
All attributes are read-only.
+ ====================== ===============================================
cid Card Identification Register
csd Card Specific Data Register
scr SD Card Configuration Register (SD only)
date Manufacturing Date (from CID Register)
- fwrev Firmware/Product Revision (from CID Register) (SD and MMCv1 only)
- hwrev Hardware/Product Revision (from CID Register) (SD and MMCv1 only)
+ fwrev Firmware/Product Revision (from CID Register)
+ (SD and MMCv1 only)
+ hwrev Hardware/Product Revision (from CID Register)
+ (SD and MMCv1 only)
manfid Manufacturer ID (from CID Register)
name Product Name (from CID Register)
oemid OEM/Application ID (from CID Register)
- prv Product Revision (from CID Register) (SD and MMCv4 only)
+ prv Product Revision (from CID Register)
+ (SD and MMCv4 only)
serial Product Serial Number (from CID Register)
erase_size Erase group size
preferred_erase_size Preferred erase size
@@ -30,7 +37,10 @@ All attributes are read-only.
rel_sectors Reliable write sector count
ocr Operation Conditions Register
dsr Driver Stage Register
- cmdq_en Command Queue enabled: 1 => enabled, 0 => not enabled
+ cmdq_en Command Queue enabled:
+
+ 1 => enabled, 0 => not enabled
+ ====================== ===============================================
Note on Erase Size and Preferred Erase Size:
@@ -44,14 +54,15 @@ Note on Erase Size and Preferred Erase Size:
SD/MMC cards can erase an arbitrarily large area up to and
including the whole card. When erasing a large area it may
be desirable to do it in smaller chunks for three reasons:
- 1. A single erase command will make all other I/O on
+
+ 1. A single erase command will make all other I/O on
the card wait. This is not a problem if the whole card
is being erased, but erasing one partition will make
I/O for another partition on the same card wait for the
duration of the erase - which could be a several
minutes.
- 2. To be able to inform the user of erase progress.
- 3. The erase timeout becomes too large to be very
+ 2. To be able to inform the user of erase progress.
+ 3. The erase timeout becomes too large to be very
useful. Because the erase timeout contains a margin
which is multiplied by the size of the erase area,
the value can end up being several minutes for large
@@ -72,6 +83,9 @@ Note on Erase Size and Preferred Erase Size:
"preferred_erase_size" is in bytes.
Note on raw_rpmb_size_mult:
+
"raw_rpmb_size_mult" is a multiple of 128kB block.
+
RPMB size in byte is calculated by using the following equation:
- RPMB partition size = 128kB x raw_rpmb_size_mult
+
+ RPMB partition size = 128kB x raw_rpmb_size_mult
diff --git a/Documentation/mmc/mmc-dev-parts.txt b/Documentation/mmc/mmc-dev-parts.rst
similarity index 83%
rename from Documentation/mmc/mmc-dev-parts.txt
rename to Documentation/mmc/mmc-dev-parts.rst
index f08d078d43cf..995922f1f744 100644
--- a/Documentation/mmc/mmc-dev-parts.txt
+++ b/Documentation/mmc/mmc-dev-parts.rst
@@ -1,3 +1,4 @@
+============================
SD and MMC Device Partitions
============================
@@ -18,18 +19,18 @@ platform, write access is disabled by default to reduce the chance of
accidental bricking.
To enable write access to /dev/mmcblkXbootY, disable the forced read-only
-access with:
+access with::
-echo 0 > /sys/block/mmcblkXbootY/force_ro
+ echo 0 > /sys/block/mmcblkXbootY/force_ro
-To re-enable read-only access:
+To re-enable read-only access::
-echo 1 > /sys/block/mmcblkXbootY/force_ro
+ echo 1 > /sys/block/mmcblkXbootY/force_ro
The boot partitions can also be locked read only until the next power on,
-with:
+with::
-echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
+ echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
This is a feature of the card and not of the kernel. If the card does
not support boot partition locking, the file will not exist. If the
diff --git a/Documentation/mmc/mmc-tools.txt b/Documentation/mmc/mmc-tools.rst
similarity index 92%
rename from Documentation/mmc/mmc-tools.txt
rename to Documentation/mmc/mmc-tools.rst
index 735509c165d5..54406093768b 100644
--- a/Documentation/mmc/mmc-tools.txt
+++ b/Documentation/mmc/mmc-tools.rst
@@ -1,14 +1,17 @@
+======================
MMC tools introduction
======================
There is one MMC test tools called mmc-utils, which is maintained by Chris Ball,
you can find it at the below public git repository:
-http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
+
+ http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
Functions
=========
The mmc-utils tools can do the following:
+
- Print and parse extcsd data.
- Determine the eMMC writeprotect status.
- Set the eMMC writeprotect status.
--
2.21.0
^ permalink raw reply related
* [PATCH v1 07/31] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Convert this small file to ReST format and rename it.
Most of the conversion were related to adjusting whitespaces
in order for each section to be properly parsed.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/pti/pti_intel_mid.rst | 106 ++++++++++++++++++++++++++++
Documentation/pti/pti_intel_mid.txt | 99 --------------------------
2 files changed, 106 insertions(+), 99 deletions(-)
create mode 100644 Documentation/pti/pti_intel_mid.rst
delete mode 100644 Documentation/pti/pti_intel_mid.txt
diff --git a/Documentation/pti/pti_intel_mid.rst b/Documentation/pti/pti_intel_mid.rst
new file mode 100644
index 000000000000..ea05725174cb
--- /dev/null
+++ b/Documentation/pti/pti_intel_mid.rst
@@ -0,0 +1,106 @@
+:orphan:
+
+=============
+Intel MID PTI
+=============
+
+The Intel MID PTI project is HW implemented in Intel Atom
+system-on-a-chip designs based on the Parallel Trace
+Interface for MIPI P1149.7 cJTAG standard. The kernel solution
+for this platform involves the following files::
+
+ ./include/linux/pti.h
+ ./drivers/.../n_tracesink.h
+ ./drivers/.../n_tracerouter.c
+ ./drivers/.../n_tracesink.c
+ ./drivers/.../pti.c
+
+pti.c is the driver that enables various debugging features
+popular on platforms from certain mobile manufacturers.
+n_tracerouter.c and n_tracesink.c allow extra system information to
+be collected and routed to the pti driver, such as trace
+debugging data from a modem. Although n_tracerouter
+and n_tracesink are a part of the complete PTI solution,
+these two line disciplines can work separately from
+pti.c and route any data stream from one /dev/tty node
+to another /dev/tty node via kernel-space. This provides
+a stable, reliable connection that will not break unless
+the user-space application shuts down (plus avoids
+kernel->user->kernel context switch overheads of routing
+data).
+
+An example debugging usage for this driver system:
+
+ * Hook /dev/ttyPTI0 to syslogd. Opening this port will also start
+ a console device to further capture debugging messages to PTI.
+ * Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
+ This is where n_tracerouter and n_tracesink are used.
+ * Hook /dev/pti to a user-level debugging application for writing
+ to PTI HW.
+ * `Use mipi_` Kernel Driver API in other device drivers for
+ debugging to PTI by first requesting a PTI write address via
+ mipi_request_masterchannel(1).
+
+Below is example pseudo-code on how a 'privileged' application
+can hook up n_tracerouter and n_tracesink to any tty on
+a system. 'Privileged' means the application has enough
+privileges to successfully manipulate the ldisc drivers
+but is not just blindly executing as 'root'. Keep in mind
+the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
+and n_tracesink line discpline drivers but is a generic
+operation for a program to use a line discpline driver
+on a tty port other than the default n_tty::
+
+ /////////// To hook up n_tracerouter and n_tracesink /////////
+
+ // Note that n_tracerouter depends on n_tracesink.
+ #include <errno.h>
+ #define ONE_TTY "/dev/ttyOne"
+ #define TWO_TTY "/dev/ttyTwo"
+
+ // needed global to hand onto ldisc connection
+ static int g_fd_source = -1;
+ static int g_fd_sink = -1;
+
+ // these two vars used to grab LDISC values from loaded ldisc drivers
+ // in OS. Look at /proc/tty/ldiscs to get the right numbers from
+ // the ldiscs loaded in the system.
+ int source_ldisc_num, sink_ldisc_num = -1;
+ int retval;
+
+ g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
+ g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W
+
+ if (g_fd_source <= 0) || (g_fd_sink <= 0) {
+ // doubt you'll want to use these exact error lines of code
+ printf("Error on open(). errno: %d\n",errno);
+ return errno;
+ }
+
+ retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
+ if (retval < 0) {
+ printf("Error on ioctl(). errno: %d\n", errno);
+ return errno;
+ }
+
+ retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
+ if (retval < 0) {
+ printf("Error on ioctl(). errno: %d\n", errno);
+ return errno;
+ }
+
+ /////////// To disconnect n_tracerouter and n_tracesink ////////
+
+ // First make sure data through the ldiscs has stopped.
+
+ // Second, disconnect ldiscs. This provides a
+ // little cleaner shutdown on tty stack.
+ sink_ldisc_num = 0;
+ source_ldisc_num = 0;
+ ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
+ ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
+
+ // Three, program closes connection, and cleanup:
+ close(g_fd_uart);
+ close(g_fd_gadget);
+ g_fd_uart = g_fd_gadget = NULL;
diff --git a/Documentation/pti/pti_intel_mid.txt b/Documentation/pti/pti_intel_mid.txt
deleted file mode 100644
index e7a5b6d1f7a9..000000000000
--- a/Documentation/pti/pti_intel_mid.txt
+++ /dev/null
@@ -1,99 +0,0 @@
-The Intel MID PTI project is HW implemented in Intel Atom
-system-on-a-chip designs based on the Parallel Trace
-Interface for MIPI P1149.7 cJTAG standard. The kernel solution
-for this platform involves the following files:
-
-./include/linux/pti.h
-./drivers/.../n_tracesink.h
-./drivers/.../n_tracerouter.c
-./drivers/.../n_tracesink.c
-./drivers/.../pti.c
-
-pti.c is the driver that enables various debugging features
-popular on platforms from certain mobile manufacturers.
-n_tracerouter.c and n_tracesink.c allow extra system information to
-be collected and routed to the pti driver, such as trace
-debugging data from a modem. Although n_tracerouter
-and n_tracesink are a part of the complete PTI solution,
-these two line disciplines can work separately from
-pti.c and route any data stream from one /dev/tty node
-to another /dev/tty node via kernel-space. This provides
-a stable, reliable connection that will not break unless
-the user-space application shuts down (plus avoids
-kernel->user->kernel context switch overheads of routing
-data).
-
-An example debugging usage for this driver system:
- *Hook /dev/ttyPTI0 to syslogd. Opening this port will also start
- a console device to further capture debugging messages to PTI.
- *Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
- This is where n_tracerouter and n_tracesink are used.
- *Hook /dev/pti to a user-level debugging application for writing
- to PTI HW.
- *Use mipi_* Kernel Driver API in other device drivers for
- debugging to PTI by first requesting a PTI write address via
- mipi_request_masterchannel(1).
-
-Below is example pseudo-code on how a 'privileged' application
-can hook up n_tracerouter and n_tracesink to any tty on
-a system. 'Privileged' means the application has enough
-privileges to successfully manipulate the ldisc drivers
-but is not just blindly executing as 'root'. Keep in mind
-the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
-and n_tracesink line discpline drivers but is a generic
-operation for a program to use a line discpline driver
-on a tty port other than the default n_tty.
-
-/////////// To hook up n_tracerouter and n_tracesink /////////
-
-// Note that n_tracerouter depends on n_tracesink.
-#include <errno.h>
-#define ONE_TTY "/dev/ttyOne"
-#define TWO_TTY "/dev/ttyTwo"
-
-// needed global to hand onto ldisc connection
-static int g_fd_source = -1;
-static int g_fd_sink = -1;
-
-// these two vars used to grab LDISC values from loaded ldisc drivers
-// in OS. Look at /proc/tty/ldiscs to get the right numbers from
-// the ldiscs loaded in the system.
-int source_ldisc_num, sink_ldisc_num = -1;
-int retval;
-
-g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
-g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W
-
-if (g_fd_source <= 0) || (g_fd_sink <= 0) {
- // doubt you'll want to use these exact error lines of code
- printf("Error on open(). errno: %d\n",errno);
- return errno;
-}
-
-retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
-if (retval < 0) {
- printf("Error on ioctl(). errno: %d\n", errno);
- return errno;
-}
-
-retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
-if (retval < 0) {
- printf("Error on ioctl(). errno: %d\n", errno);
- return errno;
-}
-
-/////////// To disconnect n_tracerouter and n_tracesink ////////
-
-// First make sure data through the ldiscs has stopped.
-
-// Second, disconnect ldiscs. This provides a
-// little cleaner shutdown on tty stack.
-sink_ldisc_num = 0;
-source_ldisc_num = 0;
-ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
-ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
-
-// Three, program closes connection, and cleanup:
-close(g_fd_uart);
-close(g_fd_gadget);
-g_fd_uart = g_fd_gadget = NULL;
--
2.21.0
^ permalink raw reply related
* [PATCH v1 12/31] docs: xen-tpmfront.txt: convert it to .rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
In order to be able to add this file to the security book,
we need first to convert it to reST.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{xen-tpmfront.txt => xen-tpmfront.rst} | 103 ++++++++++--------
1 file changed, 58 insertions(+), 45 deletions(-)
rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)
diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.rst
similarity index 66%
rename from Documentation/security/tpm/xen-tpmfront.txt
rename to Documentation/security/tpm/xen-tpmfront.rst
index 69346de87ff3..98a16ab87360 100644
--- a/Documentation/security/tpm/xen-tpmfront.txt
+++ b/Documentation/security/tpm/xen-tpmfront.rst
@@ -1,4 +1,8 @@
+:orphan:
+
+=============================
Virtual TPM interface for Xen
+=============================
Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
@@ -6,7 +10,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for
Xen. The reader is assumed to have familiarity with building and installing Xen,
Linux, and a basic understanding of the TPM and vTPM concepts.
-INTRODUCTION
+Introduction
+------------
The goal of this work is to provide a TPM functionality to a virtual guest
operating system (in Xen terms, a DomU). This allows programs to interact with
@@ -24,81 +29,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by
IBM and Intel corporation.
-DESIGN OVERVIEW
+Design Overview
---------------
-The architecture of vTPM is described below:
+The architecture of vTPM is described below::
-+------------------+
-| Linux DomU | ...
-| | ^ |
-| v | |
-| xen-tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpm-stubdom | ...
-| | ^ |
-| v | |
-| mini-os/tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpmmgr-stubdom |
-| | ^ |
-| v | |
-| mini-os/tpm_tis |
-+------------------+
- | ^
- v |
-+------------------+
-| Hardware TPM |
-+------------------+
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM |
+ +------------------+
- * Linux DomU: The Linux based guest that wants to use a vTPM. There may be
+* Linux DomU:
+ The Linux based guest that wants to use a vTPM. There may be
more than one of these.
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
+* xen-tpmfront.ko:
+ Linux kernel virtual TPM frontend driver. This driver
provides vTPM access to a Linux-based DomU.
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
+* mini-os/tpmback:
+ Mini-os TPM backend driver. The Linux frontend driver
connects to this backend driver to facilitate communications
between the Linux DomU and its vTPM. This driver is also
used by vtpmmgr-stubdom to communicate with vtpm-stubdom.
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
+* vtpm-stubdom:
+ A mini-os stub domain that implements a vTPM. There is a
one to one mapping between running vtpm-stubdom instances and
logical vtpms on the system. The vTPM Platform Configuration
Registers (PCRs) are normally all initialized to zero.
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
+* mini-os/tpmfront:
+ Mini-os TPM frontend driver. The vTPM mini-os domain
vtpm-stubdom uses this driver to communicate with
vtpmmgr-stubdom. This driver is also used in mini-os
domains such as pv-grub that talk to the vTPM domain.
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is
+* vtpmmgr-stubdom:
+ A mini-os domain that implements the vTPM manager. There is
only one vTPM manager and it should be running during the
entire lifetime of the machine. This domain regulates
access to the physical TPM on the system and secures the
persistent state of each vTPM.
- * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+* mini-os/tpm_tis:
+ Mini-os TPM version 1.2 TPM Interface Specification (TIS)
driver. This driver used by vtpmmgr-stubdom to talk directly to
the hardware TPM. Communication is facilitated by mapping
hardware memory pages into vtpmmgr-stubdom.
- * Hardware TPM: The physical TPM that is soldered onto the motherboard.
+* Hardware TPM:
+ The physical TPM that is soldered onto the motherboard.
-INTEGRATION WITH XEN
+Integration With Xen
--------------------
Support for the vTPM driver was added in Xen using the libxl toolstack in Xen
--
2.21.0
^ permalink raw reply related
* [PATCH v1 16/31] docs: rbtree.txt: fix Sphinx build warnings
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Ths file is already at ReST format. Yet, some recent changes
made it to produce a few warnings when building it with
Sphinx.
Those are trivially fixed by marking some literal blocks.
Fix them before adding it to the docs building system.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/rbtree.txt | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt
index c42a21b99046..523d54b60087 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.txt
@@ -204,21 +204,21 @@ potentially expensive tree iterations. This is done at negligible runtime
overhead for maintanence; albeit larger memory footprint.
Similar to the rb_root structure, cached rbtrees are initialized to be
-empty via:
+empty via::
struct rb_root_cached mytree = RB_ROOT_CACHED;
Cached rbtree is simply a regular rb_root with an extra pointer to cache the
leftmost node. This allows rb_root_cached to exist wherever rb_root does,
which permits augmented trees to be supported as well as only a few extra
-interfaces:
+interfaces::
struct rb_node *rb_first_cached(struct rb_root_cached *tree);
void rb_insert_color_cached(struct rb_node *, struct rb_root_cached *, bool);
void rb_erase_cached(struct rb_node *node, struct rb_root_cached *);
Both insert and erase calls have their respective counterpart of augmented
-trees:
+trees::
void rb_insert_augmented_cached(struct rb_node *node, struct rb_root_cached *,
bool, struct rb_augment_callbacks *);
--
2.21.0
^ permalink raw reply related
* [PATCH v1 17/31] docs: DMA-API-HOWTO.txt: fix an unmarked code block
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
When building with Sphinx, it would produce this warning:
docs/Documentation/DMA-API-HOWTO.rst:222: WARNING: Definition list ends without a blank line; unexpected unindent.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/DMA-API-HOWTO.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index cb712a02f59f..358d495456d1 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -212,7 +212,7 @@ The standard 64-bit addressing device would do something like this::
If the device only supports 32-bit addressing for descriptors in the
coherent allocations, but supports full 64-bits for streaming mappings
-it would look like this:
+it would look like this::
if (dma_set_mask(dev, DMA_BIT_MASK(64))) {
dev_warn(dev, "mydev: No suitable DMA available\n");
--
2.21.0
^ permalink raw reply related
* [PATCH v1 05/31] docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
The debugfs interface for CMA should be there together with other
mm-related documents.
Convert this small file to ReST and move it to its rightful place.
The conversion is actually quite simple: just add a title for the
document. In order to make it to look better for the audience,
also mark the "echo" command as a literal block.
While this is not part of any book, mark it as :orphan:,
in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cma/{debugfs.txt => debugfs.rst} | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%)
diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.rst
similarity index 91%
rename from Documentation/cma/debugfs.txt
rename to Documentation/cma/debugfs.rst
index 6cef20a8cedc..518fe401b5ee 100644
--- a/Documentation/cma/debugfs.txt
+++ b/Documentation/cma/debugfs.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+=====================
+CMA Debugfs Interface
+=====================
+
The CMA debugfs interface is useful to retrieve basic information out of the
different CMA areas and to test allocation/release in each of the areas.
@@ -12,7 +18,7 @@ The structure of the files created under that directory is as follows:
- [RO] count: Amount of memory in the CMA area.
- [RO] order_per_bit: Order of pages represented by one bit.
- [RO] bitmap: The bitmap of page states in the zone.
- - [WO] alloc: Allocate N pages from that CMA area. For example:
+ - [WO] alloc: Allocate N pages from that CMA area. For example::
echo 5 > <debugfs>/cma/cma-2/alloc
--
2.21.0
^ permalink raw reply related
* [PATCH v1 02/31] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{lcd-panel-cgram.txt => lcd-panel-cgram.rst} | 9 +++++++--
MAINTAINERS | 2 +-
2 files changed, 8 insertions(+), 3 deletions(-)
rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%)
diff --git a/Documentation/auxdisplay/lcd-panel-cgram.txt b/Documentation/auxdisplay/lcd-panel-cgram.rst
similarity index 88%
rename from Documentation/auxdisplay/lcd-panel-cgram.txt
rename to Documentation/auxdisplay/lcd-panel-cgram.rst
index 7f82c905763d..dfef50286018 100644
--- a/Documentation/auxdisplay/lcd-panel-cgram.txt
+++ b/Documentation/auxdisplay/lcd-panel-cgram.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+======================================
+Parallel port LCD/Keypad Panel support
+======================================
+
Some LCDs allow you to define up to 8 characters, mapped to ASCII
characters 0 to 7. The escape code to define a new character is
'\e[LG' followed by one digit from 0 to 7, representing the character
@@ -7,7 +13,7 @@ illuminated pixel with LSB on the right. Lines are numbered from the
top of the character to the bottom. On a 5x7 matrix, only the 5 lower
bits of the 7 first bytes are used for each character. If the string
is incomplete, only complete lines will be redefined. Here are some
-examples :
+examples::
printf "\e[LG0010101050D1F0C04;" => 0 = [enter]
printf "\e[LG1040E1F0000000000;" => 1 = [up]
@@ -21,4 +27,3 @@ examples :
printf "\e[LG00002061E1E060200;" => small speaker
Willy
-
diff --git a/MAINTAINERS b/MAINTAINERS
index b0b674f5aaca..fa236f3f5979 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11932,7 +11932,7 @@ PARALLEL LCD/KEYPAD PANEL DRIVER
M: Willy Tarreau <willy@haproxy.com>
M: Ksenija Stanojevic <ksenija.stanojevic@gmail.com>
S: Odd Fixes
-F: Documentation/auxdisplay/lcd-panel-cgram.txt
+F: Documentation/auxdisplay/lcd-panel-cgram.rst
F: drivers/auxdisplay/panel.c
PARALLEL PORT SUBSYSTEM
--
2.21.0
^ permalink raw reply related
* [PATCH v1 27/31] docs: md: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the md 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/md/index.rst | 12 ++
.../md/{md-cluster.txt => md-cluster.rst} | 188 ++++++++++++------
.../md/{raid5-cache.txt => raid5-cache.rst} | 28 +--
.../md/{raid5-ppl.txt => raid5-ppl.rst} | 2 +
4 files changed, 153 insertions(+), 77 deletions(-)
create mode 100644 Documentation/md/index.rst
rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)
diff --git a/Documentation/md/index.rst b/Documentation/md/index.rst
new file mode 100644
index 000000000000..c4db34ed327d
--- /dev/null
+++ b/Documentation/md/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+====
+RAID
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ md-cluster
+ raid5-cache
+ raid5-ppl
diff --git a/Documentation/md/md-cluster.txt b/Documentation/md/md-cluster.rst
similarity index 68%
rename from Documentation/md/md-cluster.txt
rename to Documentation/md/md-cluster.rst
index e1055f105cf5..96eb52cec7eb 100644
--- a/Documentation/md/md-cluster.txt
+++ b/Documentation/md/md-cluster.rst
@@ -1,19 +1,24 @@
+==========
+MD Cluster
+==========
+
The cluster MD is a shared-device RAID for a cluster, it supports
two levels: raid1 and raid10 (limited support).
1. On-disk format
+=================
Separate write-intent-bitmaps are used for each cluster node.
The bitmaps record all writes that may have been started on that node,
-and may not yet have finished. The on-disk layout is:
+and may not yet have finished. The on-disk layout is::
-0 4k 8k 12k
--------------------------------------------------------------------
-| idle | md super | bm super [0] + bits |
-| bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] |
-| bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits |
-| bm bits [3, contd] | | |
+ 0 4k 8k 12k
+ -------------------------------------------------------------------
+ | idle | md super | bm super [0] + bits |
+ | bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] |
+ | bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits |
+ | bm bits [3, contd] | | |
During "normal" functioning we assume the filesystem ensures that only
one node writes to any given block at a time, so a write request will
@@ -28,10 +33,12 @@ node) is writing.
2. DLM Locks for management
+===========================
There are three groups of locks for managing the device:
2.1 Bitmap lock resource (bm_lockres)
+-------------------------------------
The bm_lockres protects individual node bitmaps. They are named in
the form bitmap000 for node 1, bitmap001 for node 2 and so on. When a
@@ -48,6 +55,7 @@ There are three groups of locks for managing the device:
joins the cluster.
2.2 Message passing locks
+-------------------------
Each node has to communicate with other nodes when starting or ending
resync, and for metadata superblock updates. This communication is
@@ -55,116 +63,155 @@ There are three groups of locks for managing the device:
with the Lock Value Block (LVB) of one of the "message" lock.
2.3 new-device management
+-------------------------
A single lock: "no-new-dev" is used to co-ordinate the addition of
new devices - this must be synchronized across the array.
Normally all nodes hold a concurrent-read lock on this device.
3. Communication
+================
Messages can be broadcast to all nodes, and the sender waits for all
other nodes to acknowledge the message before proceeding. Only one
message can be processed at a time.
3.1 Message Types
+-----------------
There are six types of messages which are passed:
- 3.1.1 METADATA_UPDATED: informs other nodes that the metadata has
+3.1.1 METADATA_UPDATED
+^^^^^^^^^^^^^^^^^^^^^^
+
+ informs other nodes that the metadata has
been updated, and the node must re-read the md superblock. This is
performed synchronously. It is primarily used to signal device
failure.
- 3.1.2 RESYNCING: informs other nodes that a resync is initiated or
+3.1.2 RESYNCING
+^^^^^^^^^^^^^^^
+ informs other nodes that a resync is initiated or
ended so that each node may suspend or resume the region. Each
RESYNCING message identifies a range of the devices that the
sending node is about to resync. This overrides any previous
notification from that node: only one ranged can be resynced at a
time per-node.
- 3.1.3 NEWDISK: informs other nodes that a device is being added to
+3.1.3 NEWDISK
+^^^^^^^^^^^^^
+
+ informs other nodes that a device is being added to
the array. Message contains an identifier for that device. See
below for further details.
- 3.1.4 REMOVE: A failed or spare device is being removed from the
+3.1.4 REMOVE
+^^^^^^^^^^^^
+
+ A failed or spare device is being removed from the
array. The slot-number of the device is included in the message.
- 3.1.5 RE_ADD: A failed device is being re-activated - the assumption
+ 3.1.5 RE_ADD:
+
+ A failed device is being re-activated - the assumption
is that it has been determined to be working again.
- 3.1.6 BITMAP_NEEDS_SYNC: if a node is stopped locally but the bitmap
+ 3.1.6 BITMAP_NEEDS_SYNC:
+
+ If a node is stopped locally but the bitmap
isn't clean, then another node is informed to take the ownership of
resync.
3.2 Communication mechanism
+---------------------------
The DLM LVB is used to communicate within nodes of the cluster. There
are three resources used for the purpose:
- 3.2.1 token: The resource which protects the entire communication
+3.2.1 token
+^^^^^^^^^^^
+ The resource which protects the entire communication
system. The node having the token resource is allowed to
communicate.
- 3.2.2 message: The lock resource which carries the data to
- communicate.
+3.2.2 message
+^^^^^^^^^^^^^
+ The lock resource which carries the data to communicate.
- 3.2.3 ack: The resource, acquiring which means the message has been
+3.2.3 ack
+^^^^^^^^^
+
+ The resource, acquiring which means the message has been
acknowledged by all nodes in the cluster. The BAST of the resource
is used to inform the receiving node that a node wants to
communicate.
The algorithm is:
- 1. receive status - all nodes have concurrent-reader lock on "ack".
+ 1. receive status - all nodes have concurrent-reader lock on "ack"::
- sender receiver receiver
- "ack":CR "ack":CR "ack":CR
+ sender receiver receiver
+ "ack":CR "ack":CR "ack":CR
- 2. sender get EX on "token"
- sender get EX on "message"
- sender receiver receiver
- "token":EX "ack":CR "ack":CR
- "message":EX
- "ack":CR
+ 2. sender get EX on "token",
+ sender get EX on "message"::
+
+ sender receiver receiver
+ "token":EX "ack":CR "ack":CR
+ "message":EX
+ "ack":CR
Sender checks that it still needs to send a message. Messages
received or other events that happened while waiting for the
"token" may have made this message inappropriate or redundant.
- 3. sender writes LVB.
+ 3. sender writes LVB
+
sender down-convert "message" from EX to CW
+
sender try to get EX of "ack"
- [ wait until all receivers have *processed* the "message" ]
-
- [ triggered by bast of "ack" ]
- receiver get CR on "message"
- receiver read LVB
- receiver processes the message
- [ wait finish ]
- receiver releases "ack"
- receiver tries to get PR on "message"
-
- sender receiver receiver
- "token":EX "message":CR "message":CR
- "message":CW
- "ack":EX
+
+ ::
+
+ [ wait until all receivers have *processed* the "message" ]
+
+ [ triggered by bast of "ack" ]
+ receiver get CR on "message"
+ receiver read LVB
+ receiver processes the message
+ [ wait finish ]
+ receiver releases "ack"
+ receiver tries to get PR on "message"
+
+ sender receiver receiver
+ "token":EX "message":CR "message":CR
+ "message":CW
+ "ack":EX
4. triggered by grant of EX on "ack" (indicating all receivers
have processed message)
+
sender down-converts "ack" from EX to CR
+
sender releases "message"
+
sender releases "token"
- receiver upconvert to PR on "message"
- receiver get CR of "ack"
- receiver release "message"
- sender receiver receiver
- "ack":CR "ack":CR "ack":CR
+ ::
+
+ receiver upconvert to PR on "message"
+ receiver get CR of "ack"
+ receiver release "message"
+
+ sender receiver receiver
+ "ack":CR "ack":CR "ack":CR
4. Handling Failures
+====================
4.1 Node Failure
+----------------
When a node fails, the DLM informs the cluster with the slot
number. The node starts a cluster recovery thread. The cluster
@@ -177,11 +224,11 @@ The algorithm is:
- cleans the bitmap of the failed node
- releases bitmap<number> lock of the failed node
- initiates resync of the bitmap on the current node
- md_check_recovery is invoked within recover_bitmaps,
- then md_check_recovery -> metadata_update_start/finish,
- it will lock the communication by lock_comm.
- Which means when one node is resyncing it blocks all
- other nodes from writing anywhere on the array.
+ md_check_recovery is invoked within recover_bitmaps,
+ then md_check_recovery -> metadata_update_start/finish,
+ it will lock the communication by lock_comm.
+ Which means when one node is resyncing it blocks all
+ other nodes from writing anywhere on the array.
The resync process is the regular md resync. However, in a clustered
environment when a resync is performed, it needs to tell other nodes
@@ -198,6 +245,7 @@ The algorithm is:
particular I/O range should be suspended or not.
4.2 Device Failure
+==================
Device failures are handled and communicated with the metadata update
routine. When a node detects a device failure it does not allow
@@ -205,38 +253,41 @@ The algorithm is:
acknowledged by all other nodes.
5. Adding a new Device
+----------------------
For adding a new device, it is necessary that all nodes "see" the new
device to be added. For this, the following algorithm is used:
- 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
+ 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CLUSTER_ADD)
- 2. Node 1 sends a NEWDISK message with uuid and slot number
- 3. Other nodes issue kobject_uevent_env with uuid and slot number
+ 2. Node 1 sends a NEWDISK message with uuid and slot number
+ 3. Other nodes issue kobject_uevent_env with uuid and slot number
(Steps 4,5 could be a udev rule)
- 4. In userspace, the node searches for the disk, perhaps
+ 4. In userspace, the node searches for the disk, perhaps
using blkid -t SUB_UUID=""
- 5. Other nodes issue either of the following depending on whether
+ 5. Other nodes issue either of the following depending on whether
the disk was found:
ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CANDIDATE and
- disc.number set to slot number)
+ disc.number set to slot number)
ioctl(CLUSTERED_DISK_NACK)
- 6. Other nodes drop lock on "no-new-devs" (CR) if device is found
- 7. Node 1 attempts EX lock on "no-new-dev"
- 8. If node 1 gets the lock, it sends METADATA_UPDATED after
+ 6. Other nodes drop lock on "no-new-devs" (CR) if device is found
+ 7. Node 1 attempts EX lock on "no-new-dev"
+ 8. If node 1 gets the lock, it sends METADATA_UPDATED after
unmarking the disk as SpareLocal
- 9. If not (get "no-new-dev" lock), it fails the operation and sends
+ 9. If not (get "no-new-dev" lock), it fails the operation and sends
METADATA_UPDATED.
10. Other nodes get the information whether a disk is added or not
by the following METADATA_UPDATED.
-6. Module interface.
+6. Module interface
+===================
There are 17 call-backs which the md core can make to the cluster
module. Understanding these can give a good overview of the whole
process.
6.1 join(nodes) and leave()
+---------------------------
These are called when an array is started with a clustered bitmap,
and when the array is stopped. join() ensures the cluster is
@@ -244,11 +295,13 @@ The algorithm is:
Only the first 'nodes' nodes in the cluster can use the array.
6.2 slot_number()
+-----------------
Reports the slot number advised by the cluster infrastructure.
Range is from 0 to nodes-1.
6.3 resync_info_update()
+------------------------
This updates the resync range that is stored in the bitmap lock.
The starting point is updated as the resync progresses. The
@@ -256,6 +309,7 @@ The algorithm is:
It does *not* send a RESYNCING message.
6.4 resync_start(), resync_finish()
+-----------------------------------
These are called when resync/recovery/reshape starts or stops.
They update the resyncing range in the bitmap lock and also
@@ -265,8 +319,8 @@ The algorithm is:
resync_finish() also sends a BITMAP_NEEDS_SYNC message which
allows some other node to take over.
-6.5 metadata_update_start(), metadata_update_finish(),
- metadata_update_cancel().
+6.5 metadata_update_start(), metadata_update_finish(), metadata_update_cancel()
+-------------------------------------------------------------------------------
metadata_update_start is used to get exclusive access to
the metadata. If a change is still needed once that access is
@@ -275,6 +329,7 @@ The algorithm is:
can be used to release the lock.
6.6 area_resyncing()
+--------------------
This combines two elements of functionality.
@@ -289,6 +344,7 @@ The algorithm is:
a node failure.
6.7 add_new_disk_start(), add_new_disk_finish(), new_disk_ack()
+---------------------------------------------------------------
These are used to manage the new-disk protocol described above.
When a new device is added, add_new_disk_start() is called before
@@ -300,17 +356,20 @@ The algorithm is:
new_disk_ack() is called.
6.8 remove_disk()
+-----------------
This is called when a spare or failed device is removed from
the array. It causes a REMOVE message to be send to other nodes.
6.9 gather_bitmaps()
+--------------------
This sends a RE_ADD message to all other nodes and then
gathers bitmap information from all bitmaps. This combined
bitmap is then used to recovery the re-added device.
6.10 lock_all_bitmaps() and unlock_all_bitmaps()
+------------------------------------------------
These are called when change bitmap to none. If a node plans
to clear the cluster raid's bitmap, it need to make sure no other
@@ -319,6 +378,7 @@ The algorithm is:
accordingly.
7. Unsupported features
+=======================
There are somethings which are not supported by cluster MD yet.
diff --git a/Documentation/md/raid5-cache.txt b/Documentation/md/raid5-cache.rst
similarity index 92%
rename from Documentation/md/raid5-cache.txt
rename to Documentation/md/raid5-cache.rst
index 2b210f295786..d7a15f44a7c3 100644
--- a/Documentation/md/raid5-cache.txt
+++ b/Documentation/md/raid5-cache.rst
@@ -1,4 +1,6 @@
-RAID5 cache
+================
+RAID 4/5/6 cache
+================
Raid 4/5/6 could include an extra disk for data cache besides normal RAID
disks. The role of RAID disks isn't changed with the cache disk. The cache disk
@@ -6,19 +8,19 @@ caches data to the RAID disks. The cache can be in write-through (supported
since 4.4) or write-back mode (supported since 4.10). mdadm (supported since
3.4) has a new option '--write-journal' to create array with cache. Please
refer to mdadm manual for details. By default (RAID array starts), the cache is
-in write-through mode. A user can switch it to write-back mode by:
+in write-through mode. A user can switch it to write-back mode by::
-echo "write-back" > /sys/block/md0/md/journal_mode
+ echo "write-back" > /sys/block/md0/md/journal_mode
-And switch it back to write-through mode by:
+And switch it back to write-through mode by::
-echo "write-through" > /sys/block/md0/md/journal_mode
+ echo "write-through" > /sys/block/md0/md/journal_mode
In both modes, all writes to the array will hit cache disk first. This means
the cache disk must be fast and sustainable.
--------------------------------------
-write-through mode:
+write-through mode
+==================
This mode mainly fixes the 'write hole' issue. For RAID 4/5/6 array, an unclean
shutdown can cause data in some stripes to not be in consistent state, eg, data
@@ -42,8 +44,8 @@ exposed to 'write hole' again.
In write-through mode, the cache disk isn't required to be big. Several
hundreds megabytes are enough.
---------------------------------------
-write-back mode:
+write-back mode
+===============
write-back mode fixes the 'write hole' issue too, since all write data is
cached on cache disk. But the main goal of 'write-back' cache is to speed up
@@ -64,16 +66,16 @@ data loss.
In write-back mode, MD also caches data in memory. The memory cache includes
the same data stored on cache disk, so a power loss doesn't cause data loss.
The memory cache size has performance impact for the array. It's recommended
-the size is big. A user can configure the size by:
+the size is big. A user can configure the size by::
-echo "2048" > /sys/block/md0/md/stripe_cache_size
+ echo "2048" > /sys/block/md0/md/stripe_cache_size
Too small cache disk will make the write aggregation less efficient in this
mode depending on the workloads. It's recommended to use a cache disk with at
least several gigabytes size in write-back mode.
---------------------------------------
-The implementation:
+The implementation
+==================
The write-through and write-back cache use the same disk format. The cache disk
is organized as a simple write log. The log consists of 'meta data' and 'data'
diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/md/raid5-ppl.rst
similarity index 98%
rename from Documentation/md/raid5-ppl.txt
rename to Documentation/md/raid5-ppl.rst
index bfa092589e00..357e5515bc55 100644
--- a/Documentation/md/raid5-ppl.txt
+++ b/Documentation/md/raid5-ppl.rst
@@ -1,4 +1,6 @@
+==================
Partial Parity Log
+==================
Partial Parity Log (PPL) is a feature available for RAID5 arrays. The issue
addressed by PPL is that after a dirty shutdown, parity of a particular stripe
--
2.21.0
^ permalink raw reply related
* [PATCH v1 00/31] Convert files to ReST - part 2
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This is the second 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-20190612.
The first version of this series had 57 patches. Right now, there are ~80
patches pending applying on this undergoing work. 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. That's the second part.
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.
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_v4.3
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/
Mauro Carvalho Chehab (31):
docs: connector: convert to ReST and rename to connector.rst
docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
docs: lp855x-driver.txt: convert to ReST and move to kernel-api
docs: m68k: convert docs to ReST and rename to *.rst
docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst
docs: console.txt: convert docs to ReST and rename to *.rst
docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst
docs: early-userspace: convert docs to ReST and rename to *.rst
docs: driver-model: convert docs to ReST and rename to *.rst
docs: arm: convert docs to ReST and rename to *.rst
docs: memory-devices: convert ti-emif.txt to ReST
docs: xen-tpmfront.txt: convert it to .rst
docs: bus-devices: ti-gpmc.rst: convert it to ReST
docs: nvmem: convert docs to ReST and rename to *.rst
docs: phy: convert samsung-usb2.txt to ReST format
docs: rbtree.txt: fix Sphinx build warnings
docs: DMA-API-HOWTO.txt: fix an unmarked code block
docs: accounting: convert to ReST
docs: fmc: convert to ReST
docs: hid: convert to ReST
docs: ia64: convert to ReST
docs: leds: convert to ReST
docs: laptops: convert to ReST
docs: iio: convert to ReST
docs: namespaces: convert to ReST
docs: nfc: convert to ReST
docs: md: convert to ReST
docs: mtd: convert to ReST
docs: nvdimm: convert to ReST
docs: xtensa: convert to ReST
docs: mmc: convert to ReST
Documentation/ABI/testing/sysfs-block-device | 2 +-
.../ABI/testing/sysfs-platform-asus-laptop | 2 +-
Documentation/DMA-API-HOWTO.txt | 2 +-
.../{cgroupstats.txt => cgroupstats.rst} | 14 +-
...ay-accounting.txt => delay-accounting.rst} | 61 ++-
Documentation/accounting/index.rst | 14 +
Documentation/accounting/{psi.txt => psi.rst} | 40 +-
...kstats-struct.txt => taskstats-struct.rst} | 79 ++-
.../{taskstats.txt => taskstats.rst} | 15 +-
Documentation/admin-guide/cgroup-v2.rst | 6 +-
.../admin-guide/kernel-parameters.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/arm/Marvell/README | 395 -------------
Documentation/arm/Netwinder | 78 ---
Documentation/arm/SA1100/FreeBird | 21 -
Documentation/arm/SA1100/empeg | 2 -
Documentation/arm/SA1100/serial_UART | 47 --
Documentation/arm/{README => arm.rst} | 50 +-
Documentation/arm/{Booting => booting.rst} | 71 ++-
...ance.txt => cluster-pm-race-avoidance.rst} | 177 +++---
.../arm/{firmware.txt => firmware.rst} | 14 +-
Documentation/arm/index.rst | 80 +++
.../arm/{Interrupts => interrupts.rst} | 86 +--
Documentation/arm/{IXP4xx => ixp4xx.rst} | 61 ++-
...nel_mode_neon.txt => kernel_mode_neon.rst} | 3 +
...er_helpers.txt => kernel_user_helpers.rst} | 79 +--
.../keystone/{knav-qmss.txt => knav-qmss.rst} | 6 +-
.../keystone/{Overview.txt => overview.rst} | 47 +-
Documentation/arm/marvel.rst | 488 +++++++++++++++++
.../arm/{mem_alignment => mem_alignment.rst} | 11 +-
Documentation/arm/{memory.txt => memory.rst} | 9 +-
.../arm/{Microchip/README => microchip.rst} | 63 ++-
Documentation/arm/netwinder.rst | 85 +++
Documentation/arm/nwfpe/index.rst | 11 +
.../nwfpe/{README.FPE => netwinder-fpe.rst} | 24 +-
Documentation/arm/nwfpe/{NOTES => notes.rst} | 3 +
Documentation/arm/nwfpe/{README => nwfpe.rst} | 10 +-
Documentation/arm/nwfpe/{TODO => todo.rst} | 47 +-
Documentation/arm/{OMAP/DSS => omap/dss.rst} | 112 ++--
Documentation/arm/omap/index.rst | 10 +
.../arm/{OMAP/README => omap/omap.rst} | 7 +
.../arm/{OMAP/omap_pm => omap/omap_pm.rst} | 55 +-
Documentation/arm/{Porting => porting.rst} | 14 +-
Documentation/arm/pxa/{mfp.txt => mfp.rst} | 106 ++--
.../{SA1100/ADSBitsy => sa1100/adsbitsy.rst} | 14 +-
.../{SA1100/Assabet => sa1100/assabet.rst} | 185 +++----
.../arm/{SA1100/Brutus => sa1100/brutus.rst} | 45 +-
.../arm/{SA1100/CERF => sa1100/cerf.rst} | 10 +-
Documentation/arm/sa1100/freebird.rst | 25 +
.../graphicsclient.rst} | 46 +-
.../graphicsmaster.rst} | 13 +-
.../HUW_WEBPANEL => sa1100/huw_webpanel.rst} | 8 +-
Documentation/arm/sa1100/index.rst | 23 +
.../arm/{SA1100/Itsy => sa1100/itsy.rst} | 14 +-
.../arm/{SA1100/LART => sa1100/lart.rst} | 3 +-
.../nanoEngine => sa1100/nanoengine.rst} | 6 +-
.../{SA1100/Pangolin => sa1100/pangolin.rst} | 10 +-
.../arm/{SA1100/PLEB => sa1100/pleb.rst} | 6 +-
Documentation/arm/sa1100/serial_uart.rst | 51 ++
.../arm/{SA1100/Tifon => sa1100/tifon.rst} | 4 +-
.../arm/{SA1100/Yopy => sa1100/yopy.rst} | 5 +-
.../cpufreq.rst} | 5 +-
.../eb2410itx.rst} | 5 +-
.../GPIO.txt => samsung-s3c24xx/gpio.rst} | 23 +-
.../H1940.txt => samsung-s3c24xx/h1940.rst} | 5 +-
Documentation/arm/samsung-s3c24xx/index.rst | 18 +
.../NAND.txt => samsung-s3c24xx/nand.rst} | 6 +-
.../overview.rst} | 21 +-
.../s3c2412.rst} | 5 +-
.../s3c2413.rst} | 7 +-
.../smdk2440.rst} | 5 +-
.../suspend.rst} | 20 +-
.../usb-host.rst} | 16 +-
.../bootloader-interface.rst} | 27 +-
.../clksrc-change-registers.awk | 0
.../{Samsung/GPIO.txt => samsung/gpio.rst} | 7 +-
Documentation/arm/samsung/index.rst | 10 +
.../Overview.txt => samsung/overview.rst} | 15 +-
Documentation/arm/{Setup => setup.rst} | 49 +-
.../arm/{SH-Mobile => sh-mobile}/.gitignore | 0
.../overview.txt => spear/overview.rst} | 20 +-
.../arm/sti/{overview.txt => overview.rst} | 21 +-
...h407-overview.txt => stih407-overview.rst} | 9 +-
...h415-overview.txt => stih415-overview.rst} | 8 +-
...h416-overview.txt => stih416-overview.rst} | 5 +-
...h418-overview.txt => stih418-overview.rst} | 9 +-
.../arm/stm32/stm32f429-overview.rst | 7 +-
.../arm/stm32/stm32f746-overview.rst | 7 +-
.../arm/stm32/stm32f769-overview.rst | 7 +-
.../arm/stm32/stm32h743-overview.rst | 7 +-
.../arm/stm32/stm32mp157-overview.rst | 3 +-
Documentation/arm/{sunxi/README => sunxi.rst} | 98 +++-
.../arm/sunxi/{clocks.txt => clocks.rst} | 7 +-
.../arm/{swp_emulation => swp_emulation.rst} | 24 +-
Documentation/arm/{tcm.txt => tcm.rst} | 54 +-
Documentation/arm/{uefi.txt => uefi.rst} | 39 +-
.../release-notes.rst} | 4 +-
Documentation/arm/{vlocks.txt => vlocks.rst} | 9 +-
...cd-panel-cgram.txt => lcd-panel-cgram.rst} | 9 +-
Documentation/backlight/lp855x-driver.rst | 83 +++
Documentation/backlight/lp855x-driver.txt | 66 ---
.../bus-devices/{ti-gpmc.txt => ti-gpmc.rst} | 159 ++++--
.../cma/{debugfs.txt => debugfs.rst} | 8 +-
.../{connector.txt => connector.rst} | 130 ++---
.../console/{console.txt => console.rst} | 63 ++-
Documentation/devicetree/bindings/arm/xen.txt | 2 +-
.../devicetree/booting-without-of.txt | 4 +-
Documentation/driver-api/gpio/driver.rst | 2 +-
.../driver-model/{binding.txt => binding.rst} | 20 +-
.../driver-model/{bus.txt => bus.rst} | 69 +--
.../driver-model/{class.txt => class.rst} | 74 +--
...esign-patterns.txt => design-patterns.rst} | 106 ++--
.../driver-model/{device.txt => device.rst} | 57 +-
.../driver-model/{devres.txt => devres.rst} | 50 +-
.../driver-model/{driver.txt => driver.rst} | 112 ++--
Documentation/driver-model/index.rst | 26 +
.../{overview.txt => overview.rst} | 37 +-
.../{platform.txt => platform.rst} | 30 +-
.../driver-model/{porting.txt => porting.rst} | 333 +++++------
.../{buffer-format.txt => buffer-format.rst} | 19 +-
.../{README => early_userspace_support.rst} | 3 +
Documentation/early-userspace/index.rst | 18 +
Documentation/eisa.txt | 4 +-
Documentation/fb/fbcon.rst | 4 +-
Documentation/filesystems/nfs/nfsroot.txt | 2 +-
.../filesystems/ramfs-rootfs-initramfs.txt | 4 +-
Documentation/fmc/{API.txt => api.rst} | 10 +-
.../fmc/{carrier.txt => carrier.rst} | 65 +--
.../fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst} | 19 +-
.../fmc/{fmc-chardev.txt => fmc-chardev.rst} | 9 +-
.../fmc/{fmc-fakedev.txt => fmc-fakedev.rst} | 13 +-
.../fmc/{fmc-trivial.txt => fmc-trivial.rst} | 11 +-
...-write-eeprom.txt => fmc-write-eeprom.rst} | 36 +-
.../fmc/{identifiers.txt => identifiers.rst} | 20 +-
Documentation/fmc/index.rst | 21 +
.../fmc/{mezzanine.txt => mezzanine.rst} | 34 +-
.../fmc/{parameters.txt => parameters.rst} | 11 +-
.../hid/{hid-alps.txt => hid-alps.rst} | 85 ++-
.../hid/{hid-sensor.txt => hid-sensor.rst} | 192 ++++---
.../{hid-transport.txt => hid-transport.rst} | 82 ++-
Documentation/hid/{hiddev.txt => hiddev.rst} | 154 ++++--
Documentation/hid/{hidraw.txt => hidraw.rst} | 53 +-
Documentation/hid/index.rst | 18 +
Documentation/hid/intel-ish-hid.rst | 485 ++++++++++++++++
Documentation/hid/intel-ish-hid.txt | 454 ---------------
Documentation/hid/{uhid.txt => uhid.rst} | 46 +-
Documentation/hwmon/submitting-patches.rst | 2 +-
.../ia64/{aliasing.txt => aliasing.rst} | 73 ++-
Documentation/ia64/{efirtc.txt => efirtc.rst} | 118 ++--
.../ia64/{err_inject.txt => err_inject.rst} | 349 ++++++------
Documentation/ia64/{fsys.txt => fsys.rst} | 127 +++--
Documentation/ia64/{README => ia64.rst} | 26 +-
Documentation/ia64/index.rst | 18 +
.../ia64/{IRQ-redir.txt => irq-redir.rst} | 31 +-
Documentation/ia64/{mca.txt => mca.rst} | 10 +-
Documentation/ia64/{serial.txt => serial.rst} | 36 +-
Documentation/ia64/xen.rst | 206 +++++++
Documentation/ia64/xen.txt | 183 -------
.../iio/{ep93xx_adc.txt => ep93xx_adc.rst} | 15 +-
.../{iio_configfs.txt => iio_configfs.rst} | 52 +-
Documentation/iio/index.rst | 12 +
Documentation/index.rst | 1 +
Documentation/input/input.rst | 2 +-
.../{asus-laptop.txt => asus-laptop.rst} | 92 ++--
...otection.txt => disk-shock-protection.rst} | 32 +-
Documentation/laptops/index.rst | 17 +
.../{laptop-mode.txt => laptop-mode.rst} | 509 +++++++++--------
.../{sony-laptop.txt => sony-laptop.rst} | 58 +-
.../laptops/{sonypi.txt => sonypi.rst} | 28 +-
.../{thinkpad-acpi.txt => thinkpad-acpi.rst} | 367 ++++++++-----
.../{toshiba_haps.txt => toshiba_haps.rst} | 47 +-
Documentation/leds/index.rst | 25 +
.../leds/{leds-blinkm.txt => leds-blinkm.rst} | 64 ++-
...s-class-flash.txt => leds-class-flash.rst} | 49 +-
.../leds/{leds-class.txt => leds-class.rst} | 15 +-
.../leds/{leds-lm3556.txt => leds-lm3556.rst} | 100 +++-
.../leds/{leds-lp3944.txt => leds-lp3944.rst} | 23 +-
Documentation/leds/leds-lp5521.rst | 115 ++++
Documentation/leds/leds-lp5521.txt | 101 ----
Documentation/leds/leds-lp5523.rst | 147 +++++
Documentation/leds/leds-lp5523.txt | 130 -----
Documentation/leds/leds-lp5562.rst | 137 +++++
Documentation/leds/leds-lp5562.txt | 120 ----
Documentation/leds/leds-lp55xx.rst | 224 ++++++++
Documentation/leds/leds-lp55xx.txt | 194 -------
Documentation/leds/leds-mlxcpld.rst | 118 ++++
Documentation/leds/leds-mlxcpld.txt | 110 ----
...edtrig-oneshot.txt => ledtrig-oneshot.rst} | 11 +-
...ig-transient.txt => ledtrig-transient.rst} | 63 ++-
...edtrig-usbport.txt => ledtrig-usbport.rst} | 11 +-
Documentation/leds/{uleds.txt => uleds.rst} | 5 +-
Documentation/m68k/index.rst | 17 +
...{kernel-options.txt => kernel-options.rst} | 319 ++++++-----
Documentation/md/index.rst | 12 +
.../md/{md-cluster.txt => md-cluster.rst} | 188 ++++---
.../md/{raid5-cache.txt => raid5-cache.rst} | 28 +-
.../md/{raid5-ppl.txt => raid5-ppl.rst} | 2 +
.../{ti-emif.txt => ti-emif.rst} | 27 +-
Documentation/mmc/index.rst | 13 +
.../{mmc-async-req.txt => mmc-async-req.rst} | 53 +-
.../{mmc-dev-attrs.txt => mmc-dev-attrs.rst} | 32 +-
.../{mmc-dev-parts.txt => mmc-dev-parts.rst} | 13 +-
.../mmc/{mmc-tools.txt => mmc-tools.rst} | 5 +-
Documentation/mtd/index.rst | 12 +
.../mtd/{intel-spi.txt => intel-spi.rst} | 46 +-
.../mtd/{nand_ecc.txt => nand_ecc.rst} | 481 ++++++++--------
.../mtd/{spi-nor.txt => spi-nor.rst} | 7 +-
...bility-list.txt => compatibility-list.rst} | 10 +-
Documentation/namespaces/index.rst | 11 +
...ource-control.txt => resource-control.rst} | 4 +
Documentation/nfc/index.rst | 11 +
.../nfc/{nfc-hci.txt => nfc-hci.rst} | 163 +++---
.../nfc/{nfc-pn544.txt => nfc-pn544.rst} | 6 +-
Documentation/nvdimm/{btt.txt => btt.rst} | 140 ++---
Documentation/nvdimm/index.rst | 12 +
.../nvdimm/{nvdimm.txt => nvdimm.rst} | 518 ++++++++++--------
.../nvdimm/{security.txt => security.rst} | 4 +-
Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 ++--
.../{samsung-usb2.txt => samsung-usb2.rst} | 62 ++-
Documentation/pti/pti_intel_mid.rst | 106 ++++
Documentation/pti/pti_intel_mid.txt | 99 ----
Documentation/rbtree.txt | 6 +-
.../{xen-tpmfront.txt => xen-tpmfront.rst} | 103 ++--
Documentation/sysctl/vm.txt | 4 +-
Documentation/translations/zh_CN/arm/Booting | 4 +-
.../zh_CN/arm/kernel_user_helpers.txt | 4 +-
.../xtensa/{atomctl.txt => atomctl.rst} | 13 +-
.../xtensa/{booting.txt => booting.rst} | 5 +-
Documentation/xtensa/index.rst | 12 +
Documentation/xtensa/mmu.rst | 195 +++++++
Documentation/xtensa/mmu.txt | 189 -------
MAINTAINERS | 18 +-
arch/arm/Kconfig | 2 +-
arch/arm/common/mcpm_entry.c | 2 +-
arch/arm/common/mcpm_head.S | 2 +-
arch/arm/common/vlock.S | 2 +-
arch/arm/include/asm/setup.h | 2 +-
arch/arm/include/uapi/asm/setup.h | 2 +-
arch/arm/kernel/entry-armv.S | 2 +-
arch/arm/mach-exynos/common.h | 2 +-
arch/arm/mach-ixp4xx/Kconfig | 14 +-
arch/arm/mach-s3c24xx/pm.c | 2 +-
arch/arm/mm/Kconfig | 4 +-
arch/arm/plat-samsung/Kconfig | 6 +-
arch/arm/tools/mach-types | 2 +-
arch/arm64/Kconfig | 2 +-
arch/arm64/kernel/kuser32.S | 2 +-
arch/ia64/kernel/efi.c | 2 +-
arch/ia64/kernel/fsys.S | 2 +-
arch/ia64/mm/ioremap.c | 2 +-
arch/ia64/pci/pci.c | 2 +-
arch/mips/bmips/setup.c | 2 +-
arch/xtensa/include/asm/initialize_mmu.h | 2 +-
drivers/base/platform.c | 2 +-
drivers/char/Kconfig | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-cipher.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-core.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-hash.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss.h | 2 +-
drivers/gpio/gpio-cs5535.c | 2 +-
drivers/iio/Kconfig | 2 +-
drivers/input/touchscreen/sun4i-ts.c | 2 +-
drivers/leds/trigger/Kconfig | 2 +-
drivers/leds/trigger/ledtrig-transient.c | 2 +-
drivers/mtd/nand/raw/nand_ecc.c | 2 +-
drivers/net/ethernet/intel/ice/ice_main.c | 2 +-
drivers/nvdimm/Kconfig | 2 +-
drivers/platform/x86/Kconfig | 4 +-
drivers/tty/Kconfig | 2 +-
drivers/tty/serial/Kconfig | 2 +-
drivers/w1/Kconfig | 2 +-
include/linux/connector.h | 63 ++-
init/Kconfig | 2 +-
net/netfilter/Kconfig | 2 +-
samples/Kconfig | 2 +-
scripts/coccinelle/free/devm_free.cocci | 2 +-
usr/Kconfig | 2 +-
277 files changed, 8166 insertions(+), 6117 deletions(-)
rename Documentation/accounting/{cgroupstats.txt => cgroupstats.rst} (77%)
rename Documentation/accounting/{delay-accounting.txt => delay-accounting.rst} (77%)
create mode 100644 Documentation/accounting/index.rst
rename Documentation/accounting/{psi.txt => psi.rst} (91%)
rename Documentation/accounting/{taskstats-struct.txt => taskstats-struct.rst} (78%)
rename Documentation/accounting/{taskstats.txt => taskstats.rst} (95%)
delete mode 100644 Documentation/arm/Marvell/README
delete mode 100644 Documentation/arm/Netwinder
delete mode 100644 Documentation/arm/SA1100/FreeBird
delete mode 100644 Documentation/arm/SA1100/empeg
delete mode 100644 Documentation/arm/SA1100/serial_UART
rename Documentation/arm/{README => arm.rst} (88%)
rename Documentation/arm/{Booting => booting.rst} (89%)
rename Documentation/arm/{cluster-pm-race-avoidance.txt => cluster-pm-race-avoidance.rst} (84%)
rename Documentation/arm/{firmware.txt => firmware.rst} (86%)
create mode 100644 Documentation/arm/index.rst
rename Documentation/arm/{Interrupts => interrupts.rst} (81%)
rename Documentation/arm/{IXP4xx => ixp4xx.rst} (84%)
rename Documentation/arm/{kernel_mode_neon.txt => kernel_mode_neon.rst} (99%)
rename Documentation/arm/{kernel_user_helpers.txt => kernel_user_helpers.rst} (78%)
rename Documentation/arm/keystone/{knav-qmss.txt => knav-qmss.rst} (92%)
rename Documentation/arm/keystone/{Overview.txt => overview.rst} (59%)
create mode 100644 Documentation/arm/marvel.rst
rename Documentation/arm/{mem_alignment => mem_alignment.rst} (89%)
rename Documentation/arm/{memory.txt => memory.rst} (90%)
rename Documentation/arm/{Microchip/README => microchip.rst} (92%)
create mode 100644 Documentation/arm/netwinder.rst
create mode 100644 Documentation/arm/nwfpe/index.rst
rename Documentation/arm/nwfpe/{README.FPE => netwinder-fpe.rst} (94%)
rename Documentation/arm/nwfpe/{NOTES => notes.rst} (99%)
rename Documentation/arm/nwfpe/{README => nwfpe.rst} (98%)
rename Documentation/arm/nwfpe/{TODO => todo.rst} (75%)
rename Documentation/arm/{OMAP/DSS => omap/dss.rst} (86%)
create mode 100644 Documentation/arm/omap/index.rst
rename Documentation/arm/{OMAP/README => omap/omap.rst} (62%)
rename Documentation/arm/{OMAP/omap_pm => omap/omap_pm.rst} (83%)
rename Documentation/arm/{Porting => porting.rst} (94%)
rename Documentation/arm/pxa/{mfp.txt => mfp.rst} (83%)
rename Documentation/arm/{SA1100/ADSBitsy => sa1100/adsbitsy.rst} (90%)
rename Documentation/arm/{SA1100/Assabet => sa1100/assabet.rst} (62%)
rename Documentation/arm/{SA1100/Brutus => sa1100/brutus.rst} (75%)
rename Documentation/arm/{SA1100/CERF => sa1100/cerf.rst} (91%)
create mode 100644 Documentation/arm/sa1100/freebird.rst
rename Documentation/arm/{SA1100/GraphicsClient => sa1100/graphicsclient.rst} (87%)
rename Documentation/arm/{SA1100/GraphicsMaster => sa1100/graphicsmaster.rst} (92%)
rename Documentation/arm/{SA1100/HUW_WEBPANEL => sa1100/huw_webpanel.rst} (78%)
create mode 100644 Documentation/arm/sa1100/index.rst
rename Documentation/arm/{SA1100/Itsy => sa1100/itsy.rst} (88%)
rename Documentation/arm/{SA1100/LART => sa1100/lart.rst} (90%)
rename Documentation/arm/{SA1100/nanoEngine => sa1100/nanoengine.rst} (74%)
rename Documentation/arm/{SA1100/Pangolin => sa1100/pangolin.rst} (81%)
rename Documentation/arm/{SA1100/PLEB => sa1100/pleb.rst} (95%)
create mode 100644 Documentation/arm/sa1100/serial_uart.rst
rename Documentation/arm/{SA1100/Tifon => sa1100/tifon.rst} (88%)
rename Documentation/arm/{SA1100/Yopy => sa1100/yopy.rst} (74%)
rename Documentation/arm/{Samsung-S3C24XX/CPUfreq.txt => samsung-s3c24xx/cpufreq.rst} (96%)
rename Documentation/arm/{Samsung-S3C24XX/EB2410ITX.txt => samsung-s3c24xx/eb2410itx.rst} (92%)
rename Documentation/arm/{Samsung-S3C24XX/GPIO.txt => samsung-s3c24xx/gpio.rst} (89%)
rename Documentation/arm/{Samsung-S3C24XX/H1940.txt => samsung-s3c24xx/h1940.rst} (94%)
create mode 100644 Documentation/arm/samsung-s3c24xx/index.rst
rename Documentation/arm/{Samsung-S3C24XX/NAND.txt => samsung-s3c24xx/nand.rst} (92%)
rename Documentation/arm/{Samsung-S3C24XX/Overview.txt => samsung-s3c24xx/overview.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/S3C2412.txt => samsung-s3c24xx/s3c2412.rst} (96%)
rename Documentation/arm/{Samsung-S3C24XX/S3C2413.txt => samsung-s3c24xx/s3c2413.rst} (77%)
rename Documentation/arm/{Samsung-S3C24XX/SMDK2440.txt => samsung-s3c24xx/smdk2440.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/Suspend.txt => samsung-s3c24xx/suspend.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/USB-Host.txt => samsung-s3c24xx/usb-host.rst} (94%)
rename Documentation/arm/{Samsung/Bootloader-interface.txt => samsung/bootloader-interface.rst} (72%)
rename Documentation/arm/{Samsung => samsung}/clksrc-change-registers.awk (100%)
rename Documentation/arm/{Samsung/GPIO.txt => samsung/gpio.rst} (87%)
create mode 100644 Documentation/arm/samsung/index.rst
rename Documentation/arm/{Samsung/Overview.txt => samsung/overview.rst} (86%)
rename Documentation/arm/{Setup => setup.rst} (87%)
rename Documentation/arm/{SH-Mobile => sh-mobile}/.gitignore (100%)
rename Documentation/arm/{SPEAr/overview.txt => spear/overview.rst} (91%)
rename Documentation/arm/sti/{overview.txt => overview.rst} (82%)
rename Documentation/arm/sti/{stih407-overview.txt => stih407-overview.rst} (82%)
rename Documentation/arm/sti/{stih415-overview.txt => stih415-overview.rst} (79%)
rename Documentation/arm/sti/{stih416-overview.txt => stih416-overview.rst} (83%)
rename Documentation/arm/sti/{stih418-overview.txt => stih418-overview.rst} (83%)
rename Documentation/arm/{sunxi/README => sunxi.rst} (83%)
rename Documentation/arm/sunxi/{clocks.txt => clocks.rst} (92%)
rename Documentation/arm/{swp_emulation => swp_emulation.rst} (63%)
rename Documentation/arm/{tcm.txt => tcm.rst} (86%)
rename Documentation/arm/{uefi.txt => uefi.rst} (63%)
rename Documentation/arm/{VFP/release-notes.txt => vfp/release-notes.rst} (92%)
rename Documentation/arm/{vlocks.txt => vlocks.rst} (98%)
rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%)
create mode 100644 Documentation/backlight/lp855x-driver.rst
delete mode 100644 Documentation/backlight/lp855x-driver.txt
rename Documentation/bus-devices/{ti-gpmc.txt => ti-gpmc.rst} (58%)
rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%)
rename Documentation/connector/{connector.txt => connector.rst} (57%)
rename Documentation/console/{console.txt => console.rst} (80%)
rename Documentation/driver-model/{binding.txt => binding.rst} (92%)
rename Documentation/driver-model/{bus.txt => bus.rst} (76%)
rename Documentation/driver-model/{class.txt => class.rst} (75%)
rename Documentation/driver-model/{design-patterns.txt => design-patterns.rst} (59%)
rename Documentation/driver-model/{device.txt => device.rst} (71%)
rename Documentation/driver-model/{devres.txt => devres.rst} (93%)
rename Documentation/driver-model/{driver.txt => driver.rst} (75%)
create mode 100644 Documentation/driver-model/index.rst
rename Documentation/driver-model/{overview.txt => overview.rst} (90%)
rename Documentation/driver-model/{platform.txt => platform.rst} (95%)
rename Documentation/driver-model/{porting.txt => porting.rst} (62%)
rename Documentation/early-userspace/{buffer-format.txt => buffer-format.rst} (91%)
rename Documentation/early-userspace/{README => early_userspace_support.rst} (99%)
create mode 100644 Documentation/early-userspace/index.rst
rename Documentation/fmc/{API.txt => api.rst} (87%)
rename Documentation/fmc/{carrier.txt => carrier.rst} (91%)
rename Documentation/fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst} (88%)
rename Documentation/fmc/{fmc-chardev.txt => fmc-chardev.rst} (96%)
rename Documentation/fmc/{fmc-fakedev.txt => fmc-fakedev.rst} (85%)
rename Documentation/fmc/{fmc-trivial.txt => fmc-trivial.rst} (69%)
rename Documentation/fmc/{fmc-write-eeprom.txt => fmc-write-eeprom.rst} (79%)
rename Documentation/fmc/{identifiers.txt => identifiers.rst} (93%)
create mode 100644 Documentation/fmc/index.rst
rename Documentation/fmc/{mezzanine.txt => mezzanine.rst} (87%)
rename Documentation/fmc/{parameters.txt => parameters.rst} (96%)
rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
create mode 100644 Documentation/hid/index.rst
create mode 100644 Documentation/hid/intel-ish-hid.rst
delete mode 100644 Documentation/hid/intel-ish-hid.txt
rename Documentation/hid/{uhid.txt => uhid.rst} (94%)
rename Documentation/ia64/{aliasing.txt => aliasing.rst} (83%)
rename Documentation/ia64/{efirtc.txt => efirtc.rst} (70%)
rename Documentation/ia64/{err_inject.txt => err_inject.rst} (82%)
rename Documentation/ia64/{fsys.txt => fsys.rst} (76%)
rename Documentation/ia64/{README => ia64.rst} (61%)
create mode 100644 Documentation/ia64/index.rst
rename Documentation/ia64/{IRQ-redir.txt => irq-redir.rst} (86%)
rename Documentation/ia64/{mca.txt => mca.rst} (96%)
rename Documentation/ia64/{serial.txt => serial.rst} (87%)
create mode 100644 Documentation/ia64/xen.rst
delete mode 100644 Documentation/ia64/xen.txt
rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
create mode 100644 Documentation/iio/index.rst
rename Documentation/laptops/{asus-laptop.txt => asus-laptop.rst} (84%)
rename Documentation/laptops/{disk-shock-protection.txt => disk-shock-protection.rst} (91%)
create mode 100644 Documentation/laptops/index.rst
rename Documentation/laptops/{laptop-mode.txt => laptop-mode.rst} (62%)
rename Documentation/laptops/{sony-laptop.txt => sony-laptop.rst} (85%)
rename Documentation/laptops/{sonypi.txt => sonypi.rst} (87%)
rename Documentation/laptops/{thinkpad-acpi.txt => thinkpad-acpi.rst} (89%)
rename Documentation/laptops/{toshiba_haps.txt => toshiba_haps.rst} (60%)
create mode 100644 Documentation/leds/index.rst
rename Documentation/leds/{leds-blinkm.txt => leds-blinkm.rst} (57%)
rename Documentation/leds/{leds-class-flash.txt => leds-class-flash.rst} (74%)
rename Documentation/leds/{leds-class.txt => leds-class.rst} (92%)
rename Documentation/leds/{leds-lm3556.txt => leds-lm3556.rst} (70%)
rename Documentation/leds/{leds-lp3944.txt => leds-lp3944.rst} (78%)
create mode 100644 Documentation/leds/leds-lp5521.rst
delete mode 100644 Documentation/leds/leds-lp5521.txt
create mode 100644 Documentation/leds/leds-lp5523.rst
delete mode 100644 Documentation/leds/leds-lp5523.txt
create mode 100644 Documentation/leds/leds-lp5562.rst
delete mode 100644 Documentation/leds/leds-lp5562.txt
create mode 100644 Documentation/leds/leds-lp55xx.rst
delete mode 100644 Documentation/leds/leds-lp55xx.txt
create mode 100644 Documentation/leds/leds-mlxcpld.rst
delete mode 100644 Documentation/leds/leds-mlxcpld.txt
rename Documentation/leds/{ledtrig-oneshot.txt => ledtrig-oneshot.rst} (90%)
rename Documentation/leds/{ledtrig-transient.txt => ledtrig-transient.rst} (81%)
rename Documentation/leds/{ledtrig-usbport.txt => ledtrig-usbport.rst} (86%)
rename Documentation/leds/{uleds.txt => uleds.rst} (95%)
create mode 100644 Documentation/m68k/index.rst
rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%)
create mode 100644 Documentation/md/index.rst
rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)
rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%)
create mode 100644 Documentation/mmc/index.rst
rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%)
rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%)
rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%)
rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%)
create mode 100644 Documentation/mtd/index.rst
rename Documentation/mtd/{intel-spi.txt => intel-spi.rst} (71%)
rename Documentation/mtd/{nand_ecc.txt => nand_ecc.rst} (67%)
rename Documentation/mtd/{spi-nor.txt => spi-nor.rst} (94%)
rename Documentation/namespaces/{compatibility-list.txt => compatibility-list.rst} (86%)
create mode 100644 Documentation/namespaces/index.rst
rename Documentation/namespaces/{resource-control.txt => resource-control.rst} (89%)
create mode 100644 Documentation/nfc/index.rst
rename Documentation/nfc/{nfc-hci.txt => nfc-hci.rst} (71%)
rename Documentation/nfc/{nfc-pn544.txt => nfc-pn544.rst} (82%)
rename Documentation/nvdimm/{btt.txt => btt.rst} (71%)
create mode 100644 Documentation/nvdimm/index.rst
rename Documentation/nvdimm/{nvdimm.txt => nvdimm.rst} (60%)
rename Documentation/nvdimm/{security.txt => security.rst} (99%)
rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)
rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%)
create mode 100644 Documentation/pti/pti_intel_mid.rst
delete mode 100644 Documentation/pti/pti_intel_mid.txt
rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)
rename Documentation/xtensa/{atomctl.txt => atomctl.rst} (81%)
rename Documentation/xtensa/{booting.txt => booting.rst} (91%)
create mode 100644 Documentation/xtensa/index.rst
create mode 100644 Documentation/xtensa/mmu.rst
delete mode 100644 Documentation/xtensa/mmu.txt
--
2.21.0
^ permalink raw reply
* [PATCH v1 15/31] docs: phy: convert samsung-usb2.txt to ReST format
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Kamil Debski, Sylwester Nawrocki
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
In order to merge it into a Sphinx book, we need first to
convert to ReST.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{samsung-usb2.txt => samsung-usb2.rst} | 62 ++++++++++---------
MAINTAINERS | 2 +-
2 files changed, 34 insertions(+), 30 deletions(-)
rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%)
diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.rst
similarity index 77%
rename from Documentation/phy/samsung-usb2.txt
rename to Documentation/phy/samsung-usb2.rst
index ed12d437189d..98b5952fcb97 100644
--- a/Documentation/phy/samsung-usb2.txt
+++ b/Documentation/phy/samsung-usb2.rst
@@ -1,9 +1,11 @@
-.------------------------------------------------------------------------------+
-| Samsung USB 2.0 PHY adaptation layer |
-+-----------------------------------------------------------------------------+'
+:orphan:
-| 1. Description
-+----------------
+====================================
+Samsung USB 2.0 PHY adaptation layer
+====================================
+
+1. Description
+--------------
The architecture of the USB 2.0 PHY module in Samsung SoCs is similar
among many SoCs. In spite of the similarities it proved difficult to
@@ -14,8 +16,8 @@ the PHY powering up process had to be altered. This adaptation layer is
a compromise between having separate drivers and having a single driver
with added support for many special cases.
-| 2. Files description
-+----------------------
+2. Files description
+--------------------
- phy-samsung-usb2.c
This is the main file of the adaptation layer. This file contains
@@ -32,44 +34,45 @@ with added support for many special cases.
driver. In addition it should contain extern declarations for
structures that describe particular SoCs.
-| 3. Supporting SoCs
-+--------------------
+3. Supporting SoCs
+------------------
To support a new SoC a new file should be added to the drivers/phy
directory. Each SoC's configuration is stored in an instance of the
-struct samsung_usb2_phy_config.
+struct samsung_usb2_phy_config::
-struct samsung_usb2_phy_config {
+ struct samsung_usb2_phy_config {
const struct samsung_usb2_common_phy *phys;
int (*rate_to_clk)(unsigned long, u32 *);
unsigned int num_phys;
bool has_mode_switch;
-};
+ };
-The num_phys is the number of phys handled by the driver. *phys is an
+The num_phys is the number of phys handled by the driver. `*phys` is an
array that contains the configuration for each phy. The has_mode_switch
property is a boolean flag that determines whether the SoC has USB host
and device on a single pair of pins. If so, a special register has to
be modified to change the internal routing of these pins between a USB
device or host module.
-For example the configuration for Exynos 4210 is following:
+For example the configuration for Exynos 4210 is following::
-const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
+ const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
.has_mode_switch = 0,
.num_phys = EXYNOS4210_NUM_PHYS,
.phys = exynos4210_phys,
.rate_to_clk = exynos4210_rate_to_clk,
-}
+ }
+
+- `int (*rate_to_clk)(unsigned long, u32 *)`
-- int (*rate_to_clk)(unsigned long, u32 *)
The rate_to_clk callback is to convert the rate of the clock
used as the reference clock for the PHY module to the value
that should be written in the hardware register.
-The exynos4210_phys configuration array is as follows:
+The exynos4210_phys configuration array is as follows::
-static const struct samsung_usb2_common_phy exynos4210_phys[] = {
+ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
{
.label = "device",
.id = EXYNOS4210_DEVICE,
@@ -95,29 +98,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
.power_off = exynos4210_power_off,
},
{},
-};
+ };
+
+- `int (*power_on)(struct samsung_usb2_phy_instance *);`
+ `int (*power_off)(struct samsung_usb2_phy_instance *);`
-- int (*power_on)(struct samsung_usb2_phy_instance *);
-- int (*power_off)(struct samsung_usb2_phy_instance *);
These two callbacks are used to power on and power off the phy
by modifying appropriate registers.
Final change to the driver is adding appropriate compatible value to the
phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were
-added to the struct of_device_id samsung_usb2_phy_of_match[] array:
+added to the struct of_device_id samsung_usb2_phy_of_match[] array::
-#ifdef CONFIG_PHY_EXYNOS4210_USB2
+ #ifdef CONFIG_PHY_EXYNOS4210_USB2
{
.compatible = "samsung,exynos4210-usb2-phy",
.data = &exynos4210_usb2_phy_config,
},
-#endif
+ #endif
To add further flexibility to the driver the Kconfig file enables to
include support for selected SoCs in the compiled driver. The Kconfig
-entry for Exynos 4210 is following:
+entry for Exynos 4210 is following::
-config PHY_EXYNOS4210_USB2
+ config PHY_EXYNOS4210_USB2
bool "Support for Exynos 4210"
depends on PHY_SAMSUNG_USB2
depends on CPU_EXYNOS4210
@@ -128,8 +132,8 @@ config PHY_EXYNOS4210_USB2
phys are available - device, host, HSCI0 and HSCI1.
The newly created file that supports the new SoC has to be also added to the
-Makefile. In case of Exynos 4210 the added line is following:
+Makefile. In case of Exynos 4210 the added line is following::
-obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o
+ obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o
After completing these steps the support for the new SoC should be ready.
diff --git a/MAINTAINERS b/MAINTAINERS
index 62a6771e261f..8d39979e4091 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13963,7 +13963,7 @@ M: Sylwester Nawrocki <s.nawrocki@samsung.com>
L: linux-kernel@vger.kernel.org
S: Supported
F: Documentation/devicetree/bindings/phy/samsung-phy.txt
-F: Documentation/phy/samsung-usb2.txt
+F: Documentation/phy/samsung-usb2.rst
F: drivers/phy/samsung/phy-exynos4210-usb2.c
F: drivers/phy/samsung/phy-exynos4x12-usb2.c
F: drivers/phy/samsung/phy-exynos5250-usb2.c
--
2.21.0
^ permalink raw reply related
* [PATCH v1 19/31] docs: fmc: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the FMC 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 least some of this files seemed to be using some markup
language similar to ReST, but with a different markup for
cross-references. Adjust those to use the ReST syntax.
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/fmc/{API.txt => api.rst} | 10 +--
.../fmc/{carrier.txt => carrier.rst} | 65 ++++++++++---------
.../fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst} | 19 ++++--
.../fmc/{fmc-chardev.txt => fmc-chardev.rst} | 9 +--
.../fmc/{fmc-fakedev.txt => fmc-fakedev.rst} | 13 ++--
.../fmc/{fmc-trivial.txt => fmc-trivial.rst} | 11 ++--
...-write-eeprom.txt => fmc-write-eeprom.rst} | 36 +++++-----
.../fmc/{identifiers.txt => identifiers.rst} | 20 +++---
Documentation/fmc/index.rst | 21 ++++++
.../fmc/{mezzanine.txt => mezzanine.rst} | 34 +++++-----
.../fmc/{parameters.txt => parameters.rst} | 11 ++--
11 files changed, 147 insertions(+), 102 deletions(-)
rename Documentation/fmc/{API.txt => api.rst} (87%)
rename Documentation/fmc/{carrier.txt => carrier.rst} (91%)
rename Documentation/fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst} (88%)
rename Documentation/fmc/{fmc-chardev.txt => fmc-chardev.rst} (96%)
rename Documentation/fmc/{fmc-fakedev.txt => fmc-fakedev.rst} (85%)
rename Documentation/fmc/{fmc-trivial.txt => fmc-trivial.rst} (69%)
rename Documentation/fmc/{fmc-write-eeprom.txt => fmc-write-eeprom.rst} (79%)
rename Documentation/fmc/{identifiers.txt => identifiers.rst} (93%)
create mode 100644 Documentation/fmc/index.rst
rename Documentation/fmc/{mezzanine.txt => mezzanine.rst} (87%)
rename Documentation/fmc/{parameters.txt => parameters.rst} (96%)
diff --git a/Documentation/fmc/API.txt b/Documentation/fmc/api.rst
similarity index 87%
rename from Documentation/fmc/API.txt
rename to Documentation/fmc/api.rst
index 06b06b92c794..157a7343180c 100644
--- a/Documentation/fmc/API.txt
+++ b/Documentation/fmc/api.rst
@@ -2,7 +2,7 @@ Functions Exported by fmc.ko
****************************
The FMC core exports the usual 4 functions that are needed for a bus to
-work, and a few more:
+work, and a few more::
int fmc_driver_register(struct fmc_driver *drv);
void fmc_driver_unregister(struct fmc_driver *drv);
@@ -20,9 +20,9 @@ work, and a few more:
int fmc_reprogram(struct fmc_device *f, struct fmc_driver *d, char *gw,
int sdb_entry);
-The data structure that describe a device is detailed in *note FMC
-Device::, the one that describes a driver is detailed in *note FMC
-Driver::. Please note that structures of type fmc_device must be
+The data structure that describe a device is detailed in :ref:`fmc_device`,
+the one that describes a driver is detailed in :ref:`fmc_driver`.
+Please note that structures of type fmc_device must be
allocated by the caller, but must not be released after unregistering.
The fmc-bus itself takes care of releasing the structure when their use
count reaches zero - actually, the device model does that in lieu of us.
@@ -39,7 +39,7 @@ should register as a group only mezzanines that are driven by the same
FPGA, for the reason outlined above.
Finally, the fmc_reprogram function calls the reprogram method (see
-*note The API Offered by Carriers:: and also scans the memory area for
+:ref:`fmc_api_offered_by_carriers`) and also scans the memory area for
an SDB tree. You can pass -1 as sdb_entry to disable such scan.
Otherwise, the function fails if no tree is found at the specified
entry point. The function is meant to factorize common code, and by
diff --git a/Documentation/fmc/carrier.txt b/Documentation/fmc/carrier.rst
similarity index 91%
rename from Documentation/fmc/carrier.txt
rename to Documentation/fmc/carrier.rst
index 5e4f1dd3e98b..06ba443441e1 100644
--- a/Documentation/fmc/carrier.txt
+++ b/Documentation/fmc/carrier.rst
@@ -1,5 +1,8 @@
+.. _fmc_device:
+
+==========
FMC Device
-**********
+==========
Within the Linux bus framework, the FMC device is created and
registered by the carrier driver. For example, the PCI driver for the
@@ -25,7 +28,7 @@ change for compatible changes (like a new flag) and the major number
will increase when an incompatible change happens (for example, a
change in layout of some fmc data structures). Device writers should
just set it to the value FMC_VERSION, and be ready to get back -EINVAL
-at registration time.
+at registration time::
struct fmc_device {
unsigned long version;
@@ -123,13 +126,15 @@ As I write this, she SPEC carrier is already completely functional in
the fmc-bus environment, and is a good reference to look at.
+.. _fmc_api_offered_by_carriers:
+
The API Offered by Carriers
===========================
The carrier provides a number of methods by means of the
-`fmc_operations' structure, which currently is defined like this
+`fmc_operations` structure, which currently is defined like this
(again, it is a moving target, please refer to the header rather than
-this document):
+this document)::
struct fmc_operations {
uint32_t (*readl)(struct fmc_device *fmc, int offset);
@@ -148,8 +153,7 @@ this document):
The individual methods perform the following tasks:
-`readl'
-`writel'
+`readl`, `writel`
These functions access FPGA registers by whatever means the
carrier offers. They are not expected to fail, and most of the time
they will just make a memory access to the host bus. If the
@@ -161,20 +165,20 @@ The individual methods perform the following tasks:
or other non-local carriers, error-management is still to be
defined.
-`validate'
+`validate`
Module parameters are used to manage different applications for
two or more boards of the same kind. Validation is based on the
busid module parameter, if provided, and returns the matching
- index in the associated array. See *note Module Parameters:: in in
- doubt. If no match is found, `-ENOENT' is returned; if the user
- didn't pass `busid=', all devices will pass validation. The value
+ index in the associated array. See :ref:`fmc_module_parameters` in in
+ doubt. If no match is found, `-ENOENT` is returned; if the user
+ didn't pass `busid=`, all devices will pass validation. The value
returned by the validate method can be used as index into other
- parameters (for example, some drivers use the `lm32=' parameter in
- this way). Such "generic parameters" are documented in *note
- Module Parameters::, below. The validate method is used by
- `fmc-trivial.ko', described in *note fmc-trivial::.
+ parameters (for example, some drivers use the `lm32=` parameter in
+ this way). Such "generic parameters" are documented in
+ :ref:`fmc_module_parameters` below. The validate method is used by
+ `fmc-trivial.ko`, described in :ref:`fmc_trivial`.
-`reprogram'
+`reprogram`
The carrier enumerates FMC devices by loading a standard (or
golden) FPGA binary that allows EEPROM access. Each driver, then,
will need to reprogram the FPGA by calling this function. If the
@@ -182,31 +186,28 @@ The individual methods perform the following tasks:
binary. If the gateware name has been overridden through module
parameters (in a carrier-specific way) the file loaded will match
the parameters. Per-device gateware names can be specified using
- the `gateware=' parameter, see *note Module Parameters::. Note:
+ the `gateware=` parameter, see :ref:`fmc_module_parameters`. Note:
Clients should call rhe new helper, fmc_reprogram, which both
calls this method and parse the SDB tree of the FPGA.
-`irq_request'
-`irq_ack'
-`irq_free'
+`irq_request`, `irq_ack`, `irq_free`
Interrupt management is carrier-specific, so it is abstracted as
operations. The interrupt number is listed in the device
structure, and for the mezzanine driver the number is only
informative. The handler will receive the fmc pointer as dev_id;
the flags argument is passed to the Linux request_irq function,
but fmc-specific flags may be added in the future. You'll most
- likely want to pass the `IRQF_SHARED' flag.
+ likely want to pass the `IRQF_SHARED` flag.
-`gpio_config'
+`gpio_config`
The method allows to configure a GPIO pin in the carrier, and read
- its current value if it is configured as input. See *note The GPIO
- Abstraction:: for details.
+ its current value if it is configured as input. See
+ :ref:`fmc_gpio_abstraction` for details.
-`read_ee'
-`write_ee'
+`read_ee`, `write_ee`
Read or write the EEPROM. The functions are expected to be only
called before reprogramming and the carrier should refuse them
- with `ENODEV' after reprogramming. The offset is expected to be
+ with `ENODEV` after reprogramming. The offset is expected to be
within 8kB (the current size), but addresses up to 1MB are
reserved to fit bigger I2C devices in the future. Carriers may
offer access to other internal flash memories using these same
@@ -214,9 +215,9 @@ The individual methods perform the following tasks:
I2C memory is seen at offset 1M and the internal SPI flash is seen
at offset 16M. This multiplexing of several flash memories in the
same address space is carrier-specific and should only be used
- by a driver that has verified the `carrier_name' field.
-
+ by a driver that has verified the `carrier_name` field.
+.. _fmc_gpio_abstraction:
The GPIO Abstraction
====================
@@ -230,7 +231,7 @@ some knowledge of the carrier itself. For this reason, the specific
driver can request to configure carrier-specific GPIO pins, numbered
from 0 to at most 4095. Configuration is performed by passing a
pointer to an array of struct fmc_gpio items, as well as the length of
-the array. This is the data structure:
+the array. This is the data structure::
struct fmc_gpio {
char *carrier_name;
@@ -254,7 +255,7 @@ pins, and expect one such configuration to succeed - if none succeeds
it most likely means that the current carrier is a still-unknown one.
If, however, your GPIO pin has a specific known role, you can pass a
-special number in the gpio field, using one of the following macros:
+special number in the gpio field, using one of the following macros::
#define FMC_GPIO_RAW(x) (x) /* 4096 of them */
#define FMC_GPIO_IRQ(x) ((x) + 0x1000) /* 256 of them */
@@ -293,9 +294,9 @@ carriers.
The return value of gpio_config is defined as follows:
- * If no pin in the array can be used by the carrier, `-ENODEV'.
+ * If no pin in the array can be used by the carrier, `-ENODEV`.
- * If at least one virtual GPIO number cannot be mapped, `-ENOENT'.
+ * If at least one virtual GPIO number cannot be mapped, `-ENOENT`.
* On success, 0 or positive. The value returned is the number of
high input bits (if no input is configured, the value for success
diff --git a/Documentation/fmc/FMC-and-SDB.txt b/Documentation/fmc/fmc-and-sdb.rst
similarity index 88%
rename from Documentation/fmc/FMC-and-SDB.txt
rename to Documentation/fmc/fmc-and-sdb.rst
index fa14e0b24521..e64c6104a241 100644
--- a/Documentation/fmc/FMC-and-SDB.txt
+++ b/Documentation/fmc/fmc-and-sdb.rst
@@ -1,3 +1,6 @@
+============
+Introduction
+============
FMC (FPGA Mezzanine Card) is the standard we use for our I/O devices,
in the context of White Rabbit and related hardware.
@@ -18,12 +21,12 @@ submodule.
The most up to date version of code and documentation is always
available from the repository you can clone from:
- git://ohwr.org/fmc-projects/fmc-bus.git (read-only)
- git@ohwr.org:fmc-projects/fmc-bus.git (read-write for developers)
+ - git://ohwr.org/fmc-projects/fmc-bus.git (read-only)
+ - git@ohwr.org:fmc-projects/fmc-bus.git (read-write for developers)
Selected versions of the documentation, as well as complete tar
archives for selected revisions are placed to the Files section of the
-project: `http://www.ohwr.org/projects/fmc-bus/files'
+project: `http://www.ohwr.org/projects/fmc-bus/files`
What is FMC
@@ -62,13 +65,15 @@ a filesystem inside the FMC EEPROM.
SDB is not mandatory for use of this FMC kernel bus, but if you have SDB
this package can make good use of it. SDB itself is developed in the
fpga-config-space OHWR project. The link to the repository is
-`git://ohwr.org/hdl-core-lib/fpga-config-space.git' and what is used in
+`git://ohwr.org/hdl-core-lib/fpga-config-space.git` and what is used in
this project lives in the sdbfs subdirectory in there.
-SDB support for FMC is described in *note FMC Identification:: and
-*note SDB Support::
+SDB support for FMC is described in :ref:`fmc_identification` and
+:ref:`fmc_sdb_support`.
+.. _fmc_sdb_support:
+
SDB Support
***********
@@ -79,7 +84,7 @@ memory image.
The module exports the following functions, in the special header
<linux/fmc-sdb.h>. The linux/ prefix in the name is there because we
plan to submit it upstream in the future, and don't want to force
-changes on our drivers if that happens.
+changes on our drivers if that happens::
int fmc_scan_sdb_tree(struct fmc_device *fmc, unsigned long address);
void fmc_show_sdb_tree(struct fmc_device *fmc);
diff --git a/Documentation/fmc/fmc-chardev.txt b/Documentation/fmc/fmc-chardev.rst
similarity index 96%
rename from Documentation/fmc/fmc-chardev.txt
rename to Documentation/fmc/fmc-chardev.rst
index d9ccb278e597..5aa77511e4d1 100644
--- a/Documentation/fmc/fmc-chardev.txt
+++ b/Documentation/fmc/fmc-chardev.rst
@@ -1,5 +1,6 @@
-fmc-chardev
-===========
+================
+Character device
+================
This is a simple generic driver, that allows user access by means of a
character device (actually, one for each mezzanine it takes hold of).
@@ -27,7 +28,7 @@ arises.
The example below shows raw access to a SPEC card programmed with its
golden FPGA file, that features an SDB structure at offset 256 - i.e.
64 words. The mezzanine's EEPROM in this case is not programmed, so the
-default name is fmc-<bus><devfn>, and there are two cards in the system:
+default name is fmc-<bus><devfn>, and there are two cards in the system::
spusa.root# insmod fmc-chardev.ko
[ 1073.339332] spec 0000:02:00.0: Driver has no ID: matches all
@@ -52,7 +53,7 @@ repeated reading data is written to stdout; repeated writes read from
stdin and the value argument is ignored.
The following examples show reading the SDB magic number and the first
-SDB record from a SPEC device programmed with its golden image:
+SDB record from a SPEC device programmed with its golden image::
spusa.root# ./fmc-mem /dev/fmc-0200 100
5344422d
diff --git a/Documentation/fmc/fmc-fakedev.txt b/Documentation/fmc/fmc-fakedev.rst
similarity index 85%
rename from Documentation/fmc/fmc-fakedev.txt
rename to Documentation/fmc/fmc-fakedev.rst
index e85b74a4ae30..e9300e839eef 100644
--- a/Documentation/fmc/fmc-fakedev.txt
+++ b/Documentation/fmc/fmc-fakedev.rst
@@ -1,7 +1,10 @@
-fmc-fakedev
-===========
+.. _fmc_fakedev:
-This package includes a software-only device, called fmc-fakedev, which
+=========================
+Software-only Fake Device
+=========================
+
+This package includes a software-only device, called **fmc-fakedev**, which
is able to register up to 4 mezzanines (by default it registers one).
Unlike the SPEC driver, which creates an FMC device for each PCI cards
it manages, this module creates a single instance of its set of
@@ -9,14 +12,14 @@ mezzanines.
It is meant as the simplest possible example of how a driver should be
written, and it includes a fake EEPROM image (built using the tools
-described in *note FMC Identification::),, which by default is
+described in :ref:`fmc_identification` which by default is
replicated for each fake mezzanine.
You can also use this device to verify the match algorithms, by asking
it to test your own EEPROM image. You can provide the image by means of
the eeprom= module parameter: the new EEPROM image is loaded, as usual,
by means of the firmware loader. This example shows the defaults and a
-custom EEPROM image:
+custom EEPROM image::
spusa.root# insmod fmc-fakedev.ko
[ 99.971247] fake-fmc-carrier: mezzanine 0
diff --git a/Documentation/fmc/fmc-trivial.txt b/Documentation/fmc/fmc-trivial.rst
similarity index 69%
rename from Documentation/fmc/fmc-trivial.txt
rename to Documentation/fmc/fmc-trivial.rst
index d1910bc67159..c98324f955ea 100644
--- a/Documentation/fmc/fmc-trivial.txt
+++ b/Documentation/fmc/fmc-trivial.rst
@@ -1,7 +1,9 @@
-fmc-trivial
-===========
+.. _fmc_trivial:
-The simple module fmc-trivial is just a simple client that registers an
+FMC trivial driver
+==================
+
+The simple module **fmc-trivial** is just a simple client that registers an
interrupt handler. I used it to verify the basic mechanism of the FMC
bus and how interrupts worked.
@@ -9,8 +11,7 @@ The module implements the generic FMC parameters, so it can program a
different gateware file in each card. The whole list of parameters it
accepts are:
-`busid='
-`gateware='
+`busid=`, `gateware=`
Generic parameters. See mezzanine.txt
diff --git a/Documentation/fmc/fmc-write-eeprom.txt b/Documentation/fmc/fmc-write-eeprom.rst
similarity index 79%
rename from Documentation/fmc/fmc-write-eeprom.txt
rename to Documentation/fmc/fmc-write-eeprom.rst
index e0a9712156aa..45311bcc804a 100644
--- a/Documentation/fmc/fmc-write-eeprom.txt
+++ b/Documentation/fmc/fmc-write-eeprom.rst
@@ -1,9 +1,12 @@
-fmc-write-eeprom
+.. _fmc_write_eeprom:
+
+================
+FMC write eeprom
================
-This module is designed to load a binary file from /lib/firmware and to
-write it to the internal EEPROM of the mezzanine card. This driver uses
-the `busid' generic parameter.
+The module **fmc-write-eeprom** is designed to load a binary file from
+/lib/firmware and to write it to the internal EEPROM of the mezzanine card.
+This driver uses the `busid` generic parameter.
Overwriting the EEPROM is not something you should do daily, and it is
expected to only happen during manufacturing. For this reason, the
@@ -11,36 +14,36 @@ module makes it unlikely for the random user to change a working EEPROM.
However, since the EEPROM may include application-specific information
other than the identification, later versions of this packages added
-write-support through sysfs. See *note Accessing the EEPROM::.
+write-support through sysfs. See :ref:`fmc_accessing_eeprom`.
To avoid damaging the EEPROM content, the module takes the following
measures:
- * It accepts a `file=' argument (within /lib/firmware) and if no
+ * It accepts a `file=` argument (within /lib/firmware) and if no
such argument is received, it doesn't write anything to EEPROM
(i.e. there is no default file name).
- * If the file name ends with `.bin' it is written verbatim starting
+ * If the file name ends with `.bin` it is written verbatim starting
at offset 0.
- * If the file name ends with `.tlv' it is interpreted as
+ * If the file name ends with `.tlv` it is interpreted as
type-length-value (i.e., it allows writev(2)-like operation).
* If the file name doesn't match any of the patterns above, it is
ignored and no write is performed.
- * Only cards listed with `busid=' are written to. If no busid is
+ * Only cards listed with `busid=` are written to. If no busid is
specified, no programming is done (and the probe function of the
driver will fail).
Each TLV tuple is formatted in this way: the header is 5 bytes,
-followed by data. The first byte is `w' for write, the next two bytes
+followed by data. The first byte is `w` for write, the next two bytes
represent the address, in little-endian byte order, and the next two
represent the data length, in little-endian order. The length does not
include the header (it is the actual number of bytes to be written).
-This is a real example: that writes 5 bytes at position 0x110:
+This is a real example: that writes 5 bytes at position 0x110::
spusa.root# od -t x1 -Ax /lib/firmware/try.tlv
000000 77 10 01 05 00 30 31 32 33 34
@@ -55,13 +58,13 @@ Rabbit environment. For this reason the TLV format is not expected to
be used much and is not expected to be developed further.
If you want to try reflashing fake EEPROM devices, you can use the
-fmc-fakedev.ko module (see *note fmc-fakedev::). Whenever you change
+fmc-fakedev.ko module (see :ref:`fmc_fakedev`). Whenever you change
the image starting at offset 0, it will deregister and register again
after two seconds. Please note, however, that if fmc-write-eeprom is
still loaded, the system will associate it to the new device, which
will be reprogrammed and thus will be unloaded after two seconds. The
following example removes the module after it reflashed fakedev the
-first time.
+first time::
spusa.root# insmod fmc-fakedev.ko
[ 72.984733] fake-fmc: Manufacturer: fake-vendor
@@ -74,12 +77,13 @@ first time.
[ 132.895794] fake-fmc: Manufacturer: CERN
[ 132.899872] fake-fmc: Product name: FmcDelay1ns4cha
+.. _fmc_accessing_eeprom:
Accessing the EEPROM
-=====================
+====================
The bus creates a sysfs binary file called eeprom for each mezzanine it
-knows about:
+knows about::
spusa.root# cd /sys/bus/fmc/devices; ls -l */eeprom
-r--r--r-- 1 root root 8192 Feb 21 12:30 FmcAdc100m14b4cha-0800/eeprom
@@ -94,5 +98,5 @@ the FPGA with a custom circuit, the carrier is unable to access the
EEPROM and returns ENOTSUPP.
An alternative way to write the EEPROM is the mezzanine driver
-fmc-write-eeprom (See *note fmc-write-eeprom::), but the procedure is
+fmc-write-eeprom (See :ref:`fmc_write_eeprom`), but the procedure is
more complex.
diff --git a/Documentation/fmc/identifiers.txt b/Documentation/fmc/identifiers.rst
similarity index 93%
rename from Documentation/fmc/identifiers.txt
rename to Documentation/fmc/identifiers.rst
index 3bb577ff0d52..01e6dde0996f 100644
--- a/Documentation/fmc/identifiers.txt
+++ b/Documentation/fmc/identifiers.rst
@@ -1,3 +1,5 @@
+.. _fmc_identification:
+
FMC Identification
******************
@@ -19,7 +21,7 @@ package and SDB (part of the fpga-config-space package).
The first sections are only interesting for manufacturers who need to
write the EEPROM. If you are just a software developer writing an FMC
-device or driver, you may jump straight to *note SDB Support::.
+device or driver, you may jump straight to :ref:`fmc_sdb_support`.
Building the FRU Structure
@@ -27,7 +29,7 @@ Building the FRU Structure
If you want to know the internals of the FRU structure and despair, you
can retrieve the document from
-`http://download.intel.com/design/servers/ipmi/FRU1011.pdf' . The
+`http://download.intel.com/design/servers/ipmi/FRU1011.pdf` . The
standard is awful and difficult without reason, so we only support the
minimum mandatory subset - we create a simple structure and parse it
back at run time, but we are not able to either generate or parse more
@@ -43,13 +45,15 @@ line takes precedence)
To make a long story short, in order to build a standard-compliant
binary file to be burned in your EEPROM, you need the following items:
+ =========== === ===================== ============
Environment Opt Official Name Default
----------------------------------------------------------------------
+ =========== === ===================== ============
FRU_VENDOR -v "Board Manufacturer" fmc-example
FRU_NAME -n "Board Product Name" mezzanine
- FRU_SERIAL -s `Board Serial Number" 0001
+ FRU_SERIAL -s "Board Serial Number" 0001
FRU_PART -p "Board Part Number" sample-part
FRU_OUTPUT -o not applicable /dev/stdout
+ =========== === ===================== ============
The "Official Name" above is what you find in the FRU official
documentation, chapter 11, page 7 ("Board Info Area Format"). The
@@ -63,7 +67,7 @@ soon as I find some time for that.
FIXME: consumption etc for FRU are here or in PTS?
-The following example creates a binary image for a specific board:
+The following example creates a binary image for a specific board::
./tools/fru-generator -v CERN -n FmcAdc100m14b4cha \
-s HCCFFIA___-CR000003 -p EDA-02063-V5-0 > eeprom.bin
@@ -71,7 +75,7 @@ The following example creates a binary image for a specific board:
The following example shows a script that builds several binary EEPROM
images for a series of boards, changing the serial number for each of
them. The script uses a mix of environment variables and command line
-options, and uses the same string patterns shown above.
+options, and uses the same string patterns shown above::
#!/bin/sh
@@ -131,7 +135,7 @@ name. The IPMI-FRU name is not mandatory, but a strongly suggested
choice; the name filename is mandatory, because this is the preferred
short name used by the FMC core. For example, a name of "fdelay" may
supplement a Product Name like "FmcDelay1ns4cha" - exactly as
-demonstrated in `tools/sdbfs'.
+demonstrated in `tools/sdbfs`.
Note: SDB access to flash memory is not yet supported, so the short
name currently in use is just the "Product Name" FRU string.
@@ -139,7 +143,7 @@ name currently in use is just the "Product Name" FRU string.
The example in tools/sdbfs includes an extra file, that is needed by
the fine-delay driver, and must live at a known address of 0x1800. By
running gensdbfs on that directory you can output your binary EEPROM
-image (here below spusa$ is the shell prompt):
+image (here below spusa$ is the shell prompt)::
spusa$ ../fru-generator -v CERN -n FmcDelay1ns4cha -s proto-0 \
-p EDA-02267-V3 > IPMI-FRU
diff --git a/Documentation/fmc/index.rst b/Documentation/fmc/index.rst
new file mode 100644
index 000000000000..a749cb04f39e
--- /dev/null
+++ b/Documentation/fmc/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+=========================
+FMC (FPGA Mezzanine Card)
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
+ fmc-and-sdb
+ carrier
+ identifiers
+ mezzanine
+ parameters
+
+ api
+
+ fmc-fakedev
+ fmc-trivial
+ fmc-write-eeprom
+ fmc-chardev
diff --git a/Documentation/fmc/mezzanine.txt b/Documentation/fmc/mezzanine.rst
similarity index 87%
rename from Documentation/fmc/mezzanine.txt
rename to Documentation/fmc/mezzanine.rst
index 87910dbfc91e..9a37147e8f14 100644
--- a/Documentation/fmc/mezzanine.txt
+++ b/Documentation/fmc/mezzanine.rst
@@ -1,5 +1,8 @@
+.. _fmc_driver:
+
+==========
FMC Driver
-**********
+==========
An FMC driver is concerned with the specific mezzanine and associated
gateware. As such, it is expected to be independent of the carrier
@@ -12,23 +15,23 @@ configured in the FPGA; the latter technique is used when the FPGA is
already programmed when the device is registered to the bus core.
In some special cases it is possible for a driver to directly access
-FPGA registers, by means of the `fpga_base' field of the device
+FPGA registers, by means of the `fpga_base` field of the device
structure. This may be needed for high-bandwidth peripherals like fast
ADC cards. If the device module registered a remote device (for example
-by means of Etherbone), the `fpga_base' pointer will be NULL.
+by means of Etherbone), the `fpga_base` pointer will be NULL.
Therefore, drivers must be ready to deal with NULL base pointers, and
fail gracefully. Most driver, however, are not expected to access the
pointer directly but run fmc_readl and fmc_writel instead, which will
work in any case.
In even more special cases, the driver may access carrier-specific
-functionality: the `carrier_name' string allows the driver to check
-which is the current carrier and make use of the `carrier_data'
+functionality: the `carrier_name` string allows the driver to check
+which is the current carrier and make use of the `carrier_data`
pointer. We chose to use carrier names rather than numeric identifiers
for greater flexibility, but also to avoid a central registry within
-the `fmc.h' file - we hope other users will exploit our framework with
+the `fmc.h` file - we hope other users will exploit our framework with
their own carriers. An example use of carrier names is in GPIO setup
-(see *note The GPIO Abstraction::), although the name match is not
+(see :ref:`fmc_gpio_abstraction`), although the name match is not
expected to be performed by the driver. If you depend on specific
carriers, please check the carrier name and fail gracefully if your
driver finds it is running in a yet-unknown-to-it environment.
@@ -44,7 +47,7 @@ their EEPROM or on the actual FPGA cores that can be enumerated.
Therefore, we have two tables of identifiers.
Matching of FRU information depends on two names, the manufacturer (or
-vendor) and the device (see *note FMC Identification::); for
+vendor) and the device (see :ref:`fmc_identification`); for
flexibility during production (i.e. before writing to the EEPROM) the
bus supports a catch-all driver that specifies NULL strings. For this
reason, the table is specified as pointer-and-length, not a a
@@ -58,7 +61,7 @@ instantiated), and for consistency the list is passed as
pointer-and-length. Several similar devices can be driven by the same
driver, and thus the driver specifies and array of such arrays.
-The complete set of involved data structures is thus the following:
+The complete set of involved data structures is thus the following::
struct fmc_fru_id { char *manufacturer; char *product_name; };
struct fmc_sdb_one_id { uint64_t vendor; uint32_t device; };
@@ -71,13 +74,14 @@ The complete set of involved data structures is thus the following:
A better reference, with full explanation, is the <linux/fmc.h> header.
+.. _fmc_module_parameters:
Module Parameters
=================
Most of the FMC drivers need the same set of kernel parameters. This
package includes support to implement common parameters by means of
-fields in the `fmc_driver' structure and simple macro definitions.
+fields in the `fmc_driver` structure and simple macro definitions.
The parameters are carrier-specific, in that they rely on the busid
concept, that varies among carriers. For the SPEC, the identifier is a
@@ -88,20 +92,20 @@ and some code duplication is unavoidable.
This is the list of parameters that are common to several modules to
see how they are actually used, please look at spec-trivial.c.
-`busid='
+`busid=`
This is an array of integers, listing carrier-specific
- identification numbers. For PIC, for example, `0x0400' represents
+ identification numbers. For PIC, for example, `0x0400` represents
bus 4, slot 0. If any such ID is specified, the driver will only
accept to drive cards that appear in the list (even if the FMC ID
matches). This is accomplished by the validate carrier method.
-`gateware='
+`gateware=`
The argument is an array of strings. If no busid= is specified,
the first string of gateware= is used for all cards; otherwise the
identifiers and gateware names are paired one by one, in the order
specified.
-`show_sdb='
+`show_sdb=`
For modules supporting it, this parameter asks to show the SDB
internal structure by means of kernel messages. It is disabled by
default because those lines tend to hide more important messages,
@@ -113,7 +117,7 @@ see how they are actually used, please look at spec-trivial.c.
For example, if you are using the trivial driver to load two different
gateware files to two different cards, you can use the following
parameters to load different binaries to the cards, after looking up
-the PCI identifiers. This has been tested with a SPEC carrier.
+the PCI identifiers. This has been tested with a SPEC carrier::
insmod fmc-trivial.ko \
busid=0x0200,0x0400 \
diff --git a/Documentation/fmc/parameters.txt b/Documentation/fmc/parameters.rst
similarity index 96%
rename from Documentation/fmc/parameters.txt
rename to Documentation/fmc/parameters.rst
index 59edf088e3a4..bf4566967e9c 100644
--- a/Documentation/fmc/parameters.txt
+++ b/Documentation/fmc/parameters.rst
@@ -1,16 +1,17 @@
+===========================
Module Parameters in fmc.ko
-***************************
+===========================
The core driver receives two module parameters, meant to help debugging
client modules. Both parameters can be modified by writing to
/sys/module/fmc/parameters/, because they are used when client drivers
are devices are registered, not when fmc.ko is loaded.
-`dump_eeprom='
+`dump_eeprom=`
If not zero, the parameter asks the bus controller to dump the
EEPROM of any device that is registered, using printk.
-`dump_sdb='
+`dump_sdb=`
If not zero, the parameter prints the SDB tree of every FPGA it is
loaded by fmc_reprogram(). If greater than one, it asks to dump
the binary content of SDB records. This currently only dumps the
@@ -19,7 +20,7 @@ are devices are registered, not when fmc.ko is loaded.
EEPROM dumping avoids repeating lines, since most of the contents is
usually empty and all bits are one or zero. This is an example of the
-output:
+output::
[ 6625.850480] spec 0000:02:00.0: FPGA programming successful
[ 6626.139949] spec 0000:02:00.0: Manufacturer: CERN
@@ -40,7 +41,7 @@ output:
The dump of SDB looks like the following; the example shows the simple
golden gateware for the SPEC card, removing the leading timestamps to
-fit the page:
+fit the page::
spec 0000:02:00.0: SDB: 00000651:e6a542c9 WB4-Crossbar-GSI
spec 0000:02:00.0: SDB: 0000ce42:ff07fc47 WR-Periph-Syscon (00000000-000000ff)
--
2.21.0
^ permalink raw reply related
* [PATCH v1 03/31] docs: lp855x-driver.txt: convert to ReST and move to kernel-api
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Milo Kim
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
This small file seems to be an attempt to start documenting
backlight drivers.
It contains descriptions of the controls for the driver
with could sound as an somewhat user-faced description, but
it's main focus is to describe, instead, the data that should
be passed via platform data and some driver-specific stuff.
While this is not part of the driver-api book, mark it as
:orphan:, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/backlight/lp855x-driver.rst | 83 +++++++++++++++++++++++
Documentation/backlight/lp855x-driver.txt | 66 ------------------
MAINTAINERS | 2 +-
3 files changed, 84 insertions(+), 67 deletions(-)
create mode 100644 Documentation/backlight/lp855x-driver.rst
delete mode 100644 Documentation/backlight/lp855x-driver.txt
diff --git a/Documentation/backlight/lp855x-driver.rst b/Documentation/backlight/lp855x-driver.rst
new file mode 100644
index 000000000000..62b7ed847a77
--- /dev/null
+++ b/Documentation/backlight/lp855x-driver.rst
@@ -0,0 +1,83 @@
+:orphan:
+
+====================
+Kernel driver lp855x
+====================
+
+Backlight driver for LP855x ICs
+
+Supported chips:
+
+ Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
+ LP8557
+
+Author: Milo(Woogyom) Kim <milo.kim@ti.com>
+
+Description
+-----------
+
+* Brightness control
+
+ Brightness can be controlled by the pwm input or the i2c command.
+ The lp855x driver supports both cases.
+
+* Device attributes
+
+ 1) bl_ctl_mode
+
+ Backlight control mode.
+
+ Value: pwm based or register based
+
+ 2) chip_id
+
+ The lp855x chip id.
+
+ Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
+
+Platform data for lp855x
+------------------------
+
+For supporting platform specific data, the lp855x platform data can be used.
+
+* name:
+ Backlight driver name. If it is not defined, default name is set.
+* device_control:
+ Value of DEVICE CONTROL register.
+* initial_brightness:
+ Initial value of backlight brightness.
+* period_ns:
+ Platform specific PWM period value. unit is nano.
+ Only valid when brightness is pwm input mode.
+* size_program:
+ Total size of lp855x_rom_data.
+* rom_data:
+ List of new eeprom/eprom registers.
+
+Examples
+========
+
+1) lp8552 platform data: i2c register mode with new eeprom data::
+
+ #define EEPROM_A5_ADDR 0xA5
+ #define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */
+
+ static struct lp855x_rom_data lp8552_eeprom_arr[] = {
+ {EEPROM_A5_ADDR, EEPROM_A5_VAL},
+ };
+
+ static struct lp855x_platform_data lp8552_pdata = {
+ .name = "lcd-bl",
+ .device_control = I2C_CONFIG(LP8552),
+ .initial_brightness = INITIAL_BRT,
+ .size_program = ARRAY_SIZE(lp8552_eeprom_arr),
+ .rom_data = lp8552_eeprom_arr,
+ };
+
+2) lp8556 platform data: pwm input mode with default rom data::
+
+ static struct lp855x_platform_data lp8556_pdata = {
+ .device_control = PWM_CONFIG(LP8556),
+ .initial_brightness = INITIAL_BRT,
+ .period_ns = 1000000,
+ };
diff --git a/Documentation/backlight/lp855x-driver.txt b/Documentation/backlight/lp855x-driver.txt
deleted file mode 100644
index 01bce243d3d7..000000000000
--- a/Documentation/backlight/lp855x-driver.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-Kernel driver lp855x
-====================
-
-Backlight driver for LP855x ICs
-
-Supported chips:
- Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
- LP8557
-
-Author: Milo(Woogyom) Kim <milo.kim@ti.com>
-
-Description
------------
-
-* Brightness control
-
-Brightness can be controlled by the pwm input or the i2c command.
-The lp855x driver supports both cases.
-
-* Device attributes
-
-1) bl_ctl_mode
-Backlight control mode.
-Value : pwm based or register based
-
-2) chip_id
-The lp855x chip id.
-Value : lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
-
-Platform data for lp855x
-------------------------
-
-For supporting platform specific data, the lp855x platform data can be used.
-
-* name : Backlight driver name. If it is not defined, default name is set.
-* device_control : Value of DEVICE CONTROL register.
-* initial_brightness : Initial value of backlight brightness.
-* period_ns : Platform specific PWM period value. unit is nano.
- Only valid when brightness is pwm input mode.
-* size_program : Total size of lp855x_rom_data.
-* rom_data : List of new eeprom/eprom registers.
-
-example 1) lp8552 platform data : i2c register mode with new eeprom data
-
-#define EEPROM_A5_ADDR 0xA5
-#define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */
-
-static struct lp855x_rom_data lp8552_eeprom_arr[] = {
- {EEPROM_A5_ADDR, EEPROM_A5_VAL},
-};
-
-static struct lp855x_platform_data lp8552_pdata = {
- .name = "lcd-bl",
- .device_control = I2C_CONFIG(LP8552),
- .initial_brightness = INITIAL_BRT,
- .size_program = ARRAY_SIZE(lp8552_eeprom_arr),
- .rom_data = lp8552_eeprom_arr,
-};
-
-example 2) lp8556 platform data : pwm input mode with default rom data
-
-static struct lp855x_platform_data lp8556_pdata = {
- .device_control = PWM_CONFIG(LP8556),
- .initial_brightness = INITIAL_BRT,
- .period_ns = 1000000,
-};
diff --git a/MAINTAINERS b/MAINTAINERS
index fa236f3f5979..28c3b926555e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15828,7 +15828,7 @@ F: sound/soc/codecs/isabelle*
TI LP855x BACKLIGHT DRIVER
M: Milo Kim <milo.kim@ti.com>
S: Maintained
-F: Documentation/backlight/lp855x-driver.txt
+F: Documentation/backlight/lp855x-driver.rst
F: drivers/video/backlight/lp855x_bl.c
F: include/linux/platform_data/lp855x.h
--
2.21.0
^ permalink raw reply related
* [PATCH v1 01/31] docs: connector: convert to ReST and rename to connector.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Evgeniy Polyakov
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
As it has some function definitions, move them to connector.h.
The remaining conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
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>
---
.../{connector.txt => connector.rst} | 130 ++++++------------
drivers/w1/Kconfig | 2 +-
include/linux/connector.h | 63 ++++++++-
samples/Kconfig | 2 +-
4 files changed, 109 insertions(+), 88 deletions(-)
rename Documentation/connector/{connector.txt => connector.rst} (57%)
diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.rst
similarity index 57%
rename from Documentation/connector/connector.txt
rename to Documentation/connector/connector.rst
index ab7ca897fab7..24e26dc22dbf 100644
--- a/Documentation/connector/connector.txt
+++ b/Documentation/connector/connector.rst
@@ -1,6 +1,8 @@
-/*****************************************/
-Kernel Connector.
-/*****************************************/
+:orphan:
+
+================
+Kernel Connector
+================
Kernel connector - new netlink based userspace <-> kernel space easy
to use communication module.
@@ -12,94 +14,55 @@ identifier, the appropriate callback will be called.
From the userspace point of view it's quite straightforward:
- socket();
- bind();
- send();
- recv();
+ - socket();
+ - bind();
+ - send();
+ - recv();
But if kernelspace wants to use the full power of such connections, the
driver writer must create special sockets, must know about struct sk_buff
handling, etc... The Connector driver allows any kernelspace agents to use
netlink based networking for inter-process communication in a significantly
-easier way:
+easier way::
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
-void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
-void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
+ int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
+ void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
-struct cb_id
-{
+ struct cb_id
+ {
__u32 idx;
__u32 val;
-};
+ };
idx and val are unique identifiers which must be registered in the
-connector.h header for in-kernel usage. void (*callback) (void *) is a
+connector.h header for in-kernel usage. `void (*callback) (void *)` is a
callback function which will be called when a message with above idx.val
is received by the connector core. The argument for that function must
-be dereferenced to struct cn_msg *.
+be dereferenced to `struct cn_msg *`::
-struct cn_msg
-{
+ struct cn_msg
+ {
struct cb_id id;
__u32 seq;
__u32 ack;
- __u32 len; /* Length of the following data */
+ __u32 len; /* Length of the following data */
__u8 data[0];
-};
+ };
-/*****************************************/
-Connector interfaces.
-/*****************************************/
+Connector interfaces
+====================
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ .. kernel-doc:: include/linux/connector.h
- Registers new callback with connector core.
+ Note:
+ When registering new callback user, connector core assigns
+ netlink group to the user which is equal to its id.idx.
- struct cb_id *id - unique connector's user identifier.
- It must be registered in connector.h for legal in-kernel users.
- char *name - connector's callback symbolic name.
- void (*callback) (struct cn..) - connector's callback.
- cn_msg and the sender's credentials
-
-
-void cn_del_callback(struct cb_id *id);
-
- Unregisters new callback with connector core.
-
- struct cb_id *id - unique connector's user identifier.
-
-
-int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask);
-int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask);
-
- Sends message to the specified groups. It can be safely called from
- softirq context, but may silently fail under strong memory pressure.
- If there are no listeners for given group -ESRCH can be returned.
-
- struct cn_msg * - message header(with attached data).
- u16 len - for *_multi multiple cn_msg messages can be sent
- u32 port - destination port.
- If non-zero the message will be sent to the
- given port, which should be set to the
- original sender.
- u32 __group - destination group.
- If port and __group is zero, then appropriate group will
- be searched through all registered connector users,
- and message will be delivered to the group which was
- created for user with the same ID as in msg.
- If __group is not zero, then message will be delivered
- to the specified group.
- int gfp_mask - GFP mask.
-
- Note: When registering new callback user, connector core assigns
- netlink group to the user which is equal to its id.idx.
-
-/*****************************************/
-Protocol description.
-/*****************************************/
+Protocol description
+====================
The current framework offers a transport layer with fixed headers. The
recommended protocol which uses such a header is as following:
@@ -132,9 +95,8 @@ driver (it also registers itself with id={-1, -1}).
As example of this usage can be found in the cn_test.c module which
uses the connector to request notification and to send messages.
-/*****************************************/
-Reliability.
-/*****************************************/
+Reliability
+===========
Netlink itself is not a reliable protocol. That means that messages can
be lost due to memory pressure or process' receiving queue overflowed,
@@ -142,32 +104,31 @@ so caller is warned that it must be prepared. That is why the struct
cn_msg [main connector's message header] contains u32 seq and u32 ack
fields.
-/*****************************************/
-Userspace usage.
-/*****************************************/
+Userspace usage
+===============
2.6.14 has a new netlink socket implementation, which by default does not
allow people to send data to netlink groups other than 1.
So, if you wish to use a netlink socket (for example using connector)
with a different group number, the userspace application must subscribe to
-that group first. It can be achieved by the following pseudocode:
+that group first. It can be achieved by the following pseudocode::
-s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
+ s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
-l_local.nl_family = AF_NETLINK;
-l_local.nl_groups = 12345;
-l_local.nl_pid = 0;
+ l_local.nl_family = AF_NETLINK;
+ l_local.nl_groups = 12345;
+ l_local.nl_pid = 0;
-if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
+ if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
perror("bind");
close(s);
return -1;
-}
+ }
-{
+ {
int on = l_local.nl_groups;
setsockopt(s, 270, 1, &on, sizeof(on));
-}
+ }
Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
option. To drop a multicast subscription, one should call the above socket
@@ -180,16 +141,15 @@ group number 12345, you must increment CN_NETLINK_USERS to that number.
Additional 0xf numbers are allocated to be used by non-in-kernel users.
Due to this limitation, group 0xffffffff does not work now, so one can
-not use add/remove connector's group notifications, but as far as I know,
+not use add/remove connector's group notifications, but as far as I know,
only cn_test.c test module used it.
Some work in netlink area is still being done, so things can be changed in
2.6.15 timeframe, if it will happen, documentation will be updated for that
kernel.
-/*****************************************/
Code samples
-/*****************************************/
+============
Sample code for a connector test module and user space can be found
in samples/connector/. To build this code, enable CONFIG_CONNECTOR
diff --git a/drivers/w1/Kconfig b/drivers/w1/Kconfig
index 03dd57581df7..160053c0baea 100644
--- a/drivers/w1/Kconfig
+++ b/drivers/w1/Kconfig
@@ -19,7 +19,7 @@ config W1_CON
default y
---help---
This allows to communicate with userspace using connector. For more
- information see <file:Documentation/connector/connector.txt>.
+ information see <file:Documentation/connector/connector.rst>.
There are three types of messages between w1 core and userspace:
1. Events. They are generated each time new master or slave device found
either due to automatic or requested search.
diff --git a/include/linux/connector.h b/include/linux/connector.h
index 1d72ef76f24f..6b6c7396a584 100644
--- a/include/linux/connector.h
+++ b/include/linux/connector.h
@@ -55,10 +55,71 @@ struct cn_dev {
struct cn_queue_dev *cbdev;
};
+/**
+ * cn_add_callback() - Registers new callback with connector core.
+ *
+ * @id: unique connector's user identifier.
+ * It must be registered in connector.h for legal
+ * in-kernel users.
+ * @name: connector's callback symbolic name.
+ * @callback: connector's callback.
+ * parameters are %cn_msg and the sender's credentials
+ */
int cn_add_callback(struct cb_id *id, const char *name,
void (*callback)(struct cn_msg *, struct netlink_skb_parms *));
-void cn_del_callback(struct cb_id *);
+/**
+ * cn_del_callback() - Unregisters new callback with connector core.
+ *
+ * @id: unique connector's user identifier.
+ */
+void cn_del_callback(struct cb_id *id);
+
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg: message header(with attached data).
+ * @len: Number of @msg to be sent.
+ * @portid: destination port.
+ * If non-zero the message will be sent to the given port,
+ * which should be set to the original sender.
+ * @group: destination group.
+ * If @portid and @group is zero, then appropriate group will
+ * be searched through all registered connector users, and
+ * message will be delivered to the group which was created
+ * for user with the same ID as in @msg.
+ * If @group is not zero, then message will be delivered
+ * to the specified group.
+ * @gfp_mask: GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask);
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg: message header(with attached data).
+ * @portid: destination port.
+ * If non-zero the message will be sent to the given port,
+ * which should be set to the original sender.
+ * @group: destination group.
+ * If @portid and @group is zero, then appropriate group will
+ * be searched through all registered connector users, and
+ * message will be delivered to the group which was created
+ * for user with the same ID as in @msg.
+ * If @group is not zero, then message will be delivered
+ * to the specified group.
+ * @gfp_mask: GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 group, gfp_t gfp_mask);
int cn_queue_add_callback(struct cn_queue_dev *dev, const char *name,
diff --git a/samples/Kconfig b/samples/Kconfig
index d63cc8a3e0df..9ec524b2e003 100644
--- a/samples/Kconfig
+++ b/samples/Kconfig
@@ -100,7 +100,7 @@ config SAMPLE_CONNECTOR
When enabled, this builds both a sample kernel module for
the connector interface and a user space tool to communicate
with it.
- See also Documentation/connector/connector.txt
+ See also Documentation/connector/connector.rst
config SAMPLE_SECCOMP
bool "Build seccomp sample code"
--
2.21.0
^ permalink raw reply related
* [PATCH v1 24/31] docs: iio: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-iio
In-Reply-To: <cover.1560364493.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.
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>
---
.../iio/{ep93xx_adc.txt => ep93xx_adc.rst} | 15 +++++-
.../{iio_configfs.txt => iio_configfs.rst} | 52 +++++++++++--------
Documentation/iio/index.rst | 12 +++++
drivers/iio/Kconfig | 2 +-
4 files changed, 56 insertions(+), 25 deletions(-)
rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
create mode 100644 Documentation/iio/index.rst
diff --git a/Documentation/iio/ep93xx_adc.txt b/Documentation/iio/ep93xx_adc.rst
similarity index 71%
rename from Documentation/iio/ep93xx_adc.txt
rename to Documentation/iio/ep93xx_adc.rst
index 23053e7817bd..4fd8dea3f6b8 100644
--- a/Documentation/iio/ep93xx_adc.txt
+++ b/Documentation/iio/ep93xx_adc.rst
@@ -1,12 +1,16 @@
-Cirrus Logic EP93xx ADC driver.
+==============================
+Cirrus Logic EP93xx ADC driver
+==============================
1. Overview
+===========
The driver is intended to work on both low-end (EP9301, EP9302) devices with
5-channel ADC and high-end (EP9307, EP9312, EP9315) devices with 10-channel
touchscreen/ADC module.
2. Channel numbering
+====================
Numbering scheme for channels 0..4 is defined in EP9301 and EP9302 datasheets.
EP9307, EP9312 and EP9312 have 3 channels more (total 8), but the numbering is
@@ -17,13 +21,20 @@ Assuming ep93xx_adc is IIO device0, you'd find the following entries under
+-----------------+---------------+
| sysfs entry | ball/pin name |
- +-----------------+---------------+
+ +=================+===============+
| in_voltage0_raw | YM |
+ +-----------------+---------------+
| in_voltage1_raw | SXP |
+ +-----------------+---------------+
| in_voltage2_raw | SXM |
+ +-----------------+---------------+
| in_voltage3_raw | SYP |
+ +-----------------+---------------+
| in_voltage4_raw | SYM |
+ +-----------------+---------------+
| in_voltage5_raw | XP |
+ +-----------------+---------------+
| in_voltage6_raw | XM |
+ +-----------------+---------------+
| in_voltage7_raw | YP |
+-----------------+---------------+
diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.rst
similarity index 73%
rename from Documentation/iio/iio_configfs.txt
rename to Documentation/iio/iio_configfs.rst
index 4e5f101837a8..ecbfdb3afef7 100644
--- a/Documentation/iio/iio_configfs.txt
+++ b/Documentation/iio/iio_configfs.rst
@@ -1,6 +1,9 @@
+===============================
Industrial IIO configfs support
+===============================
1. Overview
+===========
Configfs is a filesystem-based manager of kernel objects. IIO uses some
objects that could be easily configured using configfs (e.g.: devices,
@@ -10,20 +13,22 @@ See Documentation/filesystems/configfs/configfs.txt for more information
about how configfs works.
2. Usage
+========
In order to use configfs support in IIO we need to select it at compile
time via CONFIG_IIO_CONFIGFS config option.
-Then, mount the configfs filesystem (usually under /config directory):
+Then, mount the configfs filesystem (usually under /config directory)::
-$ mkdir /config
-$ mount -t configfs none /config
+ $ mkdir /config
+ $ mount -t configfs none /config
At this point, all default IIO groups will be created and can be accessed
under /config/iio. Next chapters will describe available IIO configuration
objects.
3. Software triggers
+====================
One of the IIO default configfs groups is the "triggers" group. It is
automagically accessible when the configfs is mounted and can be found
@@ -31,40 +36,40 @@ under /config/iio/triggers.
IIO software triggers implementation offers support for creating multiple
trigger types. A new trigger type is usually implemented as a separate
-kernel module following the interface in include/linux/iio/sw_trigger.h:
+kernel module following the interface in include/linux/iio/sw_trigger.h::
-/*
- * drivers/iio/trigger/iio-trig-sample.c
- * sample kernel module implementing a new trigger type
- */
-#include <linux/iio/sw_trigger.h>
+ /*
+ * drivers/iio/trigger/iio-trig-sample.c
+ * sample kernel module implementing a new trigger type
+ */
+ #include <linux/iio/sw_trigger.h>
-static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
-{
+ static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
+ {
/*
* This allocates and registers an IIO trigger plus other
* trigger type specific initialization.
*/
-}
+ }
-static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
-{
+ static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
+ {
/*
* This undoes the actions in iio_trig_sample_probe
*/
-}
+ }
-static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
+ static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
.probe = iio_trig_sample_probe,
.remove = iio_trig_sample_remove,
-};
+ };
-static struct iio_sw_trigger_type iio_trig_sample = {
+ static struct iio_sw_trigger_type iio_trig_sample = {
.name = "trig-sample",
.owner = THIS_MODULE,
.ops = &iio_trig_sample_ops,
-};
+ };
module_iio_sw_trigger_driver(iio_trig_sample);
@@ -73,21 +78,24 @@ iio-trig-sample module will create 'trig-sample' trigger type directory
/config/iio/triggers/trig-sample.
We support the following interrupt sources (trigger types):
+
* hrtimer, uses high resolution timers as interrupt source
3.1 Hrtimer triggers creation and destruction
+---------------------------------------------
Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
users to create hrtimer triggers under /config/iio/triggers/hrtimer.
-e.g:
+e.g::
-$ mkdir /config/iio/triggers/hrtimer/instance1
-$ rmdir /config/iio/triggers/hrtimer/instance1
+ $ mkdir /config/iio/triggers/hrtimer/instance1
+ $ rmdir /config/iio/triggers/hrtimer/instance1
Each trigger can have one or more attributes specific to the trigger type.
3.2 "hrtimer" trigger types attributes
+--------------------------------------
"hrtimer" trigger type doesn't have any configurable attribute from /config dir.
It does introduce the sampling_frequency attribute to trigger directory.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
new file mode 100644
index 000000000000..0593dca89a94
--- /dev/null
+++ b/Documentation/iio/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+==============
+Industrial I/O
+==============
+
+.. toctree::
+ :maxdepth: 1
+
+ iio_configfs
+
+ ep93xx_adc
diff --git a/drivers/iio/Kconfig b/drivers/iio/Kconfig
index 1d736a4952ab..5bd51853b15e 100644
--- a/drivers/iio/Kconfig
+++ b/drivers/iio/Kconfig
@@ -28,7 +28,7 @@ config IIO_CONFIGFS
help
This allows configuring various IIO bits through configfs
(e.g. software triggers). For more info see
- Documentation/iio/iio_configfs.txt.
+ Documentation/iio/iio_configfs.rst.
config IIO_TRIGGER
bool "Enable triggered sampling support"
--
2.21.0
^ permalink raw reply related
* [PATCH v1 20/31] docs: hid: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jiri Kosina, Jonathan Cameron,
Srinivas Pandruvada, Benjamin Tissoires, Dmitry Torokhov,
linux-input, linux-iio, linux-usb
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the HID documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
While here, fix the sysfs example from hid-sensor.txt, that
has a lot of "?" instead of the proper UTF-8 characters that
are produced by the tree command.
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>
---
.../hid/{hid-alps.txt => hid-alps.rst} | 85 ++-
.../hid/{hid-sensor.txt => hid-sensor.rst} | 192 +++----
.../{hid-transport.txt => hid-transport.rst} | 82 ++-
Documentation/hid/{hiddev.txt => hiddev.rst} | 154 ++++--
Documentation/hid/{hidraw.txt => hidraw.rst} | 53 +-
Documentation/hid/index.rst | 18 +
Documentation/hid/intel-ish-hid.rst | 485 ++++++++++++++++++
Documentation/hid/intel-ish-hid.txt | 454 ----------------
Documentation/hid/{uhid.txt => uhid.rst} | 46 +-
Documentation/input/input.rst | 2 +-
MAINTAINERS | 2 +-
11 files changed, 897 insertions(+), 676 deletions(-)
rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
create mode 100644 Documentation/hid/index.rst
create mode 100644 Documentation/hid/intel-ish-hid.rst
delete mode 100644 Documentation/hid/intel-ish-hid.txt
rename Documentation/hid/{uhid.txt => uhid.rst} (94%)
diff --git a/Documentation/hid/hid-alps.txt b/Documentation/hid/hid-alps.rst
similarity index 64%
rename from Documentation/hid/hid-alps.txt
rename to Documentation/hid/hid-alps.rst
index 6b02a2447c77..e2f4c4c11e3f 100644
--- a/Documentation/hid/hid-alps.txt
+++ b/Documentation/hid/hid-alps.rst
@@ -1,19 +1,26 @@
+==========================
ALPS HID Touchpad Protocol
-----------------------
+==========================
Introduction
------------
Currently ALPS HID driver supports U1 Touchpad device.
-U1 devuce basic information.
+U1 device basic information.
+
+========== ======
Vender ID 0x044E
Product ID 0x120B
Version ID 0x0121
+========== ======
HID Descriptor
-------------
+--------------
+
+======= ==================== ===== =======================================
Byte Field Value Notes
+======= ==================== ===== =======================================
0 wHIDDescLength 001E Length of HID Descriptor : 30 bytes
2 bcdVersion 0100 Compliant with Version 1.00
4 wReportDescLength 00B2 Report Descriptor is 178 Bytes (0x00B2)
@@ -28,32 +35,42 @@ Byte Field Value Notes
22 wProductID 120B Product ID 0x120B
24 wVersionID 0121 Version 01.21
26 RESERVED 0000 RESERVED
+======= ==================== ===== =======================================
Report ID
-------------
-ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP
-ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP
-ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP
-ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP
-ReportID-5 (Feature Reports) Feature Reports
-ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP
-ReportID-7 (Feature Reports) Flash update (Bootloader)
+---------
+
+========== ================= =========================================
+ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP
+ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP
+ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP
+ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP
+ReportID-5 (Feature Reports) Feature Reports
+ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP
+ReportID-7 (Feature Reports) Flash update (Bootloader)
+========== ================= =========================================
Data pattern
------------
+
+===== ========== ===== =================
Case1 ReportID_1 TP/SP Relative/Relative
Case2 ReportID_3 TP Absolute
ReportID_6 SP Absolute
+===== ========== ===== =================
Command Read/Write
------------------
To read/write to RAM, need to send a commands to the device.
+
The command format is as below.
DataByte(SET_REPORT)
+
+===== ======================
Byte1 Command Byte
Byte2 Address - Byte 0 (LSB)
Byte3 Address - Byte 1
@@ -61,13 +78,19 @@ Byte4 Address - Byte 2
Byte5 Address - Byte 3 (MSB)
Byte6 Value Byte
Byte7 Checksum
+===== ======================
Command Byte is read=0xD1/write=0xD2 .
+
Address is read/write RAM address.
+
Value Byte is writing data when you send the write commands.
+
When you read RAM, there is no meaning.
DataByte(GET_REPORT)
+
+===== ======================
Byte1 Response Byte
Byte2 Address - Byte 0 (LSB)
Byte3 Address - Byte 1
@@ -75,6 +98,7 @@ Byte4 Address - Byte 2
Byte5 Address - Byte 3 (MSB)
Byte6 Value Byte
Byte7 Checksum
+===== ======================
Read value is stored in Value Byte.
@@ -82,7 +106,11 @@ Read value is stored in Value Byte.
Packet Format
Touchpad data byte
------------------
- b7 b6 b5 b4 b3 b2 b1 b0
+
+
+======= ======= ======= ======= ======= ======= ======= ======= =====
+- b7 b6 b5 b4 b3 b2 b1 b0
+======= ======= ======= ======= ======= ======= ======= ======= =====
1 0 0 SW6 SW5 SW4 SW3 SW2 SW1
2 0 0 0 Fcv Fn3 Fn2 Fn1 Fn0
3 Xa0_7 Xa0_6 Xa0_5 Xa0_4 Xa0_3 Xa0_2 Xa0_1 Xa0_0
@@ -114,17 +142,25 @@ Touchpad data byte
25 Ya4_7 Ya4_6 Ya4_5 Ya4_4 Ya4_3 Ya4_2 Ya4_1 Ya4_0
26 Ya4_15 Ya4_14 Ya4_13 Ya4_12 Ya4_11 Ya4_10 Ya4_9 Ya4_8
27 LFB4 Zs4_6 Zs4_5 Zs4_4 Zs4_3 Zs4_2 Zs4_1 Zs4_0
+======= ======= ======= ======= ======= ======= ======= ======= =====
-SW1-SW6: SW ON/OFF status
-Xan_15-0(16bit):X Absolute data of the "n"th finger
-Yan_15-0(16bit):Y Absolute data of the "n"th finger
-Zsn_6-0(7bit): Operation area of the "n"th finger
+SW1-SW6:
+ SW ON/OFF status
+Xan_15-0(16bit):
+ X Absolute data of the "n"th finger
+Yan_15-0(16bit):
+ Y Absolute data of the "n"th finger
+Zsn_6-0(7bit):
+ Operation area of the "n"th finger
StickPointer data byte
-------------------
- b7 b6 b5 b4 b3 b2 b1 b0
+----------------------
+
+======= ======= ======= ======= ======= ======= ======= ======= =====
+- b7 b6 b5 b4 b3 b2 b1 b0
+======= ======= ======= ======= ======= ======= ======= ======= =====
Byte1 1 1 1 0 1 SW3 SW2 SW1
Byte2 X7 X6 X5 X4 X3 X2 X1 X0
Byte3 X15 X14 X13 X12 X11 X10 X9 X8
@@ -132,8 +168,13 @@ Byte4 Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
Byte5 Y15 Y14 Y13 Y12 Y11 Y10 Y9 Y8
Byte6 Z7 Z6 Z5 Z4 Z3 Z2 Z1 Z0
Byte7 T&P Z14 Z13 Z12 Z11 Z10 Z9 Z8
+======= ======= ======= ======= ======= ======= ======= ======= =====
-SW1-SW3: SW ON/OFF status
-Xn_15-0(16bit):X Absolute data
-Yn_15-0(16bit):Y Absolute data
-Zn_14-0(15bit):Z
+SW1-SW3:
+ SW ON/OFF status
+Xn_15-0(16bit):
+ X Absolute data
+Yn_15-0(16bit):
+ Y Absolute data
+Zn_14-0(15bit):
+ Z
diff --git a/Documentation/hid/hid-sensor.txt b/Documentation/hid/hid-sensor.rst
similarity index 61%
rename from Documentation/hid/hid-sensor.txt
rename to Documentation/hid/hid-sensor.rst
index b287752a31cd..758972e34971 100644
--- a/Documentation/hid/hid-sensor.txt
+++ b/Documentation/hid/hid-sensor.rst
@@ -1,6 +1,6 @@
-
+=====================
HID Sensors Framework
-======================
+=====================
HID sensor framework provides necessary interfaces to implement sensor drivers,
which are connected to a sensor hub. The sensor hub is a HID device and it provides
a report descriptor conforming to HID 1.12 sensor usage tables.
@@ -15,22 +15,22 @@ the drivers themselves."
This specification describes many usage IDs, which describe the type of sensor
and also the individual data fields. Each sensor can have variable number of
data fields. The length and order is specified in the report descriptor. For
-example a part of report descriptor can look like:
+example a part of report descriptor can look like::
- INPUT(1)[INPUT]
- ..
- Field(2)
- Physical(0020.0073)
- Usage(1)
- 0020.045f
- Logical Minimum(-32767)
- Logical Maximum(32767)
- Report Size(8)
- Report Count(1)
- Report Offset(16)
- Flags(Variable Absolute)
-..
-..
+ INPUT(1)[INPUT]
+ ..
+ Field(2)
+ Physical(0020.0073)
+ Usage(1)
+ 0020.045f
+ Logical Minimum(-32767)
+ Logical Maximum(32767)
+ Report Size(8)
+ Report Count(1)
+ Report Offset(16)
+ Flags(Variable Absolute)
+ ..
+ ..
The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
This accelerometer-3D has some fields. Here for example field 2 is motion intensity
@@ -40,13 +40,14 @@ data will use this format.
Implementation
-=================
+==============
This specification defines many different types of sensors with different sets of
data fields. It is difficult to have a common input event to user space applications,
for different sensors. For example an accelerometer can send X,Y and Z data, whereas
an ambient light sensor can send illumination data.
So the implementation has two parts:
+
- Core hid driver
- Individual sensor processing part (sensor drivers)
@@ -55,8 +56,11 @@ Core driver
The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
report descriptors and identifies all the sensors present. It adds an MFD device
with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
-For example
+
+For example:
+
HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
+
So if any driver with this name is inserted, then the probe routine for that
function will be called. So an accelerometer processing driver can register
with this name and will be probed if there is an accelerometer-3D detected.
@@ -66,7 +70,8 @@ drivers to register and get events for that usage id. Also it provides parsing
functions, which get and set each input/feature/output report.
Individual sensor processing part (sensor drivers)
------------
+--------------------------------------------------
+
The processing driver will use an interface provided by the core driver to parse
the report and get the indexes of the fields and also can get events. This driver
can use IIO interface to use the standard ABI defined for a type of sensor.
@@ -75,31 +80,34 @@ can use IIO interface to use the standard ABI defined for a type of sensor.
Core driver Interface
=====================
-Callback structure:
-Each processing driver can use this structure to set some callbacks.
+Callback structure::
+
+ Each processing driver can use this structure to set some callbacks.
int (*suspend)(..): Callback when HID suspend is received
int (*resume)(..): Callback when HID resume is received
int (*capture_sample)(..): Capture a sample for one of its data fields
int (*send_event)(..): One complete event is received which can have
multiple data fields.
-Registration functions:
-int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
+Registration functions::
+
+ int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
u32 usage_id,
struct hid_sensor_hub_callbacks *usage_callback):
Registers callbacks for an usage id. The callback functions are not allowed
-to sleep.
+to sleep::
-int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
+ int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
u32 usage_id):
Removes callbacks for an usage id.
-Parsing function:
-int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
+Parsing function::
+
+ int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
u8 type,
u32 usage_id, u32 attr_usage_id,
struct hid_sensor_hub_attribute_info *info);
@@ -110,26 +118,27 @@ so that fields can be set or get individually.
These indexes avoid searching every time and getting field index to get or set.
-Set Feature report
-int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
+Set Feature report::
+
+ int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
u32 field_index, s32 value);
This interface is used to set a value for a field in feature report. For example
if there is a field report_interval, which is parsed by a call to
-sensor_hub_input_get_attribute_info before, then it can directly set that individual
-field.
+sensor_hub_input_get_attribute_info before, then it can directly set that
+individual field::
-int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
+ int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
u32 field_index, s32 *value);
This interface is used to get a value for a field in input report. For example
if there is a field report_interval, which is parsed by a call to
-sensor_hub_input_get_attribute_info before, then it can directly get that individual
-field value.
+sensor_hub_input_get_attribute_info before, then it can directly get that
+individual field value::
-int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
+ int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
u32 usage_id,
u32 attr_usage_id, u32 report_id);
@@ -143,6 +152,8 @@ registered callback function to process the sample.
----------
HID Custom and generic Sensors
+------------------------------
+
HID Sensor specification defines two special sensor usage types. Since they
don't represent a standard sensor, it is not possible to define using Linux IIO
@@ -158,66 +169,73 @@ keyboard attached/detached or lid open/close.
To allow application to utilize these sensors, here they are exported uses sysfs
attribute groups, attributes and misc device interface.
-An example of this representation on sysfs:
-/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
-.
-????????? enable_sensor
-????????? feature-0-200316
-??????? ????????? feature-0-200316-maximum
-??????? ????????? feature-0-200316-minimum
-??????? ????????? feature-0-200316-name
-??????? ????????? feature-0-200316-size
-??????? ????????? feature-0-200316-unit-expo
-??????? ????????? feature-0-200316-units
-??????? ????????? feature-0-200316-value
-????????? feature-1-200201
-??????? ????????? feature-1-200201-maximum
-??????? ????????? feature-1-200201-minimum
-??????? ????????? feature-1-200201-name
-??????? ????????? feature-1-200201-size
-??????? ????????? feature-1-200201-unit-expo
-??????? ????????? feature-1-200201-units
-??????? ????????? feature-1-200201-value
-????????? input-0-200201
-??????? ????????? input-0-200201-maximum
-??????? ????????? input-0-200201-minimum
-??????? ????????? input-0-200201-name
-??????? ????????? input-0-200201-size
-??????? ????????? input-0-200201-unit-expo
-??????? ????????? input-0-200201-units
-??????? ????????? input-0-200201-value
-????????? input-1-200202
-??????? ????????? input-1-200202-maximum
-??????? ????????? input-1-200202-minimum
-??????? ????????? input-1-200202-name
-??????? ????????? input-1-200202-size
-??????? ????????? input-1-200202-unit-expo
-??????? ????????? input-1-200202-units
-??????? ????????? input-1-200202-value
+An example of this representation on sysfs::
+
+ /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
+ .
+ │ ├── enable_sensor
+ │ │ ├── feature-0-200316
+ │ │ │ ├── feature-0-200316-maximum
+ │ │ │ ├── feature-0-200316-minimum
+ │ │ │ ├── feature-0-200316-name
+ │ │ │ ├── feature-0-200316-size
+ │ │ │ ├── feature-0-200316-unit-expo
+ │ │ │ ├── feature-0-200316-units
+ │ │ │ ├── feature-0-200316-value
+ │ │ ├── feature-1-200201
+ │ │ │ ├── feature-1-200201-maximum
+ │ │ │ ├── feature-1-200201-minimum
+ │ │ │ ├── feature-1-200201-name
+ │ │ │ ├── feature-1-200201-size
+ │ │ │ ├── feature-1-200201-unit-expo
+ │ │ │ ├── feature-1-200201-units
+ │ │ │ ├── feature-1-200201-value
+ │ │ ├── input-0-200201
+ │ │ │ ├── input-0-200201-maximum
+ │ │ │ ├── input-0-200201-minimum
+ │ │ │ ├── input-0-200201-name
+ │ │ │ ├── input-0-200201-size
+ │ │ │ ├── input-0-200201-unit-expo
+ │ │ │ ├── input-0-200201-units
+ │ │ │ ├── input-0-200201-value
+ │ │ ├── input-1-200202
+ │ │ │ ├── input-1-200202-maximum
+ │ │ │ ├── input-1-200202-minimum
+ │ │ │ ├── input-1-200202-name
+ │ │ │ ├── input-1-200202-size
+ │ │ │ ├── input-1-200202-unit-expo
+ │ │ │ ├── input-1-200202-units
+ │ │ │ ├── input-1-200202-value
Here there is a custom sensors with four fields, two feature and two inputs.
Each field is represented by a set of attributes. All fields except the "value"
are read only. The value field is a RW field.
-Example
-/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
-feature-0-200316-maximum:6
-feature-0-200316-minimum:0
-feature-0-200316-name:property-reporting-state
-feature-0-200316-size:1
-feature-0-200316-unit-expo:0
-feature-0-200316-units:25
-feature-0-200316-value:1
+
+Example::
+
+ /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
+ feature-0-200316-maximum:6
+ feature-0-200316-minimum:0
+ feature-0-200316-name:property-reporting-state
+ feature-0-200316-size:1
+ feature-0-200316-unit-expo:0
+ feature-0-200316-units:25
+ feature-0-200316-value:1
How to enable such sensor?
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
By default sensor can be power gated. To enable sysfs attribute "enable" can be
-used.
-$ echo 1 > enable_sensor
+used::
+
+ $ echo 1 > enable_sensor
Once enabled and powered on, sensor can report value using HID reports.
-These reports are pushed using misc device interface in a FIFO order.
-/dev$ tree | grep HID-SENSOR-2000e1.6.auto
-??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
-????????? HID-SENSOR-2000e1.6.auto
+These reports are pushed using misc device interface in a FIFO order::
+
+ /dev$ tree | grep HID-SENSOR-2000e1.6.auto
+ │ │ │ ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
+ │ ├── HID-SENSOR-2000e1.6.auto
Each reports can be of variable length preceded by a header. This header
consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
diff --git a/Documentation/hid/hid-transport.txt b/Documentation/hid/hid-transport.rst
similarity index 93%
rename from Documentation/hid/hid-transport.txt
rename to Documentation/hid/hid-transport.rst
index 3dcba9fd4a3a..6f3aaa86ce7b 100644
--- a/Documentation/hid/hid-transport.txt
+++ b/Documentation/hid/hid-transport.rst
@@ -1,5 +1,6 @@
- HID I/O Transport Drivers
- ===========================
+=========================
+HID I/O Transport Drivers
+=========================
The HID subsystem is independent of the underlying transport driver. Initially,
only USB was supported, but other specifications adopted the HID design and
@@ -16,6 +17,8 @@ transport and device setup/management. HID core is responsible of
report-parsing, report interpretation and the user-space API. Device specifics
and quirks are handled by all layers depending on the quirk.
+::
+
+-----------+ +-----------+ +-----------+ +-----------+
| Device #1 | | Device #i | | Device #j | | Device #k |
+-----------+ +-----------+ +-----------+ +-----------+
@@ -42,8 +45,9 @@ and quirks are handled by all layers depending on the quirk.
+----------------+ +-----------+ +------------------+ +------------------+
Example Drivers:
- I/O: USB, I2C, Bluetooth-l2cap
- Transport: USB-HID, I2C-HID, BT-HIDP
+
+ - I/O: USB, I2C, Bluetooth-l2cap
+ - Transport: USB-HID, I2C-HID, BT-HIDP
Everything below "HID Core" is simplified in this graph as it is only of
interest to HID device drivers. Transport drivers do not need to know the
@@ -183,7 +187,7 @@ Other ctrl-channel requests are supported by USB-HID but are not available
-------------------
Transport drivers normally use the following procedure to register a new device
-with HID core:
+with HID core::
struct hid_device *hid;
int ret;
@@ -215,7 +219,7 @@ Once hid_add_device() is entered, HID core might use the callbacks provided in
"custom_ll_driver". Note that fields like "country" can be ignored by underlying
transport-drivers if not supported.
-To unregister a device, use:
+To unregister a device, use::
hid_destroy_device(hid);
@@ -226,73 +230,110 @@ driver callbacks.
-----------------------------
The available HID callbacks are:
- - int (*start) (struct hid_device *hdev)
+
+ ::
+
+ int (*start) (struct hid_device *hdev)
+
Called from HID device drivers once they want to use the device. Transport
drivers can choose to setup their device in this callback. However, normally
devices are already set up before transport drivers register them to HID core
so this is mostly only used by USB-HID.
- - void (*stop) (struct hid_device *hdev)
+ ::
+
+ void (*stop) (struct hid_device *hdev)
+
Called from HID device drivers once they are done with a device. Transport
drivers can free any buffers and deinitialize the device. But note that
->start() might be called again if another HID device driver is loaded on the
device.
+
Transport drivers are free to ignore it and deinitialize devices after they
destroyed them via hid_destroy_device().
- - int (*open) (struct hid_device *hdev)
+ ::
+
+ int (*open) (struct hid_device *hdev)
+
Called from HID device drivers once they are interested in data reports.
Usually, while user-space didn't open any input API/etc., device drivers are
not interested in device data and transport drivers can put devices asleep.
However, once ->open() is called, transport drivers must be ready for I/O.
->open() calls are nested for each client that opens the HID device.
- - void (*close) (struct hid_device *hdev)
+ ::
+
+ void (*close) (struct hid_device *hdev)
+
Called from HID device drivers after ->open() was called but they are no
longer interested in device reports. (Usually if user-space closed any input
devices of the driver).
+
Transport drivers can put devices asleep and terminate any I/O of all
->open() calls have been followed by a ->close() call. However, ->start() may
be called again if the device driver is interested in input reports again.
- - int (*parse) (struct hid_device *hdev)
+ ::
+
+ int (*parse) (struct hid_device *hdev)
+
Called once during device setup after ->start() has been called. Transport
drivers must read the HID report-descriptor from the device and tell HID core
about it via hid_parse_report().
- - int (*power) (struct hid_device *hdev, int level)
+ ::
+
+ int (*power) (struct hid_device *hdev, int level)
+
Called by HID core to give PM hints to transport drivers. Usually this is
analogical to the ->open() and ->close() hints and redundant.
- - void (*request) (struct hid_device *hdev, struct hid_report *report,
- int reqtype)
+ ::
+
+ void (*request) (struct hid_device *hdev, struct hid_report *report,
+ int reqtype)
+
Send an HID request on the ctrl channel. "report" contains the report that
should be sent and "reqtype" the request type. Request-type can be
HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
+
This callback is optional. If not provided, HID core will assemble a raw
report following the HID specs and send it via the ->raw_request() callback.
The transport driver is free to implement this asynchronously.
- - int (*wait) (struct hid_device *hdev)
+ ::
+
+ int (*wait) (struct hid_device *hdev)
+
Used by HID core before calling ->request() again. A transport driver can use
it to wait for any pending requests to complete if only one request is
allowed at a time.
- - int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
- __u8 *buf, size_t count, unsigned char rtype,
- int reqtype)
+ ::
+
+ int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
+ __u8 *buf, size_t count, unsigned char rtype,
+ int reqtype)
+
Same as ->request() but provides the report as raw buffer. This request shall
be synchronous. A transport driver must not use ->wait() to complete such
requests. This request is mandatory and hid core will reject the device if
it is missing.
- - int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
+ ::
+
+ int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
+
Send raw output report via intr channel. Used by some HID device drivers
which require high throughput for outgoing requests on the intr channel. This
must not cause SET_REPORT calls! This must be implemented as asynchronous
output report on the intr channel!
- - int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
+ ::
+
+ int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
+
Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
2.3) Data Path
@@ -314,4 +355,5 @@ transport driver and not passed to hid_input_report().
Acknowledgements to SET_REPORT requests are not of interest to HID core.
----------------------------------------------------
+
Written 2013, David Herrmann <dh.herrmann@gmail.com>
diff --git a/Documentation/hid/hiddev.txt b/Documentation/hid/hiddev.rst
similarity index 77%
rename from Documentation/hid/hiddev.txt
rename to Documentation/hid/hiddev.rst
index 638448707aa2..209e6ba4e019 100644
--- a/Documentation/hid/hiddev.txt
+++ b/Documentation/hid/hiddev.rst
@@ -1,6 +1,9 @@
+================================================
Care and feeding of your Human Interface Devices
+================================================
-INTRODUCTION
+Introduction
+============
In addition to the normal input type HID devices, USB also uses the
human interface device protocols for things that are not really human
@@ -16,38 +19,40 @@ normalised event interface - see Documentation/input/input.rst
* the hiddev interface, which provides fairly raw HID events
The data flow for a HID event produced by a device is something like
-the following :
+the following::
usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event]
|
|
- --> hiddev.c ----> POWER / MONITOR CONTROL
+ --> hiddev.c ----> POWER / MONITOR CONTROL
In addition, other subsystems (apart from USB) can potentially feed
events into the input subsystem, but these have no effect on the hid
device interface.
-USING THE HID DEVICE INTERFACE
+Using the HID Device Interface
+==============================
The hiddev interface is a char interface using the normal USB major,
with the minor numbers starting at 96 and finishing at 111. Therefore,
-you need the following commands:
-mknod /dev/usb/hiddev0 c 180 96
-mknod /dev/usb/hiddev1 c 180 97
-mknod /dev/usb/hiddev2 c 180 98
-mknod /dev/usb/hiddev3 c 180 99
-mknod /dev/usb/hiddev4 c 180 100
-mknod /dev/usb/hiddev5 c 180 101
-mknod /dev/usb/hiddev6 c 180 102
-mknod /dev/usb/hiddev7 c 180 103
-mknod /dev/usb/hiddev8 c 180 104
-mknod /dev/usb/hiddev9 c 180 105
-mknod /dev/usb/hiddev10 c 180 106
-mknod /dev/usb/hiddev11 c 180 107
-mknod /dev/usb/hiddev12 c 180 108
-mknod /dev/usb/hiddev13 c 180 109
-mknod /dev/usb/hiddev14 c 180 110
-mknod /dev/usb/hiddev15 c 180 111
+you need the following commands::
+
+ mknod /dev/usb/hiddev0 c 180 96
+ mknod /dev/usb/hiddev1 c 180 97
+ mknod /dev/usb/hiddev2 c 180 98
+ mknod /dev/usb/hiddev3 c 180 99
+ mknod /dev/usb/hiddev4 c 180 100
+ mknod /dev/usb/hiddev5 c 180 101
+ mknod /dev/usb/hiddev6 c 180 102
+ mknod /dev/usb/hiddev7 c 180 103
+ mknod /dev/usb/hiddev8 c 180 104
+ mknod /dev/usb/hiddev9 c 180 105
+ mknod /dev/usb/hiddev10 c 180 106
+ mknod /dev/usb/hiddev11 c 180 107
+ mknod /dev/usb/hiddev12 c 180 108
+ mknod /dev/usb/hiddev13 c 180 109
+ mknod /dev/usb/hiddev14 c 180 110
+ mknod /dev/usb/hiddev15 c 180 111
So you point your hiddev compliant user-space program at the correct
interface for your device, and it all just works.
@@ -56,7 +61,9 @@ Assuming that you have a hiddev compliant user-space program, of
course. If you need to write one, read on.
-THE HIDDEV API
+The HIDDEV API
+==============
+
This description should be read in conjunction with the HID
specification, freely available from http://www.usb.org, and
conveniently linked of http://www.linux-usb.org.
@@ -69,12 +76,14 @@ each of which can have one or more "usages". In the hid-core,
each one of these usages has a single signed 32 bit value.
read():
+-------
+
This is the event interface. When the HID device's state changes,
it performs an interrupt transfer containing a report which contains
the changed value. The hid-core.c module parses the report, and
returns to hiddev.c the individual usages that have changed within
the report. In its basic mode, the hiddev will make these individual
-usage changes available to the reader using a struct hiddev_event:
+usage changes available to the reader using a struct hiddev_event::
struct hiddev_event {
unsigned hid;
@@ -90,13 +99,19 @@ behavior of the read() function can be modified using the HIDIOCSFLAG
ioctl() described below.
-ioctl():
-This is the control interface. There are a number of controls:
+ioctl():
+--------
-HIDIOCGVERSION - int (read)
-Gets the version code out of the hiddev driver.
+This is the control interface. There are a number of controls:
+
+HIDIOCGVERSION
+ - int (read)
+
+ Gets the version code out of the hiddev driver.
+
+HIDIOCAPPLICATION
+ - (none)
-HIDIOCAPPLICATION - (none)
This ioctl call returns the HID application usage associated with the
hid device. The third argument to ioctl() specifies which application
index to get. This is useful when the device has more than one
@@ -104,25 +119,33 @@ application collection. If the index is invalid (greater or equal to
the number of application collections this device has) the ioctl
returns -1. You can find out beforehand how many application
collections the device has from the num_applications field from the
-hiddev_devinfo structure.
+hiddev_devinfo structure.
+
+HIDIOCGCOLLECTIONINFO
+ - struct hiddev_collection_info (read/write)
-HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
This returns a superset of the information above, providing not only
application collections, but all the collections the device has. It
also returns the level the collection lives in the hierarchy.
-The user passes in a hiddev_collection_info struct with the index
-field set to the index that should be returned. The ioctl fills in
-the other fields. If the index is larger than the last collection
+The user passes in a hiddev_collection_info struct with the index
+field set to the index that should be returned. The ioctl fills in
+the other fields. If the index is larger than the last collection
index, the ioctl returns -1 and sets errno to -EINVAL.
-HIDIOCGDEVINFO - struct hiddev_devinfo (read)
+HIDIOCGDEVINFO
+ - struct hiddev_devinfo (read)
+
Gets a hiddev_devinfo structure which describes the device.
-HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
+HIDIOCGSTRING
+ - struct hiddev_string_descriptor (read/write)
+
Gets a string descriptor from the device. The caller must fill in the
"index" field to indicate which descriptor should be returned.
-HIDIOCINITREPORT - (none)
+HIDIOCINITREPORT
+ - (none)
+
Instructs the kernel to retrieve all input and feature report values
from the device. At this point, all the usage structures will contain
current values for the device, and will maintain it as the device
@@ -130,21 +153,29 @@ changes. Note that the use of this ioctl is unnecessary in general,
since later kernels automatically initialize the reports from the
device at attach time.
-HIDIOCGNAME - string (variable length)
+HIDIOCGNAME
+ - string (variable length)
+
Gets the device name
-HIDIOCGREPORT - struct hiddev_report_info (write)
+HIDIOCGREPORT
+ - struct hiddev_report_info (write)
+
Instructs the kernel to get a feature or input report from the device,
in order to selectively update the usage structures (in contrast to
INITREPORT).
-HIDIOCSREPORT - struct hiddev_report_info (write)
+HIDIOCSREPORT
+ - struct hiddev_report_info (write)
+
Instructs the kernel to send a report to the device. This report can
be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
individual usage values in the report before sending the report in full
-to the device.
+to the device.
+
+HIDIOCGREPORTINFO
+ - struct hiddev_report_info (read/write)
-HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
Fills in a hiddev_report_info structure for the user. The report is
looked up by type (input, output or feature) and id, so these fields
must be filled in by the user. The ID can be absolute -- the actual
@@ -154,52 +185,67 @@ report_id) for the next report after report_id. Without a-priori
information about report ids, the right way to use this ioctl is to
use the relative IDs above to enumerate the valid IDs. The ioctl
returns non-zero when there is no more next ID. The real report ID is
-filled into the returned hiddev_report_info structure.
+filled into the returned hiddev_report_info structure.
+
+HIDIOCGFIELDINFO
+ - struct hiddev_field_info (read/write)
-HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
Returns the field information associated with a report in a
hiddev_field_info structure. The user must fill in report_id and
report_type in this structure, as above. The field_index should also
be filled in, which should be a number from 0 and maxfield-1, as
-returned from a previous HIDIOCGREPORTINFO call.
+returned from a previous HIDIOCGREPORTINFO call.
+
+HIDIOCGUCODE
+ - struct hiddev_usage_ref (read/write)
-HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
Returns the usage_code in a hiddev_usage_ref structure, given that
given its report type, report id, field index, and index within the
field have already been filled into the structure.
-HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
+HIDIOCGUSAGE
+ - struct hiddev_usage_ref (read/write)
+
Returns the value of a usage in a hiddev_usage_ref structure. The
usage to be retrieved can be specified as above, or the user can
choose to fill in the report_type field and specify the report_id as
HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
filled in with the report and field information associated with this
-usage if it is found.
+usage if it is found.
+
+HIDIOCSUSAGE
+ - struct hiddev_usage_ref (write)
-HIDIOCSUSAGE - struct hiddev_usage_ref (write)
Sets the value of a usage in an output report. The user fills in
the hiddev_usage_ref structure as above, but additionally fills in
the value field.
-HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
+HIDIOGCOLLECTIONINDEX
+ - struct hiddev_usage_ref (write)
+
Returns the collection index associated with this usage. This
indicates where in the collection hierarchy this usage sits.
-HIDIOCGFLAG - int (read)
-HIDIOCSFLAG - int (write)
+HIDIOCGFLAG
+ - int (read)
+HIDIOCSFLAG
+ - int (write)
+
These operations respectively inspect and replace the mode flags
that influence the read() call above. The flags are as follows:
- HIDDEV_FLAG_UREF - read() calls will now return
+ HIDDEV_FLAG_UREF
+ - read() calls will now return
struct hiddev_usage_ref instead of struct hiddev_event.
This is a larger structure, but in situations where the
device has more than one usage in its reports with the
same usage code, this mode serves to resolve such
ambiguity.
- HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
+ HIDDEV_FLAG_REPORT
+ - This flag can only be used in conjunction
with HIDDEV_FLAG_UREF. With this flag set, when the device
sends a report, a struct hiddev_usage_ref will be returned
- to read() filled in with the report_type and report_id, but
+ to read() filled in with the report_type and report_id, but
with field_index set to FIELD_INDEX_NONE. This serves as
additional notification when the device has sent a report.
diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.rst
similarity index 89%
rename from Documentation/hid/hidraw.txt
rename to Documentation/hid/hidraw.rst
index c8436e354f44..4a4a0ba1f362 100644
--- a/Documentation/hid/hidraw.txt
+++ b/Documentation/hid/hidraw.rst
@@ -1,5 +1,6 @@
- HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
- ==================================================================
+================================================================
+HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
+================================================================
The hidraw driver provides a raw interface to USB and Bluetooth Human
Interface Devices (HIDs). It differs from hiddev in that reports sent and
@@ -31,6 +32,7 @@ directly under /dev (eg: /dev/hidraw0). As this location is distribution-
and udev rule-dependent, applications should use libudev to locate hidraw
devices attached to the system. There is a tutorial on libudev with a
working example at:
+
http://www.signal11.us/oss/udev/
The HIDRAW API
@@ -51,7 +53,7 @@ byte. For devices which do not use numbered reports, the report data
will begin at the first byte.
write()
---------
+-------
The write() function will write a report to the device. For USB devices, if
the device has an INTERRUPT OUT endpoint, the report will be sent on that
endpoint. If it does not, the report will be sent over the control endpoint,
@@ -62,38 +64,52 @@ number. If the device does not use numbered reports, the first byte should
be set to 0. The report data itself should begin at the second byte.
ioctl()
---------
+-------
Hidraw supports the following ioctls:
-HIDIOCGRDESCSIZE: Get Report Descriptor Size
+HIDIOCGRDESCSIZE:
+ Get Report Descriptor Size
+
This ioctl will get the size of the device's report descriptor.
-HIDIOCGRDESC: Get Report Descriptor
+HIDIOCGRDESC:
+ Get Report Descriptor
+
This ioctl returns the device's report descriptor using a
hidraw_report_descriptor struct. Make sure to set the size field of the
hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.
-HIDIOCGRAWINFO: Get Raw Info
+HIDIOCGRAWINFO:
+ Get Raw Info
+
This ioctl will return a hidraw_devinfo struct containing the bus type, the
vendor ID (VID), and product ID (PID) of the device. The bus type can be one
-of:
- BUS_USB
- BUS_HIL
- BUS_BLUETOOTH
- BUS_VIRTUAL
+of::
+
+ - BUS_USB
+ - BUS_HIL
+ - BUS_BLUETOOTH
+ - BUS_VIRTUAL
+
which are defined in uapi/linux/input.h.
-HIDIOCGRAWNAME(len): Get Raw Name
+HIDIOCGRAWNAME(len):
+ Get Raw Name
+
This ioctl returns a string containing the vendor and product strings of
the device. The returned string is Unicode, UTF-8 encoded.
-HIDIOCGRAWPHYS(len): Get Physical Address
+HIDIOCGRAWPHYS(len):
+ Get Physical Address
+
This ioctl returns a string representing the physical address of the device.
For USB devices, the string contains the physical path to the device (the
USB controller, hubs, ports, etc). For Bluetooth devices, the string
contains the hardware (MAC) address of the device.
-HIDIOCSFEATURE(len): Send a Feature Report
+HIDIOCSFEATURE(len):
+ Send a Feature Report
+
This ioctl will send a feature report to the device. Per the HID
specification, feature reports are always sent using the control endpoint.
Set the first byte of the supplied buffer to the report number. For devices
@@ -101,7 +117,9 @@ which do not use numbered reports, set the first byte to 0. The report data
begins in the second byte. Make sure to set len accordingly, to one more
than the length of the report (to account for the report number).
-HIDIOCGFEATURE(len): Get a Feature Report
+HIDIOCGFEATURE(len):
+ Get a Feature Report
+
This ioctl will request a feature report from the device using the control
endpoint. The first byte of the supplied buffer should be set to the report
number of the requested report. For devices which do not use numbered
@@ -109,11 +127,12 @@ reports, set the first byte to 0. The report will be returned starting at
the first byte of the buffer (ie: the report number is not returned).
Example
----------
+-------
In samples/, find hid-example.c, which shows examples of read(), write(),
and all the ioctls for hidraw. The code may be used by anyone for any
purpose, and can serve as a starting point for developing applications using
hidraw.
Document by:
+
Alan Ott <alan@signal11.us>, Signal 11 Software
diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst
new file mode 100644
index 000000000000..af4324902622
--- /dev/null
+++ b/Documentation/hid/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=============================
+Human Interface Devices (HID)
+=============================
+
+.. toctree::
+ :maxdepth: 1
+
+ hiddev
+ hidraw
+ hid-sensor
+ hid-transport
+
+ uhid
+
+ hid-alps
+ intel-ish-hid
diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst
new file mode 100644
index 000000000000..cccbf4be17d7
--- /dev/null
+++ b/Documentation/hid/intel-ish-hid.rst
@@ -0,0 +1,485 @@
+=================================
+Intel Integrated Sensor Hub (ISH)
+=================================
+
+A sensor hub enables the ability to offload sensor polling and algorithm
+processing to a dedicated low power co-processor. This allows the core
+processor to go into low power modes more often, resulting in the increased
+battery life.
+
+There are many vendors providing external sensor hubs confirming to HID
+Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
+and embedded products. Linux had this support since Linux 3.9.
+
+Intel® introduced integrated sensor hubs as a part of the SoC starting from
+Cherry Trail and now supported on multiple generations of CPU packages. There
+are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
+These ISH also comply to HID sensor specification, but the difference is the
+transport protocol used for communication. The current external sensor hubs
+mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
+
+1. Overview
+===========
+
+Using a analogy with a usbhid implementation, the ISH follows a similar model
+for a very high speed communication::
+
+ ----------------- ----------------------
+ | USB HID | --> | ISH HID |
+ ----------------- ----------------------
+ ----------------- ----------------------
+ | USB protocol | --> | ISH Transport |
+ ----------------- ----------------------
+ ----------------- ----------------------
+ | EHCI/XHCI | --> | ISH IPC |
+ ----------------- ----------------------
+ PCI PCI
+ ----------------- ----------------------
+ |Host controller| --> | ISH processor |
+ ----------------- ----------------------
+ USB Link
+ ----------------- ----------------------
+ | USB End points| --> | ISH Clients |
+ ----------------- ----------------------
+
+Like USB protocol provides a method for device enumeration, link management
+and user data encapsulation, the ISH also provides similar services. But it is
+very light weight tailored to manage and communicate with ISH client
+applications implemented in the firmware.
+
+The ISH allows multiple sensor management applications executing in the
+firmware. Like USB endpoints the messaging can be to/from a client. As part of
+enumeration process, these clients are identified. These clients can be simple
+HID sensor applications, sensor calibration application or senor firmware
+update application.
+
+The implementation model is similar, like USB bus, ISH transport is also
+implemented as a bus. Each client application executing in the ISH processor
+is registered as a device on this bus. The driver, which binds each device
+(ISH HID driver) identifies the device type and registers with the hid core.
+
+2. ISH Implementation: Block Diagram
+====================================
+
+::
+
+ ---------------------------
+ | User Space Applications |
+ ---------------------------
+
+ ----------------IIO ABI----------------
+ --------------------------
+ | IIO Sensor Drivers |
+ --------------------------
+ --------------------------
+ | IIO core |
+ --------------------------
+ --------------------------
+ | HID Sensor Hub MFD |
+ --------------------------
+ --------------------------
+ | HID Core |
+ --------------------------
+ --------------------------
+ | HID over ISH Client |
+ --------------------------
+ --------------------------
+ | ISH Transport (ISHTP) |
+ --------------------------
+ --------------------------
+ | IPC Drivers |
+ --------------------------
+ OS
+ ---------------- PCI -----------------
+ Hardware + Firmware
+ ----------------------------
+ | ISH Hardware/Firmware(FW) |
+ ----------------------------
+
+3. High level processing in above blocks
+========================================
+
+3.1 Hardware Interface
+----------------------
+
+The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
+product and vendor IDs are changed from different generations of processors. So
+the source code which enumerate drivers needs to update from generation to
+generation.
+
+3.2 Inter Processor Communication (IPC) driver
+----------------------------------------------
+
+Location: drivers/hid/intel-ish-hid/ipc
+
+The IPC message used memory mapped I/O. The registers are defined in
+hw-ish-regs.h.
+
+3.2.1 IPC/FW message types
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two types of messages, one for management of link and other messages
+are to and from transport layers.
+
+TX and RX of Transport messages
+...............................
+
+A set of memory mapped register offers support of multi byte messages TX and
+RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
+internal queues to sequence messages and send them in order to the FW.
+Optionally the caller can register handler to get notification of completion.
+A door bell mechanism is used in messaging to trigger processing in host and
+client firmware side. When ISH interrupt handler is called, the ISH2HOST
+doorbell register is used by host drivers to determine that the interrupt
+is for ISH.
+
+Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
+register has the following format:
+Bits 0..6: fragment length (7 bits are used)
+Bits 10..13: encapsulated protocol
+Bits 16..19: management command (for IPC management protocol)
+Bit 31: doorbell trigger (signal H/W interrupt to the other side)
+Other bits are reserved, should be 0.
+
+3.2.2 Transport layer interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To abstract HW level IPC communication, a set of callbacks are registered.
+The transport layer uses them to send and receive messages.
+Refer to struct ishtp_hw_ops for callbacks.
+
+3.3 ISH Transport layer
+-----------------------
+
+Location: drivers/hid/intel-ish-hid/ishtp/
+
+3.3.1 A Generic Transport Layer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The transport layer is a bi-directional protocol, which defines:
+- Set of commands to start, stop, connect, disconnect and flow control
+(ishtp/hbm.h) for details
+- A flow control mechanism to avoid buffer overflows
+
+This protocol resembles bus messages described in the following document:
+http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
+specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
+
+3.3.2 Connection and Flow Control Mechanism
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each FW client and a protocol is identified by an UUID. In order to communicate
+to a FW client, a connection must be established using connect request and
+response bus messages. If successful, a pair (host_client_id and fw_client_id)
+will identify the connection.
+
+Once connection is established, peers send each other flow control bus messages
+independently. Every peer may send a message only if it has received a
+flow-control credit before. Once it sent a message, it may not send another one
+before receiving the next flow control credit.
+Either side can send disconnect request bus message to end communication. Also
+the link will be dropped if major FW reset occurs.
+
+3.3.3 Peer to Peer data transfer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Peer to Peer data transfer can happen with or without using DMA. Depending on
+the sensor bandwidth requirement DMA can be enabled by using module parameter
+ishtp_use_dma under intel_ishtp.
+
+Each side (host and FW) manages its DMA transfer memory independently. When an
+ISHTP client from either host or FW side wants to send something, it decides
+whether to send over IPC or over DMA; for each transfer the decision is
+independent. The sending side sends DMA_XFER message when the message is in
+the respective host buffer (TX when host client sends, RX when FW client
+sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
+the sender that the memory region for that message may be reused.
+
+DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
+(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
+Additionally to DMA address communication, this sequence checks capabilities:
+if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
+send DMA; if FW doesn't support DMA then it won't respond with
+DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
+Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
+it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
+that it already did DMA and the message resides at host. Thus, DMA_XFER
+and DMA_XFER_ACK act as ownership indicators.
+
+At initial state all outgoing memory belongs to the sender (TX to host, RX to
+FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
+the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
+needs not wait for previous DMA_XFER to be ack'ed, and may send another message
+as long as remaining continuous memory in its ownership is enough.
+In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
+(up to IPC MTU), thus allowing for interrupt throttling.
+Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
+fragments and via IPC otherwise.
+
+3.3.4 Ring Buffers
+^^^^^^^^^^^^^^^^^^
+
+When a client initiate a connection, a ring or RX and TX buffers are allocated.
+The size of ring can be specified by the client. HID client set 16 and 32 for
+TX and RX buffers respectively. On send request from client, the data to be
+sent is copied to one of the send ring buffer and scheduled to be sent using
+bus message protocol. These buffers are required because the FW may have not
+have processed the last message and may not have enough flow control credits
+to send. Same thing holds true on receive side and flow control is required.
+
+3.3.5 Host Enumeration
+^^^^^^^^^^^^^^^^^^^^^^
+
+The host enumeration bus command allow discovery of clients present in the FW.
+There can be multiple sensor clients and clients for calibration function.
+
+To ease in implantation and allow independent driver handle each client
+this transport layer takes advantage of Linux Bus driver model. Each
+client is registered as device on the the transport bus (ishtp bus).
+
+Enumeration sequence of messages:
+
+- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
+- FW responds with HOST_START_RES_CMD
+- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
+- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
+ client IDs
+- For each FW ID found in that bitmap host sends
+ HOST_CLIENT_PROPERTIES_REQ_CMD
+- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
+ max ISHTP message size, etc.
+- Once host received properties for that last discovered client, it considers
+ ISHTP device fully functional (and allocates DMA buffers)
+
+3.4 HID over ISH Client
+-----------------------
+
+Location: drivers/hid/intel-ish-hid
+
+The ISHTP client driver is responsible for:
+
+- enumerate HID devices under FW ISH client
+- Get Report descriptor
+- Register with HID core as a LL driver
+- Process Get/Set feature request
+- Get input reports
+
+3.5 HID Sensor Hub MFD and IIO sensor drivers
+---------------------------------------------
+
+The functionality in these drivers is the same as an external sensor hub.
+Refer to
+Documentation/hid/hid-sensor.rst for HID sensor
+Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
+
+3.6 End to End HID transport Sequence Diagram
+---------------------------------------------
+
+::
+
+ HID-ISH-CLN ISHTP IPC HW
+ | | | |
+ | | |-----WAKE UP------------------>|
+ | | | |
+ | | |-----HOST READY--------------->|
+ | | | |
+ | | |<----MNG_RESET_NOTIFY_ACK----- |
+ | | | |
+ | |<----ISHTP_START------ | |
+ | | | |
+ | |<-----------------HOST_START_RES_CMD-------------------|
+ | | | |
+ | |------------------QUERY_SUBSCRIBER-------------------->|
+ | | | |
+ | |------------------HOST_ENUM_REQ_CMD------------------->|
+ | | | |
+ | |<-----------------HOST_ENUM_RES_CMD--------------------|
+ | | | |
+ | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
+ | | | |
+ | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
+ | Create new device on in ishtp bus | |
+ | | | |
+ | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
+ | | | |
+ | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
+ | Create new device on in ishtp bus | |
+ | | | |
+ | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
+ | | | |
+ probed()
+ |----ishtp_cl_connect--->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
+ | | | |
+ | |<----------------CLIENT_CONNECT_RES_CMD----------------|
+ | | | |
+ |register event callback | | |
+ | | | |
+ |ishtp_cl_send(
+ HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >|
+ | | | |
+ | | |<-----IRQ(IPC_PROTOCOL_ISHTP---|
+ | | | |
+ |<--ENUM_DEVICE RSP------| | |
+ | | | |
+ for each enumerated device
+ |ishtp_cl_send(
+ HOSTIF_GET_HID_DESCRIPTOR|----------fill ishtp_msg_hdr struct write to HW----- >|
+ | | | |
+ ...Response
+ | | | |
+ for each enumerated device
+ |ishtp_cl_send(
+ HOSTIF_GET_REPORT_DESCRIPTOR|--------------fill ishtp_msg_hdr struct write to HW-- >|
+ | | | |
+ | | | |
+ hid_allocate_device
+ | | | |
+ hid_add_device | | |
+ | | | |
+
+
+3.7 ISH Debugging
+-----------------
+
+To debug ISH, event tracing mechanism is used. To enable debug logs
+echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
+cat sys/kernel/debug/tracing/trace
+
+3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
+-----------------------------------------------------
+
+::
+
+ root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
+ /sys/bus/iio/devices/
+ ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
+ │ ├── buffer
+ │ │ ├── enable
+ │ │ ├── length
+ │ │ └── watermark
+ ...
+ │ ├── in_accel_hysteresis
+ │ ├── in_accel_offset
+ │ ├── in_accel_sampling_frequency
+ │ ├── in_accel_scale
+ │ ├── in_accel_x_raw
+ │ ├── in_accel_y_raw
+ │ ├── in_accel_z_raw
+ │ ├── name
+ │ ├── scan_elements
+ │ │ ├── in_accel_x_en
+ │ │ ├── in_accel_x_index
+ │ │ ├── in_accel_x_type
+ │ │ ├── in_accel_y_en
+ │ │ ├── in_accel_y_index
+ │ │ ├── in_accel_y_type
+ │ │ ├── in_accel_z_en
+ │ │ ├── in_accel_z_index
+ │ │ └── in_accel_z_type
+ ...
+ │ │ ├── devices
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_intensity_both_raw
+ │ │ │ │ ├── in_intensity_hysteresis
+ │ │ │ │ ├── in_intensity_offset
+ │ │ │ │ ├── in_intensity_sampling_frequency
+ │ │ │ │ ├── in_intensity_scale
+ │ │ │ │ ├── name
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_intensity_both_en
+ │ │ │ │ │ ├── in_intensity_both_index
+ │ │ │ │ │ └── in_intensity_both_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_magn_hysteresis
+ │ │ │ │ ├── in_magn_offset
+ │ │ │ │ ├── in_magn_sampling_frequency
+ │ │ │ │ ├── in_magn_scale
+ │ │ │ │ ├── in_magn_x_raw
+ │ │ │ │ ├── in_magn_y_raw
+ │ │ │ │ ├── in_magn_z_raw
+ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw
+ │ │ │ │ ├── in_rot_hysteresis
+ │ │ │ │ ├── in_rot_offset
+ │ │ │ │ ├── in_rot_sampling_frequency
+ │ │ │ │ ├── in_rot_scale
+ │ │ │ │ ├── name
+ ...
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_magn_x_en
+ │ │ │ │ │ ├── in_magn_x_index
+ │ │ │ │ │ ├── in_magn_x_type
+ │ │ │ │ │ ├── in_magn_y_en
+ │ │ │ │ │ ├── in_magn_y_index
+ │ │ │ │ │ ├── in_magn_y_type
+ │ │ │ │ │ ├── in_magn_z_en
+ │ │ │ │ │ ├── in_magn_z_index
+ │ │ │ │ │ ├── in_magn_z_type
+ │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en
+ │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index
+ │ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_anglvel_hysteresis
+ │ │ │ │ ├── in_anglvel_offset
+ │ │ │ │ ├── in_anglvel_sampling_frequency
+ │ │ │ │ ├── in_anglvel_scale
+ │ │ │ │ ├── in_anglvel_x_raw
+ │ │ │ │ ├── in_anglvel_y_raw
+ │ │ │ │ ├── in_anglvel_z_raw
+ │ │ │ │ ├── name
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_anglvel_x_en
+ │ │ │ │ │ ├── in_anglvel_x_index
+ │ │ │ │ │ ├── in_anglvel_x_type
+ │ │ │ │ │ ├── in_anglvel_y_en
+ │ │ │ │ │ ├── in_anglvel_y_index
+ │ │ │ │ │ ├── in_anglvel_y_type
+ │ │ │ │ │ ├── in_anglvel_z_en
+ │ │ │ │ │ ├── in_anglvel_z_index
+ │ │ │ │ │ └── in_anglvel_z_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_anglvel_hysteresis
+ │ │ │ │ ├── in_anglvel_offset
+ │ │ │ │ ├── in_anglvel_sampling_frequency
+ │ │ │ │ ├── in_anglvel_scale
+ │ │ │ │ ├── in_anglvel_x_raw
+ │ │ │ │ ├── in_anglvel_y_raw
+ │ │ │ │ ├── in_anglvel_z_raw
+ │ │ │ │ ├── name
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_anglvel_x_en
+ │ │ │ │ │ ├── in_anglvel_x_index
+ │ │ │ │ │ ├── in_anglvel_x_type
+ │ │ │ │ │ ├── in_anglvel_y_en
+ │ │ │ │ │ ├── in_anglvel_y_index
+ │ │ │ │ │ ├── in_anglvel_y_type
+ │ │ │ │ │ ├── in_anglvel_z_en
+ │ │ │ │ │ ├── in_anglvel_z_index
+ │ │ │ │ │ └── in_anglvel_z_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
diff --git a/Documentation/hid/intel-ish-hid.txt b/Documentation/hid/intel-ish-hid.txt
deleted file mode 100644
index d48b21c71ddd..000000000000
--- a/Documentation/hid/intel-ish-hid.txt
+++ /dev/null
@@ -1,454 +0,0 @@
-Intel Integrated Sensor Hub (ISH)
-===============================
-
-A sensor hub enables the ability to offload sensor polling and algorithm
-processing to a dedicated low power co-processor. This allows the core
-processor to go into low power modes more often, resulting in the increased
-battery life.
-
-There are many vendors providing external sensor hubs confirming to HID
-Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
-and embedded products. Linux had this support since Linux 3.9.
-
-Intel® introduced integrated sensor hubs as a part of the SoC starting from
-Cherry Trail and now supported on multiple generations of CPU packages. There
-are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
-These ISH also comply to HID sensor specification, but the difference is the
-transport protocol used for communication. The current external sensor hubs
-mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
-
-1. Overview
-
-Using a analogy with a usbhid implementation, the ISH follows a similar model
-for a very high speed communication:
-
- ----------------- ----------------------
- | USB HID | --> | ISH HID |
- ----------------- ----------------------
- ----------------- ----------------------
- | USB protocol | --> | ISH Transport |
- ----------------- ----------------------
- ----------------- ----------------------
- | EHCI/XHCI | --> | ISH IPC |
- ----------------- ----------------------
- PCI PCI
- ----------------- ----------------------
- |Host controller| --> | ISH processor |
- ----------------- ----------------------
- USB Link
- ----------------- ----------------------
- | USB End points| --> | ISH Clients |
- ----------------- ----------------------
-
-Like USB protocol provides a method for device enumeration, link management
-and user data encapsulation, the ISH also provides similar services. But it is
-very light weight tailored to manage and communicate with ISH client
-applications implemented in the firmware.
-
-The ISH allows multiple sensor management applications executing in the
-firmware. Like USB endpoints the messaging can be to/from a client. As part of
-enumeration process, these clients are identified. These clients can be simple
-HID sensor applications, sensor calibration application or senor firmware
-update application.
-
-The implementation model is similar, like USB bus, ISH transport is also
-implemented as a bus. Each client application executing in the ISH processor
-is registered as a device on this bus. The driver, which binds each device
-(ISH HID driver) identifies the device type and registers with the hid core.
-
-2. ISH Implementation: Block Diagram
-
- ---------------------------
- | User Space Applications |
- ---------------------------
-
-----------------IIO ABI----------------
- --------------------------
- | IIO Sensor Drivers |
- --------------------------
- --------------------------
- | IIO core |
- --------------------------
- --------------------------
- | HID Sensor Hub MFD |
- --------------------------
- --------------------------
- | HID Core |
- --------------------------
- --------------------------
- | HID over ISH Client |
- --------------------------
- --------------------------
- | ISH Transport (ISHTP) |
- --------------------------
- --------------------------
- | IPC Drivers |
- --------------------------
-OS
----------------- PCI -----------------
-Hardware + Firmware
- ----------------------------
- | ISH Hardware/Firmware(FW) |
- ----------------------------
-
-3. High level processing in above blocks
-
-3.1 Hardware Interface
-
-The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
-product and vendor IDs are changed from different generations of processors. So
-the source code which enumerate drivers needs to update from generation to
-generation.
-
-3.2 Inter Processor Communication (IPC) driver
-Location: drivers/hid/intel-ish-hid/ipc
-
-The IPC message used memory mapped I/O. The registers are defined in
-hw-ish-regs.h.
-
-3.2.1 IPC/FW message types
-
-There are two types of messages, one for management of link and other messages
-are to and from transport layers.
-
-TX and RX of Transport messages
-
-A set of memory mapped register offers support of multi byte messages TX and
-RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
-internal queues to sequence messages and send them in order to the FW.
-Optionally the caller can register handler to get notification of completion.
-A door bell mechanism is used in messaging to trigger processing in host and
-client firmware side. When ISH interrupt handler is called, the ISH2HOST
-doorbell register is used by host drivers to determine that the interrupt
-is for ISH.
-
-Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
-register has the following format:
-Bits 0..6: fragment length (7 bits are used)
-Bits 10..13: encapsulated protocol
-Bits 16..19: management command (for IPC management protocol)
-Bit 31: doorbell trigger (signal H/W interrupt to the other side)
-Other bits are reserved, should be 0.
-
-3.2.2 Transport layer interface
-
-To abstract HW level IPC communication, a set of callbacks are registered.
-The transport layer uses them to send and receive messages.
-Refer to struct ishtp_hw_ops for callbacks.
-
-3.3 ISH Transport layer
-Location: drivers/hid/intel-ish-hid/ishtp/
-
-3.3.1 A Generic Transport Layer
-
-The transport layer is a bi-directional protocol, which defines:
-- Set of commands to start, stop, connect, disconnect and flow control
-(ishtp/hbm.h) for details
-- A flow control mechanism to avoid buffer overflows
-
-This protocol resembles bus messages described in the following document:
-http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
-specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
-
-3.3.2 Connection and Flow Control Mechanism
-
-Each FW client and a protocol is identified by an UUID. In order to communicate
-to a FW client, a connection must be established using connect request and
-response bus messages. If successful, a pair (host_client_id and fw_client_id)
-will identify the connection.
-
-Once connection is established, peers send each other flow control bus messages
-independently. Every peer may send a message only if it has received a
-flow-control credit before. Once it sent a message, it may not send another one
-before receiving the next flow control credit.
-Either side can send disconnect request bus message to end communication. Also
-the link will be dropped if major FW reset occurs.
-
-3.3.3 Peer to Peer data transfer
-
-Peer to Peer data transfer can happen with or without using DMA. Depending on
-the sensor bandwidth requirement DMA can be enabled by using module parameter
-ishtp_use_dma under intel_ishtp.
-
-Each side (host and FW) manages its DMA transfer memory independently. When an
-ISHTP client from either host or FW side wants to send something, it decides
-whether to send over IPC or over DMA; for each transfer the decision is
-independent. The sending side sends DMA_XFER message when the message is in
-the respective host buffer (TX when host client sends, RX when FW client
-sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
-the sender that the memory region for that message may be reused.
-
-DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
-(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
-Additionally to DMA address communication, this sequence checks capabilities:
-if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
-send DMA; if FW doesn't support DMA then it won't respond with
-DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
-Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
-it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
-that it already did DMA and the message resides at host. Thus, DMA_XFER
-and DMA_XFER_ACK act as ownership indicators.
-
-At initial state all outgoing memory belongs to the sender (TX to host, RX to
-FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
-the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
-needs not wait for previous DMA_XFER to be ack'ed, and may send another message
-as long as remaining continuous memory in its ownership is enough.
-In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
-(up to IPC MTU), thus allowing for interrupt throttling.
-Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
-fragments and via IPC otherwise.
-
-3.3.4 Ring Buffers
-
-When a client initiate a connection, a ring or RX and TX buffers are allocated.
-The size of ring can be specified by the client. HID client set 16 and 32 for
-TX and RX buffers respectively. On send request from client, the data to be
-sent is copied to one of the send ring buffer and scheduled to be sent using
-bus message protocol. These buffers are required because the FW may have not
-have processed the last message and may not have enough flow control credits
-to send. Same thing holds true on receive side and flow control is required.
-
-3.3.5 Host Enumeration
-
-The host enumeration bus command allow discovery of clients present in the FW.
-There can be multiple sensor clients and clients for calibration function.
-
-To ease in implantation and allow independent driver handle each client
-this transport layer takes advantage of Linux Bus driver model. Each
-client is registered as device on the the transport bus (ishtp bus).
-
-Enumeration sequence of messages:
-- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
-- FW responds with HOST_START_RES_CMD
-- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
-- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
-client IDs
-- For each FW ID found in that bitmap host sends
-HOST_CLIENT_PROPERTIES_REQ_CMD
-- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
-max ISHTP message size, etc.
-- Once host received properties for that last discovered client, it considers
-ISHTP device fully functional (and allocates DMA buffers)
-
-3.4 HID over ISH Client
-Location: drivers/hid/intel-ish-hid
-
-The ISHTP client driver is responsible for:
-- enumerate HID devices under FW ISH client
-- Get Report descriptor
-- Register with HID core as a LL driver
-- Process Get/Set feature request
-- Get input reports
-
-3.5 HID Sensor Hub MFD and IIO sensor drivers
-
-The functionality in these drivers is the same as an external sensor hub.
-Refer to
-Documentation/hid/hid-sensor.txt for HID sensor
-Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
-
-3.6 End to End HID transport Sequence Diagram
-
-HID-ISH-CLN ISHTP IPC HW
- | | | |
- | | |-----WAKE UP------------------>|
- | | | |
- | | |-----HOST READY--------------->|
- | | | |
- | | |<----MNG_RESET_NOTIFY_ACK----- |
- | | | |
- | |<----ISHTP_START------ | |
- | | | |
- | |<-----------------HOST_START_RES_CMD-------------------|
- | | | |
- | |------------------QUERY_SUBSCRIBER-------------------->|
- | | | |
- | |------------------HOST_ENUM_REQ_CMD------------------->|
- | | | |
- | |<-----------------HOST_ENUM_RES_CMD--------------------|
- | | | |
- | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
- | | | |
- | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
- | Create new device on in ishtp bus | |
- | | | |
- | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
- | | | |
- | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
- | Create new device on in ishtp bus | |
- | | | |
- | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
- | | | |
- probed()
- |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
- | | | |
- | |<----------------CLIENT_CONNECT_RES_CMD----------------|
- | | | |
- |register event callback| | |
- | | | |
- |ishtp_cl_send(
- HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >|
- | | | |
- | | |<-----IRQ(IPC_PROTOCOL_ISHTP---|
- | | | |
- |<--ENUM_DEVICE RSP-----| | |
- | | | |
-for each enumerated device
- |ishtp_cl_send(
- HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW--- >|
- | | | |
- ...Response
- | | | |
-for each enumerated device
- |ishtp_cl_send(
- HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >|
- | | | |
- | | | |
- hid_allocate_device
- | | | |
- hid_add_device | | |
- | | | |
-
-
-3.7 ISH Debugging
-
-To debug ISH, event tracing mechanism is used. To enable debug logs
-echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
-cat sys/kernel/debug/tracing/trace
-
-3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
-
-root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
-/sys/bus/iio/devices/
-├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
-│ ├── buffer
-│ │ ├── enable
-│ │ ├── length
-│ │ └── watermark
-...
-│ ├── in_accel_hysteresis
-│ ├── in_accel_offset
-│ ├── in_accel_sampling_frequency
-│ ├── in_accel_scale
-│ ├── in_accel_x_raw
-│ ├── in_accel_y_raw
-│ ├── in_accel_z_raw
-│ ├── name
-│ ├── scan_elements
-│ │ ├── in_accel_x_en
-│ │ ├── in_accel_x_index
-│ │ ├── in_accel_x_type
-│ │ ├── in_accel_y_en
-│ │ ├── in_accel_y_index
-│ │ ├── in_accel_y_type
-│ │ ├── in_accel_z_en
-│ │ ├── in_accel_z_index
-│ │ └── in_accel_z_type
-...
-│ │ ├── devices
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_intensity_both_raw
-│ │ │ │ ├── in_intensity_hysteresis
-│ │ │ │ ├── in_intensity_offset
-│ │ │ │ ├── in_intensity_sampling_frequency
-│ │ │ │ ├── in_intensity_scale
-│ │ │ │ ├── name
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_intensity_both_en
-│ │ │ │ │ ├── in_intensity_both_index
-│ │ │ │ │ └── in_intensity_both_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_magn_hysteresis
-│ │ │ │ ├── in_magn_offset
-│ │ │ │ ├── in_magn_sampling_frequency
-│ │ │ │ ├── in_magn_scale
-│ │ │ │ ├── in_magn_x_raw
-│ │ │ │ ├── in_magn_y_raw
-│ │ │ │ ├── in_magn_z_raw
-│ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw
-│ │ │ │ ├── in_rot_hysteresis
-│ │ │ │ ├── in_rot_offset
-│ │ │ │ ├── in_rot_sampling_frequency
-│ │ │ │ ├── in_rot_scale
-│ │ │ │ ├── name
-...
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_magn_x_en
-│ │ │ │ │ ├── in_magn_x_index
-│ │ │ │ │ ├── in_magn_x_type
-│ │ │ │ │ ├── in_magn_y_en
-│ │ │ │ │ ├── in_magn_y_index
-│ │ │ │ │ ├── in_magn_y_type
-│ │ │ │ │ ├── in_magn_z_en
-│ │ │ │ │ ├── in_magn_z_index
-│ │ │ │ │ ├── in_magn_z_type
-│ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en
-│ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index
-│ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_anglvel_hysteresis
-│ │ │ │ ├── in_anglvel_offset
-│ │ │ │ ├── in_anglvel_sampling_frequency
-│ │ │ │ ├── in_anglvel_scale
-│ │ │ │ ├── in_anglvel_x_raw
-│ │ │ │ ├── in_anglvel_y_raw
-│ │ │ │ ├── in_anglvel_z_raw
-│ │ │ │ ├── name
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_anglvel_x_en
-│ │ │ │ │ ├── in_anglvel_x_index
-│ │ │ │ │ ├── in_anglvel_x_type
-│ │ │ │ │ ├── in_anglvel_y_en
-│ │ │ │ │ ├── in_anglvel_y_index
-│ │ │ │ │ ├── in_anglvel_y_type
-│ │ │ │ │ ├── in_anglvel_z_en
-│ │ │ │ │ ├── in_anglvel_z_index
-│ │ │ │ │ └── in_anglvel_z_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_anglvel_hysteresis
-│ │ │ │ ├── in_anglvel_offset
-│ │ │ │ ├── in_anglvel_sampling_frequency
-│ │ │ │ ├── in_anglvel_scale
-│ │ │ │ ├── in_anglvel_x_raw
-│ │ │ │ ├── in_anglvel_y_raw
-│ │ │ │ ├── in_anglvel_z_raw
-│ │ │ │ ├── name
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_anglvel_x_en
-│ │ │ │ │ ├── in_anglvel_x_index
-│ │ │ │ │ ├── in_anglvel_x_type
-│ │ │ │ │ ├── in_anglvel_y_en
-│ │ │ │ │ ├── in_anglvel_y_index
-│ │ │ │ │ ├── in_anglvel_y_type
-│ │ │ │ │ ├── in_anglvel_z_en
-│ │ │ │ │ ├── in_anglvel_z_index
-│ │ │ │ │ └── in_anglvel_z_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.rst
similarity index 94%
rename from Documentation/hid/uhid.txt
rename to Documentation/hid/uhid.rst
index 958fff945304..b18cb96c885f 100644
--- a/Documentation/hid/uhid.txt
+++ b/Documentation/hid/uhid.rst
@@ -1,5 +1,6 @@
- UHID - User-space I/O driver support for HID subsystem
- ========================================================
+======================================================
+UHID - User-space I/O driver support for HID subsystem
+======================================================
UHID allows user-space to implement HID transport drivers. Please see
hid-transport.txt for an introduction into HID transport drivers. This document
@@ -22,9 +23,9 @@ If a new device is detected by your HID I/O Driver and you want to register this
device with the HID subsystem, then you need to open /dev/uhid once for each
device you want to register. All further communication is done by read()'ing or
write()'ing "struct uhid_event" objects. Non-blocking operations are supported
-by setting O_NONBLOCK.
+by setting O_NONBLOCK::
-struct uhid_event {
+ struct uhid_event {
__u32 type;
union {
struct uhid_create2_req create2;
@@ -32,7 +33,7 @@ struct uhid_event {
struct uhid_input2_req input2;
...
} u;
-};
+ };
The "type" field contains the ID of the event. Depending on the ID different
payloads are sent. You must not split a single event across multiple read()'s or
@@ -86,31 +87,31 @@ the request was handled successfully. O_NONBLOCK does not affect write() as
writes are always handled immediately in a non-blocking fashion. Future requests
might make use of O_NONBLOCK, though.
- UHID_CREATE2:
+UHID_CREATE2:
This creates the internal HID device. No I/O is possible until you send this
event to the kernel. The payload is of type struct uhid_create2_req and
contains information about your device. You can start I/O now.
- UHID_DESTROY:
+UHID_DESTROY:
This destroys the internal HID device. No further I/O will be accepted. There
may still be pending messages that you can receive with read() but no further
UHID_INPUT events can be sent to the kernel.
You can create a new device by sending UHID_CREATE2 again. There is no need to
reopen the character device.
- UHID_INPUT2:
+UHID_INPUT2:
You must send UHID_CREATE2 before sending input to the kernel! This event
contains a data-payload. This is the raw data that you read from your device
on the interrupt channel. The kernel will parse the HID reports.
- UHID_GET_REPORT_REPLY:
+UHID_GET_REPORT_REPLY:
If you receive a UHID_GET_REPORT request you must answer with this request.
You must copy the "id" field from the request into the answer. Set the "err"
field to 0 if no error occurred or to EIO if an I/O error occurred.
If "err" is 0 then you should fill the buffer of the answer with the results
of the GET_REPORT request and set "size" correspondingly.
- UHID_SET_REPORT_REPLY:
+UHID_SET_REPORT_REPLY:
This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
"id" and "err" fields correctly.
@@ -120,16 +121,18 @@ read()
read() will return a queued output report. No reaction is required to any of
them but you should handle them according to your needs.
- UHID_START:
+UHID_START:
This is sent when the HID device is started. Consider this as an answer to
UHID_CREATE2. This is always the first event that is sent. Note that this
event might not be available immediately after write(UHID_CREATE2) returns.
Device drivers might required delayed setups.
This event contains a payload of type uhid_start_req. The "dev_flags" field
describes special behaviors of a device. The following flags are defined:
- UHID_DEV_NUMBERED_FEATURE_REPORTS:
- UHID_DEV_NUMBERED_OUTPUT_REPORTS:
- UHID_DEV_NUMBERED_INPUT_REPORTS:
+
+ - UHID_DEV_NUMBERED_FEATURE_REPORTS
+ - UHID_DEV_NUMBERED_OUTPUT_REPORTS
+ - UHID_DEV_NUMBERED_INPUT_REPORTS
+
Each of these flags defines whether a given report-type uses numbered
reports. If numbered reports are used for a type, all messages from
the kernel already have the report-number as prefix. Otherwise, no
@@ -137,33 +140,35 @@ them but you should handle them according to your needs.
For messages sent by user-space to the kernel, you must adjust the
prefixes according to these flags.
- UHID_STOP:
+UHID_STOP:
This is sent when the HID device is stopped. Consider this as an answer to
UHID_DESTROY.
+
If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
UHID_STOP event, this should usually be ignored. It means that the kernel
reloaded/changed the device driver loaded on your HID device (or some other
maintenance actions happened).
+
You can usually ignored any UHID_STOP events safely.
- UHID_OPEN:
+UHID_OPEN:
This is sent when the HID device is opened. That is, the data that the HID
device provides is read by some other process. You may ignore this event but
it is useful for power-management. As long as you haven't received this event
there is actually no other process that reads your data so there is no need to
send UHID_INPUT2 events to the kernel.
- UHID_CLOSE:
+UHID_CLOSE:
This is sent when there are no more processes which read the HID data. It is
the counterpart of UHID_OPEN and you may as well ignore this event.
- UHID_OUTPUT:
+UHID_OUTPUT:
This is sent if the HID device driver wants to send raw data to the I/O
device on the interrupt channel. You should read the payload and forward it to
the device. The payload is of type "struct uhid_output_req".
This may be received even though you haven't received UHID_OPEN, yet.
- UHID_GET_REPORT:
+UHID_GET_REPORT:
This event is sent if the kernel driver wants to perform a GET_REPORT request
on the control channeld as described in the HID specs. The report-type and
report-number are available in the payload.
@@ -177,11 +182,12 @@ them but you should handle them according to your needs.
timed out, the kernel will ignore the response silently. The "id" field is
never re-used, so conflicts cannot happen.
- UHID_SET_REPORT:
+UHID_SET_REPORT:
This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
send a SET_REPORT request to your hid device. Once it replies, you must tell
the kernel about it via UHID_SET_REPORT_REPLY.
The same restrictions as for UHID_GET_REPORT apply.
----------------------------------------------------
+
Written 2012, David Herrmann <dh.herrmann@gmail.com>
diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst
index 47f86a4bf16c..0eb61e67a7b7 100644
--- a/Documentation/input/input.rst
+++ b/Documentation/input/input.rst
@@ -188,7 +188,7 @@ LCDs and many other purposes.
The monitor and speaker controls should be easy to add to the hid/input
interface, but for the UPSs and LCDs it doesn't make much sense. For this,
-the hiddev interface was designed. See Documentation/hid/hiddev.txt
+the hiddev interface was designed. See Documentation/hid/hiddev.rst
for more information about it.
The usage of the usbhid module is very simple, it takes no parameters,
diff --git a/MAINTAINERS b/MAINTAINERS
index 8d39979e4091..969225e6bfce 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16383,7 +16383,7 @@ M: Benjamin Tissoires <benjamin.tissoires@redhat.com>
L: linux-usb@vger.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git
S: Maintained
-F: Documentation/hid/hiddev.txt
+F: Documentation/hid/hiddev.rst
F: drivers/hid/usbhid/
USB INTEL XHCI ROLE MUX DRIVER
--
2.21.0
^ permalink raw reply related
* [PATCH v1 29/31] docs: nvdimm: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Dan Williams, Vishal Verma, Dave Jiang,
Keith Busch, Ira Weiny, linux-nvdimm
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the mtd 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/nvdimm/{btt.txt => btt.rst} | 140 ++---
Documentation/nvdimm/index.rst | 12 +
.../nvdimm/{nvdimm.txt => nvdimm.rst} | 518 ++++++++++--------
.../nvdimm/{security.txt => security.rst} | 4 +-
drivers/nvdimm/Kconfig | 2 +-
5 files changed, 387 insertions(+), 289 deletions(-)
rename Documentation/nvdimm/{btt.txt => btt.rst} (71%)
create mode 100644 Documentation/nvdimm/index.rst
rename Documentation/nvdimm/{nvdimm.txt => nvdimm.rst} (60%)
rename Documentation/nvdimm/{security.txt => security.rst} (99%)
diff --git a/Documentation/nvdimm/btt.txt b/Documentation/nvdimm/btt.rst
similarity index 71%
rename from Documentation/nvdimm/btt.txt
rename to Documentation/nvdimm/btt.rst
index e293fb664924..2d8269f834bd 100644
--- a/Documentation/nvdimm/btt.txt
+++ b/Documentation/nvdimm/btt.rst
@@ -1,9 +1,10 @@
+=============================
BTT - Block Translation Table
=============================
1. Introduction
----------------
+===============
Persistent memory based storage is able to perform IO at byte (or more
accurately, cache line) granularity. However, we often want to expose such
@@ -25,7 +26,7 @@ provides atomic sector updates.
2. Static Layout
-----------------
+================
The underlying storage on which a BTT can be laid out is not limited in any way.
The BTT, however, splits the available space into chunks of up to 512 GiB,
@@ -33,43 +34,43 @@ called "Arenas".
Each arena follows the same layout for its metadata, and all references in an
arena are internal to it (with the exception of one field that points to the
-next arena). The following depicts the "On-disk" metadata layout:
+next arena). The following depicts the "On-disk" metadata layout::
- Backing Store +-------> Arena
-+---------------+ | +------------------+
-| | | | Arena info block |
-| Arena 0 +---+ | 4K |
-| 512G | +------------------+
-| | | |
-+---------------+ | |
-| | | |
-| Arena 1 | | Data Blocks |
-| 512G | | |
-| | | |
-+---------------+ | |
-| . | | |
-| . | | |
-| . | | |
-| | | |
-| | | |
-+---------------+ +------------------+
- | |
- | BTT Map |
- | |
- | |
- +------------------+
- | |
- | BTT Flog |
- | |
- +------------------+
- | Info block copy |
- | 4K |
- +------------------+
+ Backing Store +-------> Arena
+ +---------------+ | +------------------+
+ | | | | Arena info block |
+ | Arena 0 +---+ | 4K |
+ | 512G | +------------------+
+ | | | |
+ +---------------+ | |
+ | | | |
+ | Arena 1 | | Data Blocks |
+ | 512G | | |
+ | | | |
+ +---------------+ | |
+ | . | | |
+ | . | | |
+ | . | | |
+ | | | |
+ | | | |
+ +---------------+ +------------------+
+ | |
+ | BTT Map |
+ | |
+ | |
+ +------------------+
+ | |
+ | BTT Flog |
+ | |
+ +------------------+
+ | Info block copy |
+ | 4K |
+ +------------------+
3. Theory of Operation
-----------------------
+======================
a. The BTT Map
@@ -79,31 +80,37 @@ The map is a simple lookup/indirection table that maps an LBA to an internal
block. Each map entry is 32 bits. The two most significant bits are special
flags, and the remaining form the internal block number.
+======== =============================================================
Bit Description
-31 - 30 : Error and Zero flags - Used in the following way:
- Bit Description
- 31 30
- -----------------------------------------------------------------------
- 00 Initial state. Reads return zeroes; Premap = Postmap
- 01 Zero state: Reads return zeroes
- 10 Error state: Reads fail; Writes clear 'E' bit
- 11 Normal Block – has valid postmap
+======== =============================================================
+31 - 30 Error and Zero flags - Used in the following way:
+ == == ====================================================
+ 31 30 Description
+ == == ====================================================
+ 0 0 Initial state. Reads return zeroes; Premap = Postmap
+ 0 1 Zero state: Reads return zeroes
+ 1 0 Error state: Reads fail; Writes clear 'E' bit
+ 1 1 Normal Block – has valid postmap
+ == == ====================================================
-29 - 0 : Mappings to internal 'postmap' blocks
+29 - 0 Mappings to internal 'postmap' blocks
+======== =============================================================
Some of the terminology that will be subsequently used:
-External LBA : LBA as made visible to upper layers.
-ABA : Arena Block Address - Block offset/number within an arena
-Premap ABA : The block offset into an arena, which was decided upon by range
+============ ================================================================
+External LBA LBA as made visible to upper layers.
+ABA Arena Block Address - Block offset/number within an arena
+Premap ABA The block offset into an arena, which was decided upon by range
checking the External LBA
-Postmap ABA : The block number in the "Data Blocks" area obtained after
+Postmap ABA The block number in the "Data Blocks" area obtained after
indirection from the map
-nfree : The number of free blocks that are maintained at any given time.
+nfree The number of free blocks that are maintained at any given time.
This is the number of concurrent writes that can happen to the
arena.
+============ ================================================================
For example, after adding a BTT, we surface a disk of 1024G. We get a read for
@@ -121,19 +128,21 @@ i.e. Every write goes to a "free" block. A running list of free blocks is
maintained in the form of the BTT flog. 'Flog' is a combination of the words
"free list" and "log". The flog contains 'nfree' entries, and an entry contains:
-lba : The premap ABA that is being written to
-old_map : The old postmap ABA - after 'this' write completes, this will be a
+======== =====================================================================
+lba The premap ABA that is being written to
+old_map The old postmap ABA - after 'this' write completes, this will be a
free block.
-new_map : The new postmap ABA. The map will up updated to reflect this
+new_map The new postmap ABA. The map will up updated to reflect this
lba->postmap_aba mapping, but we log it here in case we have to
recover.
-seq : Sequence number to mark which of the 2 sections of this flog entry is
+seq Sequence number to mark which of the 2 sections of this flog entry is
valid/newest. It cycles between 01->10->11->01 (binary) under normal
operation, with 00 indicating an uninitialized state.
-lba' : alternate lba entry
-old_map': alternate old postmap entry
-new_map': alternate new postmap entry
-seq' : alternate sequence number.
+lba' alternate lba entry
+old_map' alternate old postmap entry
+new_map' alternate new postmap entry
+seq' alternate sequence number.
+======== =====================================================================
Each of the above fields is 32-bit, making one entry 32 bytes. Entries are also
padded to 64 bytes to avoid cache line sharing or aliasing. Flog updates are
@@ -147,8 +156,10 @@ c. The concept of lanes
While 'nfree' describes the number of concurrent IOs an arena can process
concurrently, 'nlanes' is the number of IOs the BTT device as a whole can
-process.
- nlanes = min(nfree, num_cpus)
+process::
+
+ nlanes = min(nfree, num_cpus)
+
A lane number is obtained at the start of any IO, and is used for indexing into
all the on-disk and in-memory data structures for the duration of the IO. If
there are more CPUs than the max number of available lanes, than lanes are
@@ -180,10 +191,10 @@ e. In-memory data structure: map locks
--------------------------------------
Consider a case where two writer threads are writing to the same LBA. There can
-be a race in the following sequence of steps:
+be a race in the following sequence of steps::
-free[lane] = map[premap_aba]
-map[premap_aba] = postmap_aba
+ free[lane] = map[premap_aba]
+ map[premap_aba] = postmap_aba
Both threads can update their respective free[lane] with the same old, freed
postmap_aba. This has made the layout inconsistent by losing a free entry, and
@@ -202,6 +213,7 @@ On startup, we analyze the BTT flog to create our list of free blocks. We walk
through all the entries, and for each lane, of the set of two possible
'sections', we always look at the most recent one only (based on the sequence
number). The reconstruction rules/steps are simple:
+
- Read map[log_entry.lba].
- If log_entry.new matches the map entry, then log_entry.old is free.
- If log_entry.new does not match the map entry, then log_entry.new is free.
@@ -228,7 +240,7 @@ Write:
1. Convert external LBA to Arena number + pre-map ABA
2. Get a lane (and take lane_lock)
3. Use lane to index into in-memory free list and obtain a new block, next flog
- index, next sequence number
+ index, next sequence number
4. Scan the RTT to check if free block is present, and spin/wait if it is.
5. Write data to this free block
6. Read map to get the existing post-map ABA entry for this pre-map ABA
@@ -245,6 +257,7 @@ Write:
An arena would be in an error state if any of the metadata is corrupted
irrecoverably, either due to a bug or a media error. The following conditions
indicate an error:
+
- Info block checksum does not match (and recovering from the copy also fails)
- All internal available blocks are not uniquely and entirely addressed by the
sum of mapped blocks and free blocks (from the BTT flog).
@@ -263,11 +276,10 @@ The BTT can be set up on any disk (namespace) exposed by the libnvdimm subsystem
(pmem, or blk mode). The easiest way to set up such a namespace is using the
'ndctl' utility [1]:
-For example, the ndctl command line to setup a btt with a 4k sector size is:
+For example, the ndctl command line to setup a btt with a 4k sector size is::
ndctl create-namespace -f -e namespace0.0 -m sector -l 4k
See ndctl create-namespace --help for more options.
[1]: https://github.com/pmem/ndctl
-
diff --git a/Documentation/nvdimm/index.rst b/Documentation/nvdimm/index.rst
new file mode 100644
index 000000000000..1a3402d3775e
--- /dev/null
+++ b/Documentation/nvdimm/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+===================================
+Non-Volatile Memory Device (NVDIMM)
+===================================
+
+.. toctree::
+ :maxdepth: 1
+
+ nvdimm
+ btt
+ security
diff --git a/Documentation/nvdimm/nvdimm.txt b/Documentation/nvdimm/nvdimm.rst
similarity index 60%
rename from Documentation/nvdimm/nvdimm.txt
rename to Documentation/nvdimm/nvdimm.rst
index 1669f626b037..08f855cbb4e6 100644
--- a/Documentation/nvdimm/nvdimm.txt
+++ b/Documentation/nvdimm/nvdimm.rst
@@ -1,8 +1,14 @@
- LIBNVDIMM: Non-Volatile Devices
- libnvdimm - kernel / libndctl - userspace helper library
- linux-nvdimm@lists.01.org
- v13
+===============================
+LIBNVDIMM: Non-Volatile Devices
+===============================
+libnvdimm - kernel / libndctl - userspace helper library
+
+linux-nvdimm@lists.01.org
+
+Version 13
+
+.. contents:
Glossary
Overview
@@ -40,49 +46,57 @@
Glossary
---------
-
-PMEM: A system-physical-address range where writes are persistent. A
-block device composed of PMEM is capable of DAX. A PMEM address range
-may span an interleave of several DIMMs.
-
-BLK: A set of one or more programmable memory mapped apertures provided
-by a DIMM to access its media. This indirection precludes the
-performance benefit of interleaving, but enables DIMM-bounded failure
-modes.
-
-DPA: DIMM Physical Address, is a DIMM-relative offset. With one DIMM in
-the system there would be a 1:1 system-physical-address:DPA association.
-Once more DIMMs are added a memory controller interleave must be
-decoded to determine the DPA associated with a given
-system-physical-address. BLK capacity always has a 1:1 relationship
-with a single-DIMM's DPA range.
-
-DAX: File system extensions to bypass the page cache and block layer to
-mmap persistent memory, from a PMEM block device, directly into a
-process address space.
-
-DSM: Device Specific Method: ACPI method to to control specific
-device - in this case the firmware.
-
-DCR: NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
-It defines a vendor-id, device-id, and interface format for a given DIMM.
-
-BTT: Block Translation Table: Persistent memory is byte addressable.
-Existing software may have an expectation that the power-fail-atomicity
-of writes is at least one sector, 512 bytes. The BTT is an indirection
-table with atomic update semantics to front a PMEM/BLK block device
-driver and present arbitrary atomic sector sizes.
-
-LABEL: Metadata stored on a DIMM device that partitions and identifies
-(persistently names) storage between PMEM and BLK. It also partitions
-BLK storage to host BTTs with different parameters per BLK-partition.
-Note that traditional partition tables, GPT/MBR, are layered on top of a
-BLK or PMEM device.
+========
+
+PMEM:
+ A system-physical-address range where writes are persistent. A
+ block device composed of PMEM is capable of DAX. A PMEM address range
+ may span an interleave of several DIMMs.
+
+BLK:
+ A set of one or more programmable memory mapped apertures provided
+ by a DIMM to access its media. This indirection precludes the
+ performance benefit of interleaving, but enables DIMM-bounded failure
+ modes.
+
+DPA:
+ DIMM Physical Address, is a DIMM-relative offset. With one DIMM in
+ the system there would be a 1:1 system-physical-address:DPA association.
+ Once more DIMMs are added a memory controller interleave must be
+ decoded to determine the DPA associated with a given
+ system-physical-address. BLK capacity always has a 1:1 relationship
+ with a single-DIMM's DPA range.
+
+DAX:
+ File system extensions to bypass the page cache and block layer to
+ mmap persistent memory, from a PMEM block device, directly into a
+ process address space.
+
+DSM:
+ Device Specific Method: ACPI method to to control specific
+ device - in this case the firmware.
+
+DCR:
+ NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
+ It defines a vendor-id, device-id, and interface format for a given DIMM.
+
+BTT:
+ Block Translation Table: Persistent memory is byte addressable.
+ Existing software may have an expectation that the power-fail-atomicity
+ of writes is at least one sector, 512 bytes. The BTT is an indirection
+ table with atomic update semantics to front a PMEM/BLK block device
+ driver and present arbitrary atomic sector sizes.
+
+LABEL:
+ Metadata stored on a DIMM device that partitions and identifies
+ (persistently names) storage between PMEM and BLK. It also partitions
+ BLK storage to host BTTs with different parameters per BLK-partition.
+ Note that traditional partition tables, GPT/MBR, are layered on top of a
+ BLK or PMEM device.
Overview
---------
+========
The LIBNVDIMM subsystem provides support for three types of NVDIMMs, namely,
PMEM, BLK, and NVDIMM devices that can simultaneously support both PMEM
@@ -96,19 +110,30 @@ accessible via BLK. When that occurs a LABEL is needed to reserve DPA
for exclusive access via one mode a time.
Supporting Documents
-ACPI 6: http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
-NVDIMM Namespace: http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
-DSM Interface Example: http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
-Driver Writer's Guide: http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
+--------------------
+
+ACPI 6:
+ http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
+NVDIMM Namespace:
+ http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
+DSM Interface Example:
+ http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
+Driver Writer's Guide:
+ http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
Git Trees
-LIBNVDIMM: https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
-LIBNDCTL: https://github.com/pmem/ndctl.git
-PMEM: https://github.com/01org/prd
+---------
+
+LIBNVDIMM:
+ https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
+LIBNDCTL:
+ https://github.com/pmem/ndctl.git
+PMEM:
+ https://github.com/01org/prd
LIBNVDIMM PMEM and BLK
-------------------
+======================
Prior to the arrival of the NFIT, non-volatile memory was described to a
system in various ad-hoc ways. Usually only the bare minimum was
@@ -122,38 +147,39 @@ For each NVDIMM access method (PMEM, BLK), LIBNVDIMM provides a block
device driver:
1. PMEM (nd_pmem.ko): Drives a system-physical-address range. This
- range is contiguous in system memory and may be interleaved (hardware
- memory controller striped) across multiple DIMMs. When interleaved the
- platform may optionally provide details of which DIMMs are participating
- in the interleave.
+ range is contiguous in system memory and may be interleaved (hardware
+ memory controller striped) across multiple DIMMs. When interleaved the
+ platform may optionally provide details of which DIMMs are participating
+ in the interleave.
- Note that while LIBNVDIMM describes system-physical-address ranges that may
- alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
- alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
- distinction. The different device-types are an implementation detail
- that userspace can exploit to implement policies like "only interface
- with address ranges from certain DIMMs". It is worth noting that when
- aliasing is present and a DIMM lacks a label, then no block device can
- be created by default as userspace needs to do at least one allocation
- of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once
- registered, can be immediately attached to nd_pmem.
+ Note that while LIBNVDIMM describes system-physical-address ranges that may
+ alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
+ alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
+ distinction. The different device-types are an implementation detail
+ that userspace can exploit to implement policies like "only interface
+ with address ranges from certain DIMMs". It is worth noting that when
+ aliasing is present and a DIMM lacks a label, then no block device can
+ be created by default as userspace needs to do at least one allocation
+ of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once
+ registered, can be immediately attached to nd_pmem.
2. BLK (nd_blk.ko): This driver performs I/O using a set of platform
- defined apertures. A set of apertures will access just one DIMM.
- Multiple windows (apertures) allow multiple concurrent accesses, much like
- tagged-command-queuing, and would likely be used by different threads or
- different CPUs.
+ defined apertures. A set of apertures will access just one DIMM.
+ Multiple windows (apertures) allow multiple concurrent accesses, much like
+ tagged-command-queuing, and would likely be used by different threads or
+ different CPUs.
- The NFIT specification defines a standard format for a BLK-aperture, but
- the spec also allows for vendor specific layouts, and non-NFIT BLK
- implementations may have other designs for BLK I/O. For this reason
- "nd_blk" calls back into platform-specific code to perform the I/O.
- One such implementation is defined in the "Driver Writer's Guide" and "DSM
- Interface Example".
+ The NFIT specification defines a standard format for a BLK-aperture, but
+ the spec also allows for vendor specific layouts, and non-NFIT BLK
+ implementations may have other designs for BLK I/O. For this reason
+ "nd_blk" calls back into platform-specific code to perform the I/O.
+
+ One such implementation is defined in the "Driver Writer's Guide" and "DSM
+ Interface Example".
Why BLK?
---------
+========
While PMEM provides direct byte-addressable CPU-load/store access to
NVDIMM storage, it does not provide the best system RAS (recovery,
@@ -162,12 +188,15 @@ system-physical-address address causes a CPU exception while an access
to a corrupted address through an BLK-aperture causes that block window
to raise an error status in a register. The latter is more aligned with
the standard error model that host-bus-adapter attached disks present.
+
Also, if an administrator ever wants to replace a memory it is easier to
service a system at DIMM module boundaries. Compare this to PMEM where
data could be interleaved in an opaque hardware specific manner across
several DIMMs.
PMEM vs BLK
+-----------
+
BLK-apertures solve these RAS problems, but their presence is also the
major contributing factor to the complexity of the ND subsystem. They
complicate the implementation because PMEM and BLK alias in DPA space.
@@ -185,13 +214,14 @@ carved into an arbitrary number of BLK devices with discontiguous
extents.
BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX
---------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One of the few
reasons to allow multiple BLK namespaces per REGION is so that each
BLK-namespace can be configured with a BTT with unique atomic sector
sizes. While a PMEM device can host a BTT the LABEL specification does
not provide for a sector size to be specified for a PMEM namespace.
+
This is due to the expectation that the primary usage model for PMEM is
via DAX, and the BTT is incompatible with DAX. However, for the cases
where an application or filesystem still needs atomic sector update
@@ -200,52 +230,52 @@ LIBNVDIMM/NDCTL: Block Translation Table "btt"
Example NVDIMM Platform
------------------------
+=======================
For the remainder of this document the following diagram will be
-referenced for any example sysfs layouts.
+referenced for any example sysfs layouts::
- (a) (b) DIMM BLK-REGION
- +-------------------+--------+--------+--------+
-+------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2
-| imc0 +--+- - - region0- - - +--------+ +--------+
-+--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3
- | +-------------------+--------v v--------+
-+--+---+ | |
-| cpu0 | region1
-+--+---+ | |
- | +----------------------------^ ^--------+
-+--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4
-| imc1 +--+----------------------------| +--------+
-+------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5
- +----------------------------+--------+--------+
+ (a) (b) DIMM BLK-REGION
+ +-------------------+--------+--------+--------+
+ +------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2
+ | imc0 +--+- - - region0- - - +--------+ +--------+
+ +--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3
+ | +-------------------+--------v v--------+
+ +--+---+ | |
+ | cpu0 | region1
+ +--+---+ | |
+ | +----------------------------^ ^--------+
+ +--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4
+ | imc1 +--+----------------------------| +--------+
+ +------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5
+ +----------------------------+--------+--------+
In this platform we have four DIMMs and two memory controllers in one
socket. Each unique interface (BLK or PMEM) to DPA space is identified
by a region device with a dynamically assigned id (REGION0 - REGION5).
1. The first portion of DIMM0 and DIMM1 are interleaved as REGION0. A
- single PMEM namespace is created in the REGION0-SPA-range that spans most
- of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
- interleaved system-physical-address range is reclaimed as BLK-aperture
- accessed space starting at DPA-offset (a) into each DIMM. In that
- reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
- REGION3 where "blk2.0" and "blk3.0" are just human readable names that
- could be set to any user-desired name in the LABEL.
+ single PMEM namespace is created in the REGION0-SPA-range that spans most
+ of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
+ interleaved system-physical-address range is reclaimed as BLK-aperture
+ accessed space starting at DPA-offset (a) into each DIMM. In that
+ reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
+ REGION3 where "blk2.0" and "blk3.0" are just human readable names that
+ could be set to any user-desired name in the LABEL.
2. In the last portion of DIMM0 and DIMM1 we have an interleaved
- system-physical-address range, REGION1, that spans those two DIMMs as
- well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace
- named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
- each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
- "blk5.0".
+ system-physical-address range, REGION1, that spans those two DIMMs as
+ well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace
+ named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
+ each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
+ "blk5.0".
3. The portion of DIMM2 and DIMM3 that do not participate in the REGION1
- interleaved system-physical-address range (i.e. the DPA address past
- offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
- Note, that this example shows that BLK-aperture namespaces don't need to
- be contiguous in DPA-space.
+ interleaved system-physical-address range (i.e. the DPA address past
+ offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
+ Note, that this example shows that BLK-aperture namespaces don't need to
+ be contiguous in DPA-space.
This bus is provided by the kernel under the device
/sys/devices/platform/nfit_test.0 when CONFIG_NFIT_TEST is enabled and
@@ -254,7 +284,7 @@ by a region device with a dynamically assigned id (REGION0 - REGION5).
LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API
-----------------------------------------------------
+========================================================
What follows is a description of the LIBNVDIMM sysfs layout and a
corresponding object hierarchy diagram as viewed through the LIBNDCTL
@@ -263,12 +293,18 @@ NVDIMM Platform which is also the LIBNVDIMM bus used in the LIBNDCTL unit
test.
LIBNDCTL: Context
+-----------------
+
Every API call in the LIBNDCTL library requires a context that holds the
logging parameters and other library instance state. The library is
based on the libabc template:
-https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
+
+ https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
LIBNDCTL: instantiate a new library context example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
struct ndctl_ctx *ctx;
@@ -278,7 +314,7 @@ LIBNDCTL: instantiate a new library context example
return NULL;
LIBNVDIMM/LIBNDCTL: Bus
--------------------
+-----------------------
A bus has a 1:1 relationship with an NFIT. The current expectation for
ACPI based systems is that there is only ever one platform-global NFIT.
@@ -288,9 +324,10 @@ we use this capability to test multiple NFIT configurations in the unit
test.
LIBNVDIMM: control class device in /sys/class
+---------------------------------------------
This character device accepts DSM messages to be passed to DIMM
-identified by its NFIT handle.
+identified by its NFIT handle::
/sys/class/nd/ndctl0
|-- dev
@@ -300,10 +337,15 @@ identified by its NFIT handle.
LIBNVDIMM: bus
+--------------
+
+::
struct nvdimm_bus *nvdimm_bus_register(struct device *parent,
struct nvdimm_bus_descriptor *nfit_desc);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- commands
|-- nd
@@ -324,7 +366,9 @@ LIBNVDIMM: bus
`-- wait_probe
LIBNDCTL: bus enumeration example
-Find the bus handle that describes the bus from Example NVDIMM Platform
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Find the bus handle that describes the bus from Example NVDIMM Platform::
static struct ndctl_bus *get_bus_by_provider(struct ndctl_ctx *ctx,
const char *provider)
@@ -342,7 +386,7 @@ Find the bus handle that describes the bus from Example NVDIMM Platform
LIBNVDIMM/LIBNDCTL: DIMM (NMEM)
----------------------------
+-------------------------------
The DIMM device provides a character device for sending commands to
hardware, and it is a container for LABELs. If the DIMM is defined by
@@ -355,11 +399,16 @@ Range Mapping Structure", and there is no requirement that they actually
be physical DIMMs, so we use a more generic name.
LIBNVDIMM: DIMM (NMEM)
+^^^^^^^^^^^^^^^^^^^^^^
+
+::
struct nvdimm *nvdimm_create(struct nvdimm_bus *nvdimm_bus, void *provider_data,
const struct attribute_group **groups, unsigned long flags,
unsigned long *dsm_mask);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- nmem0
| |-- available_slots
@@ -384,15 +433,20 @@ LIBNVDIMM: DIMM (NMEM)
LIBNDCTL: DIMM enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note, in this example we are assuming NFIT-defined DIMMs which are
identified by an "nfit_handle" a 32-bit value where:
-Bit 3:0 DIMM number within the memory channel
-Bit 7:4 memory channel number
-Bit 11:8 memory controller ID
-Bit 15:12 socket ID (within scope of a Node controller if node controller is present)
-Bit 27:16 Node Controller ID
-Bit 31:28 Reserved
+
+ - Bit 3:0 DIMM number within the memory channel
+ - Bit 7:4 memory channel number
+ - Bit 11:8 memory controller ID
+ - Bit 15:12 socket ID (within scope of a Node controller if node
+ controller is present)
+ - Bit 27:16 Node Controller ID
+ - Bit 31:28 Reserved
+
+::
static struct ndctl_dimm *get_dimm_by_handle(struct ndctl_bus *bus,
unsigned int handle)
@@ -413,7 +467,7 @@ Bit 31:28 Reserved
dimm = get_dimm_by_handle(bus, DIMM_HANDLE(0, 0, 0, 0, 0));
LIBNVDIMM/LIBNDCTL: Region
-----------------------
+--------------------------
A generic REGION device is registered for each PMEM range or BLK-aperture
set. Per the example there are 6 regions: 2 PMEM and 4 BLK-aperture
@@ -435,13 +489,15 @@ emits, "devtype" duplicates the DEVTYPE variable stored by udev at the
at the 'add' event, and finally, the optional "spa_index" is provided in
the case where the region is defined by a SPA.
-LIBNVDIMM: region
+LIBNVDIMM: region::
struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus,
struct nd_region_desc *ndr_desc);
struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus,
struct nd_region_desc *ndr_desc);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- region0
| |-- available_size
@@ -468,10 +524,11 @@ LIBNVDIMM: region
[..]
LIBNDCTL: region enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sample region retrieval routines based on NFIT-unique data like
"spa_index" (interleave set id) for PMEM and "nfit_handle" (dimm id) for
-BLK.
+BLK::
static struct ndctl_region *get_pmem_region_by_spa_index(struct ndctl_bus *bus,
unsigned int spa_index)
@@ -518,33 +575,33 @@ REGION name generic and expects userspace to always consider the
region-attributes for four reasons:
1. There are already more than two REGION and "namespace" types. For
- PMEM there are two subtypes. As mentioned previously we have PMEM where
- the constituent DIMM devices are known and anonymous PMEM. For BLK
- regions the NFIT specification already anticipates vendor specific
- implementations. The exact distinction of what a region contains is in
- the region-attributes not the region-name or the region-devtype.
+ PMEM there are two subtypes. As mentioned previously we have PMEM where
+ the constituent DIMM devices are known and anonymous PMEM. For BLK
+ regions the NFIT specification already anticipates vendor specific
+ implementations. The exact distinction of what a region contains is in
+ the region-attributes not the region-name or the region-devtype.
2. A region with zero child-namespaces is a possible configuration. For
- example, the NFIT allows for a DCR to be published without a
- corresponding BLK-aperture. This equates to a DIMM that can only accept
- control/configuration messages, but no i/o through a descendant block
- device. Again, this "type" is advertised in the attributes ('mappings'
- == 0) and the name does not tell you much.
+ example, the NFIT allows for a DCR to be published without a
+ corresponding BLK-aperture. This equates to a DIMM that can only accept
+ control/configuration messages, but no i/o through a descendant block
+ device. Again, this "type" is advertised in the attributes ('mappings'
+ == 0) and the name does not tell you much.
3. What if a third major interface type arises in the future? Outside
- of vendor specific implementations, it's not difficult to envision a
- third class of interface type beyond BLK and PMEM. With a generic name
- for the REGION level of the device-hierarchy old userspace
- implementations can still make sense of new kernel advertised
- region-types. Userspace can always rely on the generic region
- attributes like "mappings", "size", etc and the expected child devices
- named "namespace". This generic format of the device-model hierarchy
- allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
- future-proof.
+ of vendor specific implementations, it's not difficult to envision a
+ third class of interface type beyond BLK and PMEM. With a generic name
+ for the REGION level of the device-hierarchy old userspace
+ implementations can still make sense of new kernel advertised
+ region-types. Userspace can always rely on the generic region
+ attributes like "mappings", "size", etc and the expected child devices
+ named "namespace". This generic format of the device-model hierarchy
+ allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
+ future-proof.
4. There are more robust mechanisms for determining the major type of a
- region than a device name. See the next section, How Do I Determine the
- Major Type of a Region?
+ region than a device name. See the next section, How Do I Determine the
+ Major Type of a Region?
How Do I Determine the Major Type of a Region?
----------------------------------------------
@@ -553,7 +610,8 @@ Outside of the blanket recommendation of "use libndctl", or simply
looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
"nstype" integer attribute, here are some other options.
- 1. module alias lookup:
+1. module alias lookup
+^^^^^^^^^^^^^^^^^^^^^^
The whole point of region/namespace device type differentiation is to
decide which block-device driver will attach to a given LIBNVDIMM namespace.
@@ -569,28 +627,31 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
the resulting namespaces. The output from module resolution is more
accurate than a region-name or region-devtype.
- 2. udev:
+2. udev
+^^^^^^^
- The kernel "devtype" is registered in the udev database
- # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
- P: /devices/platform/nfit_test.0/ndbus0/region0
- E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
- E: DEVTYPE=nd_pmem
- E: MODALIAS=nd:t2
- E: SUBSYSTEM=nd
+ The kernel "devtype" is registered in the udev database::
- # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
- P: /devices/platform/nfit_test.0/ndbus0/region4
- E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
- E: DEVTYPE=nd_blk
- E: MODALIAS=nd:t3
- E: SUBSYSTEM=nd
+ # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
+ P: /devices/platform/nfit_test.0/ndbus0/region0
+ E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
+ E: DEVTYPE=nd_pmem
+ E: MODALIAS=nd:t2
+ E: SUBSYSTEM=nd
+
+ # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
+ P: /devices/platform/nfit_test.0/ndbus0/region4
+ E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
+ E: DEVTYPE=nd_blk
+ E: MODALIAS=nd:t3
+ E: SUBSYSTEM=nd
...and is available as a region attribute, but keep in mind that the
"devtype" does not indicate sub-type variations and scripts should
really be understanding the other attributes.
- 3. type specific attributes:
+3. type specific attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
As it currently stands a BLK-aperture region will never have a
"nfit/spa_index" attribute, but neither will a non-NFIT PMEM region. A
@@ -600,7 +661,7 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
LIBNVDIMM/LIBNDCTL: Namespace
--------------------------
+-----------------------------
A REGION, after resolving DPA aliasing and LABEL specified boundaries,
surfaces one or more "namespace" devices. The arrival of a "namespace"
@@ -608,12 +669,14 @@ device currently triggers either the nd_blk or nd_pmem driver to load
and register a disk/block device.
LIBNVDIMM: namespace
+^^^^^^^^^^^^^^^^^^^^
+
Here is a sample layout from the three major types of NAMESPACE where
namespace0.0 represents DIMM-info-backed PMEM (note that it has a 'uuid'
attribute), namespace2.0 represents a BLK namespace (note it has a
'sector_size' attribute) that, and namespace6.0 represents an anonymous
PMEM namespace (note that has no 'uuid' attribute due to not support a
-LABEL).
+LABEL)::
/sys/devices/platform/nfit_test.0/ndbus0/region0/namespace0.0
|-- alt_name
@@ -656,76 +719,84 @@ LABEL).
`-- uevent
LIBNDCTL: namespace enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Namespaces are indexed relative to their parent region, example below.
These indexes are mostly static from boot to boot, but subsystem makes
no guarantees in this regard. For a static namespace identifier use its
'uuid' attribute.
-static struct ndctl_namespace *get_namespace_by_id(struct ndctl_region *region,
- unsigned int id)
-{
- struct ndctl_namespace *ndns;
+::
- ndctl_namespace_foreach(region, ndns)
- if (ndctl_namespace_get_id(ndns) == id)
- return ndns;
+ static struct ndctl_namespace
+ *get_namespace_by_id(struct ndctl_region *region, unsigned int id)
+ {
+ struct ndctl_namespace *ndns;
- return NULL;
-}
+ ndctl_namespace_foreach(region, ndns)
+ if (ndctl_namespace_get_id(ndns) == id)
+ return ndns;
+
+ return NULL;
+ }
LIBNDCTL: namespace creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Idle namespaces are automatically created by the kernel if a given
region has enough available capacity to create a new namespace.
Namespace instantiation involves finding an idle namespace and
configuring it. For the most part the setting of namespace attributes
can occur in any order, the only constraint is that 'uuid' must be set
before 'size'. This enables the kernel to track DPA allocations
-internally with a static identifier.
+internally with a static identifier::
-static int configure_namespace(struct ndctl_region *region,
- struct ndctl_namespace *ndns,
- struct namespace_parameters *parameters)
-{
- char devname[50];
+ static int configure_namespace(struct ndctl_region *region,
+ struct ndctl_namespace *ndns,
+ struct namespace_parameters *parameters)
+ {
+ char devname[50];
- snprintf(devname, sizeof(devname), "namespace%d.%d",
- ndctl_region_get_id(region), paramaters->id);
+ snprintf(devname, sizeof(devname), "namespace%d.%d",
+ ndctl_region_get_id(region), paramaters->id);
- ndctl_namespace_set_alt_name(ndns, devname);
- /* 'uuid' must be set prior to setting size! */
- ndctl_namespace_set_uuid(ndns, paramaters->uuid);
- ndctl_namespace_set_size(ndns, paramaters->size);
- /* unlike pmem namespaces, blk namespaces have a sector size */
- if (parameters->lbasize)
- ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
- ndctl_namespace_enable(ndns);
-}
+ ndctl_namespace_set_alt_name(ndns, devname);
+ /* 'uuid' must be set prior to setting size! */
+ ndctl_namespace_set_uuid(ndns, paramaters->uuid);
+ ndctl_namespace_set_size(ndns, paramaters->size);
+ /* unlike pmem namespaces, blk namespaces have a sector size */
+ if (parameters->lbasize)
+ ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
+ ndctl_namespace_enable(ndns);
+ }
Why the Term "namespace"?
+^^^^^^^^^^^^^^^^^^^^^^^^^
1. Why not "volume" for instance? "volume" ran the risk of confusing
- ND (libnvdimm subsystem) to a volume manager like device-mapper.
+ ND (libnvdimm subsystem) to a volume manager like device-mapper.
2. The term originated to describe the sub-devices that can be created
- within a NVME controller (see the nvme specification:
- http://www.nvmexpress.org/specifications/), and NFIT namespaces are
- meant to parallel the capabilities and configurability of
- NVME-namespaces.
+ within a NVME controller (see the nvme specification:
+ http://www.nvmexpress.org/specifications/), and NFIT namespaces are
+ meant to parallel the capabilities and configurability of
+ NVME-namespaces.
LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
----------------------------------------------
+-------------------------------------------------
A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked
block device driver that fronts either the whole block device or a
partition of a block device emitted by either a PMEM or BLK NAMESPACE.
LIBNVDIMM: btt layout
+^^^^^^^^^^^^^^^^^^^^^
+
Every region will start out with at least one BTT device which is the
seed device. To activate it set the "namespace", "uuid", and
"sector_size" attributes and then bind the device to the nd_pmem or
-nd_blk driver depending on the region type.
+nd_blk driver depending on the region type::
/sys/devices/platform/nfit_test.1/ndbus0/region0/btt0/
|-- namespace
@@ -739,10 +810,12 @@ nd_blk driver depending on the region type.
`-- uuid
LIBNDCTL: btt creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Similar to namespaces an idle BTT device is automatically created per
region. Each time this "seed" btt device is configured and enabled a new
seed is created. Creating a BTT configuration involves two steps of
-finding and idle BTT and assigning it to consume a PMEM or BLK namespace.
+finding and idle BTT and assigning it to consume a PMEM or BLK namespace::
static struct ndctl_btt *get_idle_btt(struct ndctl_region *region)
{
@@ -787,29 +860,28 @@ Summary LIBNDCTL Diagram
------------------------
For the given example above, here is the view of the objects as seen by the
-LIBNDCTL API:
- +---+
- |CTX| +---------+ +--------------+ +---------------+
- +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
- | | +---------+ +--------------+ +---------------+
-+-------+ | | +---------+ +--------------+ +---------------+
-| DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
-+-------+ | | | +---------+ +--------------+ +---------------+
-| DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+
-+-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" |
-| DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+
-+-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 |
-| DIMM3 <-+ | +--------------+ +----------------------+
-+-------+ | +---------+ +--------------+ +---------------+
- +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" |
- | +---------+ | +--------------+ +----------------------+
- | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 |
- | +--------------+ +----------------------+
- | +---------+ +--------------+ +---------------+
- +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" |
- | +---------+ +--------------+ +---------------+
- | +---------+ +--------------+ +----------------------+
- +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 |
- +---------+ +--------------+ +---------------+------+
-
+LIBNDCTL API::
+ +---+
+ |CTX| +---------+ +--------------+ +---------------+
+ +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
+ | | +---------+ +--------------+ +---------------+
+ +-------+ | | +---------+ +--------------+ +---------------+
+ | DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
+ +-------+ | | | +---------+ +--------------+ +---------------+
+ | DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+
+ +-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" |
+ | DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+
+ +-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 |
+ | DIMM3 <-+ | +--------------+ +----------------------+
+ +-------+ | +---------+ +--------------+ +---------------+
+ +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" |
+ | +---------+ | +--------------+ +----------------------+
+ | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 |
+ | +--------------+ +----------------------+
+ | +---------+ +--------------+ +---------------+
+ +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" |
+ | +---------+ +--------------+ +---------------+
+ | +---------+ +--------------+ +----------------------+
+ +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 |
+ +---------+ +--------------+ +---------------+------+
diff --git a/Documentation/nvdimm/security.txt b/Documentation/nvdimm/security.rst
similarity index 99%
rename from Documentation/nvdimm/security.txt
rename to Documentation/nvdimm/security.rst
index 4c36c05ca98e..ad9dea099b34 100644
--- a/Documentation/nvdimm/security.txt
+++ b/Documentation/nvdimm/security.rst
@@ -1,4 +1,5 @@
-NVDIMM SECURITY
+===============
+NVDIMM Security
===============
1. Introduction
@@ -138,4 +139,5 @@ This command is only available when the master security is enabled, indicated
by the extended security status.
[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
+
[2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
diff --git a/drivers/nvdimm/Kconfig b/drivers/nvdimm/Kconfig
index 54500798f23a..e89c1c332407 100644
--- a/drivers/nvdimm/Kconfig
+++ b/drivers/nvdimm/Kconfig
@@ -33,7 +33,7 @@ config BLK_DEV_PMEM
Documentation/admin-guide/kernel-parameters.rst). This driver converts
these persistent memory ranges into block devices that are
capable of DAX (direct-access) file system mappings. See
- Documentation/nvdimm/nvdimm.txt for more details.
+ Documentation/nvdimm/nvdimm.rst for more details.
Say Y if you want to use an NVDIMM
--
2.21.0
^ permalink raw reply related
* [PATCH v1 30/31] docs: xtensa: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Chris Zankel, Max Filippov, linux-xtensa
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the xtensa 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>
---
.../xtensa/{atomctl.txt => atomctl.rst} | 13 +-
.../xtensa/{booting.txt => booting.rst} | 5 +-
Documentation/xtensa/index.rst | 12 ++
Documentation/xtensa/mmu.rst | 195 ++++++++++++++++++
Documentation/xtensa/mmu.txt | 189 -----------------
arch/xtensa/include/asm/initialize_mmu.h | 2 +-
6 files changed, 222 insertions(+), 194 deletions(-)
rename Documentation/xtensa/{atomctl.txt => atomctl.rst} (81%)
rename Documentation/xtensa/{booting.txt => booting.rst} (91%)
create mode 100644 Documentation/xtensa/index.rst
create mode 100644 Documentation/xtensa/mmu.rst
delete mode 100644 Documentation/xtensa/mmu.txt
diff --git a/Documentation/xtensa/atomctl.txt b/Documentation/xtensa/atomctl.rst
similarity index 81%
rename from Documentation/xtensa/atomctl.txt
rename to Documentation/xtensa/atomctl.rst
index 1da783ac200c..1ecbd0ba9a2e 100644
--- a/Documentation/xtensa/atomctl.txt
+++ b/Documentation/xtensa/atomctl.rst
@@ -1,3 +1,7 @@
+===========================================
+Atomic Operation Control (ATOMCTL) Register
+===========================================
+
We Have Atomic Operation Control (ATOMCTL) Register.
This register determines the effect of using a S32C1I instruction
with various combinations of:
@@ -8,7 +12,7 @@ with various combinations of:
2. With and without An Intelligent Memory Controller which
can do Atomic Transactions itself.
-The Core comes up with a default value of for the three types of cache ops:
+The Core comes up with a default value of for the three types of cache ops::
0x28: (WB: Internal, WT: Internal, BY:Exception)
@@ -30,15 +34,18 @@ CUSTOMER-WARNING:
Developers might find using RCW in Bypass mode convenient when testing
with the cache being bypassed; for example studying cache alias problems.
-See Section 4.3.12.4 of ISA; Bits:
+See Section 4.3.12.4 of ISA; Bits::
WB WT BY
5 4 | 3 2 | 1 0
+
+========= ================== ================== ===============
2 Bit
Field
Values WB - Write Back WT - Write Thru BY - Bypass
---------- --------------- ----------------- ----------------
+========= ================== ================== ===============
0 Exception Exception Exception
1 RCW Transaction RCW Transaction RCW Transaction
2 Internal Operation Internal Operation Reserved
3 Reserved Reserved Reserved
+========= ================== ================== ===============
diff --git a/Documentation/xtensa/booting.txt b/Documentation/xtensa/booting.rst
similarity index 91%
rename from Documentation/xtensa/booting.txt
rename to Documentation/xtensa/booting.rst
index 402b33a2619f..e1b83707e5b6 100644
--- a/Documentation/xtensa/booting.txt
+++ b/Documentation/xtensa/booting.rst
@@ -1,10 +1,13 @@
-Passing boot parameters to the kernel.
+=====================================
+Passing boot parameters to the kernel
+=====================================
Boot parameters are represented as a TLV list in the memory. Please see
arch/xtensa/include/asm/bootparam.h for definition of the bp_tag structure and
tag value constants. First entry in the list must have type BP_TAG_FIRST, last
entry must have type BP_TAG_LAST. The address of the first list entry is
passed to the kernel in the register a2. The address type depends on MMU type:
+
- For configurations without MMU, with region protection or with MPU the
address must be the physical address.
- For configurations with region translarion MMU or with MMUv3 and CONFIG_MMU=n
diff --git a/Documentation/xtensa/index.rst b/Documentation/xtensa/index.rst
new file mode 100644
index 000000000000..5a24e365e35f
--- /dev/null
+++ b/Documentation/xtensa/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+===================
+Xtensa Architecture
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ atomctl
+ booting
+ mmu
diff --git a/Documentation/xtensa/mmu.rst b/Documentation/xtensa/mmu.rst
new file mode 100644
index 000000000000..e52a12960fdc
--- /dev/null
+++ b/Documentation/xtensa/mmu.rst
@@ -0,0 +1,195 @@
+=============================
+MMUv3 initialization sequence
+=============================
+
+The code in the initialize_mmu macro sets up MMUv3 memory mapping
+identically to MMUv2 fixed memory mapping. Depending on
+CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is
+located in addresses it was linked for (symbol undefined), or not
+(symbol defined), so it needs to be position-independent.
+
+The code has the following assumptions:
+
+ - This code fragment is run only on an MMU v3.
+ - TLBs are in their reset state.
+ - ITLBCFG and DTLBCFG are zero (reset state).
+ - RASID is 0x04030201 (reset state).
+ - PS.RING is zero (reset state).
+ - LITBASE is zero (reset state, PC-relative literals); required to be PIC.
+
+TLB setup proceeds along the following steps.
+
+ Legend:
+
+ - VA = virtual address (two upper nibbles of it);
+ - PA = physical address (two upper nibbles of it);
+ - pc = physical range that contains this code;
+
+After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff
+or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below
+0x40000000 or above. That address corresponds to next instruction to execute
+in this code. After step 4, we jump to intended (linked) address of this code.
+The scheme below assumes that the kernel is loaded below 0x40000000.
+
+ ====== ===== ===== ===== ===== ====== ===== =====
+ - Step0 Step1 Step2 Step3 Step4 Step5
+
+ VA PA PA PA PA VA PA PA
+ ====== ===== ===== ===== ===== ====== ===== =====
+ E0..FF -> E0 -> E0 -> E0 F0..FF -> F0 -> F0
+ C0..DF -> C0 -> C0 -> C0 E0..EF -> F0 -> F0
+ A0..BF -> A0 -> A0 -> A0 D8..DF -> 00 -> 00
+ 80..9F -> 80 -> 80 -> 80 D0..D7 -> 00 -> 00
+ 60..7F -> 60 -> 60 -> 60
+ 40..5F -> 40 -> pc -> pc 40..5F -> pc
+ 20..3F -> 20 -> 20 -> 20
+ 00..1F -> 00 -> 00 -> 00
+ ====== ===== ===== ===== ===== ====== ===== =====
+
+The default location of IO peripherals is above 0xf0000000. This may be changed
+using a "ranges" property in a device tree simple-bus node. See the Devicetree
+Specification, section 4.5 for details on the syntax and semantics of
+simple-bus nodes. The following limitations apply:
+
+1. Only top level simple-bus nodes are considered
+
+2. Only one (first) simple-bus node is considered
+
+3. Empty "ranges" properties are not supported
+
+4. Only the first triplet in the "ranges" property is considered
+
+5. The parent-bus-address value is rounded down to the nearest 256MB boundary
+
+6. The IO area covers the entire 256MB segment of parent-bus-address; the
+ "ranges" triplet length field is ignored
+
+
+MMUv3 address space layouts.
+============================
+
+Default MMUv2-compatible layout::
+
+ Symbol VADDR Size
+ +------------------+
+ | Userspace | 0x00000000 TASK_SIZE
+ +------------------+ 0x40000000
+ +------------------+
+ | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
+ +------------------+
+ | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
+ +------------------+ 0x8e400000
+ +------------------+
+ | VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB
+ +------------------+ VMALLOC_END
+ | Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE
+ | remap area 1 |
+ +------------------+
+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
+ | remap area 2 |
+ +------------------+
+ +------------------+
+ | KMAP area | PKMAP_BASE PTRS_PER_PTE *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ | | (4MB * DCACHE_N_COLORS)
+ +------------------+
+ | Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
+ | | NR_CPUS *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ +------------------+ FIXADDR_TOP 0xcffff000
+ +------------------+
+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xd0000000 128MB
+ +------------------+
+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xd8000000 128MB
+ +------------------+
+ | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
+ +------------------+
+ | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
+ +------------------+
+
+
+256MB cached + 256MB uncached layout::
+
+ Symbol VADDR Size
+ +------------------+
+ | Userspace | 0x00000000 TASK_SIZE
+ +------------------+ 0x40000000
+ +------------------+
+ | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
+ +------------------+
+ | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
+ +------------------+ 0x8e400000
+ +------------------+
+ | VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB
+ +------------------+ VMALLOC_END
+ | Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE
+ | remap area 1 |
+ +------------------+
+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
+ | remap area 2 |
+ +------------------+
+ +------------------+
+ | KMAP area | PKMAP_BASE PTRS_PER_PTE *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ | | (4MB * DCACHE_N_COLORS)
+ +------------------+
+ | Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
+ | | NR_CPUS *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ +------------------+ FIXADDR_TOP 0xaffff000
+ +------------------+
+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xb0000000 256MB
+ +------------------+
+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 256MB
+ +------------------+
+ +------------------+
+ | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
+ +------------------+
+ | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
+ +------------------+
+
+
+512MB cached + 512MB uncached layout::
+
+ Symbol VADDR Size
+ +------------------+
+ | Userspace | 0x00000000 TASK_SIZE
+ +------------------+ 0x40000000
+ +------------------+
+ | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
+ +------------------+
+ | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
+ +------------------+ 0x8e400000
+ +------------------+
+ | VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB
+ +------------------+ VMALLOC_END
+ | Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE
+ | remap area 1 |
+ +------------------+
+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
+ | remap area 2 |
+ +------------------+
+ +------------------+
+ | KMAP area | PKMAP_BASE PTRS_PER_PTE *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ | | (4MB * DCACHE_N_COLORS)
+ +------------------+
+ | Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
+ | | NR_CPUS *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ +------------------+ FIXADDR_TOP 0x9ffff000
+ +------------------+
+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xa0000000 512MB
+ +------------------+
+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 512MB
+ +------------------+
+ | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
+ +------------------+
+ | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
+ +------------------+
diff --git a/Documentation/xtensa/mmu.txt b/Documentation/xtensa/mmu.txt
deleted file mode 100644
index 318114de63f3..000000000000
--- a/Documentation/xtensa/mmu.txt
+++ /dev/null
@@ -1,189 +0,0 @@
-MMUv3 initialization sequence.
-
-The code in the initialize_mmu macro sets up MMUv3 memory mapping
-identically to MMUv2 fixed memory mapping. Depending on
-CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is
-located in addresses it was linked for (symbol undefined), or not
-(symbol defined), so it needs to be position-independent.
-
-The code has the following assumptions:
- This code fragment is run only on an MMU v3.
- TLBs are in their reset state.
- ITLBCFG and DTLBCFG are zero (reset state).
- RASID is 0x04030201 (reset state).
- PS.RING is zero (reset state).
- LITBASE is zero (reset state, PC-relative literals); required to be PIC.
-
-TLB setup proceeds along the following steps.
-
- Legend:
- VA = virtual address (two upper nibbles of it);
- PA = physical address (two upper nibbles of it);
- pc = physical range that contains this code;
-
-After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff
-or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below
-0x40000000 or above. That address corresponds to next instruction to execute
-in this code. After step 4, we jump to intended (linked) address of this code.
-The scheme below assumes that the kernel is loaded below 0x40000000.
-
- Step0 Step1 Step2 Step3 Step4 Step5
- ===== ===== ===== ===== ===== =====
- VA PA PA PA PA VA PA PA
- ------ -- -- -- -- ------ -- --
- E0..FF -> E0 -> E0 -> E0 F0..FF -> F0 -> F0
- C0..DF -> C0 -> C0 -> C0 E0..EF -> F0 -> F0
- A0..BF -> A0 -> A0 -> A0 D8..DF -> 00 -> 00
- 80..9F -> 80 -> 80 -> 80 D0..D7 -> 00 -> 00
- 60..7F -> 60 -> 60 -> 60
- 40..5F -> 40 -> pc -> pc 40..5F -> pc
- 20..3F -> 20 -> 20 -> 20
- 00..1F -> 00 -> 00 -> 00
-
-The default location of IO peripherals is above 0xf0000000. This may be changed
-using a "ranges" property in a device tree simple-bus node. See the Devicetree
-Specification, section 4.5 for details on the syntax and semantics of
-simple-bus nodes. The following limitations apply:
-
-1. Only top level simple-bus nodes are considered
-
-2. Only one (first) simple-bus node is considered
-
-3. Empty "ranges" properties are not supported
-
-4. Only the first triplet in the "ranges" property is considered
-
-5. The parent-bus-address value is rounded down to the nearest 256MB boundary
-
-6. The IO area covers the entire 256MB segment of parent-bus-address; the
- "ranges" triplet length field is ignored
-
-
-MMUv3 address space layouts.
-============================
-
-Default MMUv2-compatible layout.
-
- Symbol VADDR Size
-+------------------+
-| Userspace | 0x00000000 TASK_SIZE
-+------------------+ 0x40000000
-+------------------+
-| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
-+------------------+ 0x8e400000
-+------------------+
-| VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB
-+------------------+ VMALLOC_END
-| Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE
-| remap area 1 |
-+------------------+
-| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
-| remap area 2 |
-+------------------+
-+------------------+
-| KMAP area | PKMAP_BASE PTRS_PER_PTE *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-| | (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
-| | NR_CPUS *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-+------------------+ FIXADDR_TOP 0xcffff000
-+------------------+
-| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xd0000000 128MB
-+------------------+
-| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xd8000000 128MB
-+------------------+
-| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
-+------------------+
-| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
-+------------------+
-
-
-256MB cached + 256MB uncached layout.
-
- Symbol VADDR Size
-+------------------+
-| Userspace | 0x00000000 TASK_SIZE
-+------------------+ 0x40000000
-+------------------+
-| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
-+------------------+ 0x8e400000
-+------------------+
-| VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB
-+------------------+ VMALLOC_END
-| Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE
-| remap area 1 |
-+------------------+
-| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
-| remap area 2 |
-+------------------+
-+------------------+
-| KMAP area | PKMAP_BASE PTRS_PER_PTE *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-| | (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
-| | NR_CPUS *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-+------------------+ FIXADDR_TOP 0xaffff000
-+------------------+
-| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xb0000000 256MB
-+------------------+
-| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 256MB
-+------------------+
-+------------------+
-| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
-+------------------+
-| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
-+------------------+
-
-
-512MB cached + 512MB uncached layout.
-
- Symbol VADDR Size
-+------------------+
-| Userspace | 0x00000000 TASK_SIZE
-+------------------+ 0x40000000
-+------------------+
-| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
-+------------------+ 0x8e400000
-+------------------+
-| VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB
-+------------------+ VMALLOC_END
-| Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE
-| remap area 1 |
-+------------------+
-| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
-| remap area 2 |
-+------------------+
-+------------------+
-| KMAP area | PKMAP_BASE PTRS_PER_PTE *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-| | (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
-| | NR_CPUS *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-+------------------+ FIXADDR_TOP 0x9ffff000
-+------------------+
-| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xa0000000 512MB
-+------------------+
-| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 512MB
-+------------------+
-| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
-+------------------+
-| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
-+------------------+
diff --git a/arch/xtensa/include/asm/initialize_mmu.h b/arch/xtensa/include/asm/initialize_mmu.h
index 323d05789159..3b054d2bede0 100644
--- a/arch/xtensa/include/asm/initialize_mmu.h
+++ b/arch/xtensa/include/asm/initialize_mmu.h
@@ -42,7 +42,7 @@
#if XCHAL_HAVE_S32C1I && (XCHAL_HW_MIN_VERSION >= XTENSA_HWVERSION_RC_2009_0)
/*
* We Have Atomic Operation Control (ATOMCTL) Register; Initialize it.
- * For details see Documentation/xtensa/atomctl.txt
+ * For details see Documentation/xtensa/atomctl.rst
*/
#if XCHAL_DCACHE_IS_COHERENT
movi a3, 0x25 /* For SMP/MX -- internal for writeback,
--
2.21.0
^ permalink raw reply related
* [PATCH v1 23/31] docs: laptops: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mattia Dongili, Arnd Bergmann,
Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
platform-driver-x86
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the laptops 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/ABI/testing/sysfs-block-device | 2 +-
.../ABI/testing/sysfs-platform-asus-laptop | 2 +-
.../admin-guide/kernel-parameters.txt | 2 +-
.../{asus-laptop.txt => asus-laptop.rst} | 92 ++--
...otection.txt => disk-shock-protection.rst} | 32 +-
Documentation/laptops/index.rst | 17 +
.../{laptop-mode.txt => laptop-mode.rst} | 509 +++++++++---------
.../{sony-laptop.txt => sony-laptop.rst} | 58 +-
.../laptops/{sonypi.txt => sonypi.rst} | 28 +-
.../{thinkpad-acpi.txt => thinkpad-acpi.rst} | 363 ++++++++-----
.../{toshiba_haps.txt => toshiba_haps.rst} | 47 +-
Documentation/sysctl/vm.txt | 4 +-
MAINTAINERS | 2 +-
drivers/char/Kconfig | 2 +-
drivers/platform/x86/Kconfig | 4 +-
15 files changed, 660 insertions(+), 504 deletions(-)
rename Documentation/laptops/{asus-laptop.txt => asus-laptop.rst} (84%)
rename Documentation/laptops/{disk-shock-protection.txt => disk-shock-protection.rst} (91%)
create mode 100644 Documentation/laptops/index.rst
rename Documentation/laptops/{laptop-mode.txt => laptop-mode.rst} (62%)
rename Documentation/laptops/{sony-laptop.txt => sony-laptop.rst} (85%)
rename Documentation/laptops/{sonypi.txt => sonypi.rst} (87%)
rename Documentation/laptops/{thinkpad-acpi.txt => thinkpad-acpi.rst} (89%)
rename Documentation/laptops/{toshiba_haps.txt => toshiba_haps.rst} (60%)
diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 82ef6eab042d..0d57bbb4fddc 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.txt
+ Documentation/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 cd9d667c3da2..d67fa4bafa70 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.txt
+ The DDD table can be found in Documentation/laptops/asus-laptop.rst
What: /sys/devices/platform/asus_laptop/bluetooth
Date: January 2007
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 3faf37b8b001..7abe677f8c5e 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.txt
+ See Documentation/laptops/sonypi.rst
spectre_v2= [X86] Control mitigation of Spectre variant 2
(indirect branch speculation) vulnerability.
diff --git a/Documentation/laptops/asus-laptop.txt b/Documentation/laptops/asus-laptop.rst
similarity index 84%
rename from Documentation/laptops/asus-laptop.txt
rename to Documentation/laptops/asus-laptop.rst
index 5f2858712aa0..95176321a25a 100644
--- a/Documentation/laptops/asus-laptop.txt
+++ b/Documentation/laptops/asus-laptop.rst
@@ -1,6 +1,9 @@
+==================
Asus Laptop Extras
+==================
Version 0.1
+
August 6, 2009
Corentin Chary <corentincj@iksaif.net>
@@ -10,11 +13,12 @@ http://acpi4asus.sf.net/
It may also support some MEDION, JVC or VICTOR laptops (such as MEDION 9675 or
VICTOR XP7210 for example). It makes all the extra buttons generate input
events (like keyboards).
+
On some models adds support for changing the display brightness and output,
switching the LCD backlight on and off, and most importantly, allows you to
blink those fancy LEDs intended for reporting mail and wireless status.
-This driver supercedes the old asus_acpi driver.
+This driver supersedes the old asus_acpi driver.
Requirements
------------
@@ -49,7 +53,7 @@ Usage
see some lines like this :
Asus Laptop Extras version 0.42
- L2D model detected.
+ - L2D model detected.
If it is not the output you have on your laptop, send it (and the laptop's
DSDT) to me.
@@ -68,9 +72,12 @@ Usage
LEDs
----
- You can modify LEDs be echoing values to /sys/class/leds/asus::*/brightness :
+ You can modify LEDs be echoing values to `/sys/class/leds/asus/*/brightness`::
+
echo 1 > /sys/class/leds/asus::mail/brightness
+
will switch the mail LED on.
+
You can also know if they are on/off by reading their content and use
kernel triggers like disk-activity or heartbeat.
@@ -81,7 +88,7 @@ Backlight
/sys/class/backlight/asus-laptop/. Brightness Values are between 0 and 15.
Wireless devices
----------------
+----------------
You can turn the internal Bluetooth adapter on/off with the bluetooth entry
(only on models with Bluetooth). This usually controls the associated LED.
@@ -93,18 +100,20 @@ Display switching
Note: the display switching code is currently considered EXPERIMENTAL.
Switching works for the following models:
- L3800C
- A2500H
- L5800C
- M5200N
- W1000N (albeit with some glitches)
- M6700R
- A6JC
- F3J
+
+ - L3800C
+ - A2500H
+ - L5800C
+ - M5200N
+ - W1000N (albeit with some glitches)
+ - M6700R
+ - A6JC
+ - F3J
Switching doesn't work for the following:
- M3700N
- L2X00D (locks the laptop under certain conditions)
+
+ - M3700N
+ - L2X00D (locks the laptop under certain conditions)
To switch the displays, echo values from 0 to 15 to
/sys/devices/platform/asus-laptop/display. The significance of those values
@@ -113,48 +122,51 @@ Display switching
+-------+-----+-----+-----+-----+-----+
| Bin | Val | DVI | TV | CRT | LCD |
+-------+-----+-----+-----+-----+-----+
- + 0000 + 0 + + + + +
+ | 0000 | 0 | | | | |
+-------+-----+-----+-----+-----+-----+
- + 0001 + 1 + + + + X +
+ | 0001 | 1 | | | | X |
+-------+-----+-----+-----+-----+-----+
- + 0010 + 2 + + + X + +
+ | 0010 | 2 | | | X | |
+-------+-----+-----+-----+-----+-----+
- + 0011 + 3 + + + X + X +
+ | 0011 | 3 | | | X | X |
+-------+-----+-----+-----+-----+-----+
- + 0100 + 4 + + X + + +
+ | 0100 | 4 | | X | | |
+-------+-----+-----+-----+-----+-----+
- + 0101 + 5 + + X + + X +
+ | 0101 | 5 | | X | | X |
+-------+-----+-----+-----+-----+-----+
- + 0110 + 6 + + X + X + +
+ | 0110 | 6 | | X | X | |
+-------+-----+-----+-----+-----+-----+
- + 0111 + 7 + + X + X + X +
+ | 0111 | 7 | | X | X | X |
+-------+-----+-----+-----+-----+-----+
- + 1000 + 8 + X + + + +
+ | 1000 | 8 | X | | | |
+-------+-----+-----+-----+-----+-----+
- + 1001 + 9 + X + + + X +
+ | 1001 | 9 | X | | | X |
+-------+-----+-----+-----+-----+-----+
- + 1010 + 10 + X + + X + +
+ | 1010 | 10 | X | | X | |
+-------+-----+-----+-----+-----+-----+
- + 1011 + 11 + X + + X + X +
+ | 1011 | 11 | X | | X | X |
+-------+-----+-----+-----+-----+-----+
- + 1100 + 12 + X + X + + +
+ | 1100 | 12 | X | X | | |
+-------+-----+-----+-----+-----+-----+
- + 1101 + 13 + X + X + + X +
+ | 1101 | 13 | X | X | | X |
+-------+-----+-----+-----+-----+-----+
- + 1110 + 14 + X + X + X + +
+ | 1110 | 14 | X | X | X | |
+-------+-----+-----+-----+-----+-----+
- + 1111 + 15 + X + X + X + X +
+ | 1111 | 15 | X | X | X | X |
+-------+-----+-----+-----+-----+-----+
In most cases, the appropriate displays must be plugged in for the above
combinations to work. TV-Out may need to be initialized at boot time.
Debugging:
+
1) Check whether the Fn+F8 key:
+
a) does not lock the laptop (try a boot with noapic / nolapic if it does)
b) generates events (0x6n, where n is the value corresponding to the
configuration above)
c) actually works
+
Record the disp value at every configuration.
2) Echo values from 0 to 15 to /sys/devices/platform/asus-laptop/display.
Record its value, note any change. If nothing changes, try a broader range,
@@ -164,7 +176,7 @@ Display switching
Note: on some machines (e.g. L3C), after the module has been loaded, only 0x6n
events are generated and no actual switching occurs. In such a case, a line
- like:
+ like::
echo $((10#$arg-60)) > /sys/devices/platform/asus-laptop/display
@@ -180,15 +192,16 @@ LED display
several items of information.
LED display works for the following models:
- W1000N
- W1J
- To control the LED display, use the following :
+ - W1000N
+ - W1J
+
+ 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,
- according to the tables below.
+ according to the tables below::
DDD (digits)
000 to 999 = display digits
@@ -208,8 +221,8 @@ LED display
For example "echo 0x01000001 >/sys/devices/platform/asus-laptop/ledd"
would display "DVD001".
-Driver options:
----------------
+Driver options
+--------------
Options can be passed to the asus-laptop driver using the standard
module argument syntax (<param>=<value> when passing the option to the
@@ -219,6 +232,7 @@ Driver options:
wapf: WAPF defines the behavior of the Fn+Fx wlan key
The significance of values is yet to be found, but
most of the time:
+
- 0x0 should do nothing
- 0x1 should allow to control the device with Fn+Fx key.
- 0x4 should send an ACPI event (0x88) while pressing the Fn+Fx key
@@ -237,7 +251,7 @@ Unsupported models
- ASUS L7300G
- ASUS L8400
-Patches, Errors, Questions:
+Patches, Errors, Questions
--------------------------
I appreciate any success or failure
@@ -253,5 +267,5 @@ Patches, Errors, Questions:
Any other comments or patches are also more than welcome.
acpi4asus-user@lists.sourceforge.net
+
http://sourceforge.net/projects/acpi4asus
-
diff --git a/Documentation/laptops/disk-shock-protection.txt b/Documentation/laptops/disk-shock-protection.rst
similarity index 91%
rename from Documentation/laptops/disk-shock-protection.txt
rename to Documentation/laptops/disk-shock-protection.rst
index 0e6ba2663834..e97c5f78d8c3 100644
--- a/Documentation/laptops/disk-shock-protection.txt
+++ b/Documentation/laptops/disk-shock-protection.rst
@@ -1,17 +1,18 @@
+==========================
Hard disk shock protection
==========================
Author: Elias Oltmanns <eo@nebensachen.de>
+
Last modified: 2008-10-03
-0. Contents
------------
+.. 0. Contents
-1. Intro
-2. The interface
-3. References
-4. CREDITS
+ 1. Intro
+ 2. The interface
+ 3. References
+ 4. CREDITS
1. Intro
@@ -36,8 +37,8 @@ that).
----------------
For each ATA device, the kernel exports the file
-block/*/device/unload_heads in sysfs (here assumed to be mounted under
-/sys). Access to /sys/block/*/device/unload_heads is denied with
+`block/*/device/unload_heads` in sysfs (here assumed to be mounted under
+/sys). Access to `/sys/block/*/device/unload_heads` is denied with
-EOPNOTSUPP if the device does not support the unload feature.
Otherwise, writing an integer value to this file will take the heads
of the respective drive off the platter and block all I/O operations
@@ -54,18 +55,18 @@ cancel a previously set timeout and resume normal operation
immediately by specifying a timeout of 0. Values below -2 are rejected
with -EINVAL (see below for the special meaning of -1 and -2). If the
timeout specified for a recent head park request has not yet expired,
-reading from /sys/block/*/device/unload_heads will report the number
+reading from `/sys/block/*/device/unload_heads` will report the number
of milliseconds remaining until normal operation will be resumed;
otherwise, reading the unload_heads attribute will return 0.
For example, do the following in order to park the heads of drive
-/dev/sda and stop all I/O operations for five seconds:
+/dev/sda and stop all I/O operations for five seconds::
-# echo 5000 > /sys/block/sda/device/unload_heads
+ # echo 5000 > /sys/block/sda/device/unload_heads
-A simple
+A simple::
-# cat /sys/block/sda/device/unload_heads
+ # cat /sys/block/sda/device/unload_heads
will show you how many milliseconds are left before normal operation
will be resumed.
@@ -112,9 +113,9 @@ unload_heads attribute. If you know that your device really does
support the unload feature (for instance, because the vendor of your
laptop or the hard drive itself told you so), then you can tell the
kernel to enable the usage of this feature for that drive by writing
-the special value -1 to the unload_heads attribute:
+the special value -1 to the unload_heads attribute::
-# echo -1 > /sys/block/sda/device/unload_heads
+ # echo -1 > /sys/block/sda/device/unload_heads
will enable the feature for /dev/sda, and giving -2 instead of -1 will
disable it again.
@@ -135,6 +136,7 @@ for use. Please feel free to add projects that have been the victims
of my ignorance.
- http://www.thinkwiki.org/wiki/HDAPS
+
See this page for information about Linux support of the hard disk
active protection system as implemented in IBM/Lenovo Thinkpads.
diff --git a/Documentation/laptops/index.rst b/Documentation/laptops/index.rst
new file mode 100644
index 000000000000..001a30910d09
--- /dev/null
+++ b/Documentation/laptops/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+==============
+Laptop Drivers
+==============
+
+.. toctree::
+ :maxdepth: 1
+
+ asus-laptop
+ disk-shock-protection
+ laptop-mode
+ lg-laptop
+ sony-laptop
+ sonypi
+ thinkpad-acpi
+ toshiba_haps
diff --git a/Documentation/laptops/laptop-mode.txt b/Documentation/laptops/laptop-mode.rst
similarity index 62%
rename from Documentation/laptops/laptop-mode.txt
rename to Documentation/laptops/laptop-mode.rst
index 1c707fc9b141..c984c4262f2e 100644
--- a/Documentation/laptops/laptop-mode.txt
+++ b/Documentation/laptops/laptop-mode.rst
@@ -1,8 +1,11 @@
+===============================================
How to conserve battery power using laptop-mode
------------------------------------------------
+===============================================
Document Author: Bart Samwel (bart@samwel.tk)
+
Date created: January 2, 2004
+
Last modified: December 06, 2004
Introduction
@@ -12,17 +15,16 @@ Laptop mode is used to minimize the time that the hard disk needs to be spun up,
to conserve battery power on laptops. It has been reported to cause significant
power savings.
-Contents
---------
+.. Contents
-* Introduction
-* Installation
-* Caveats
-* The Details
-* Tips & Tricks
-* Control script
-* ACPI integration
-* Monitoring tool
+ * Introduction
+ * Installation
+ * Caveats
+ * The Details
+ * Tips & Tricks
+ * Control script
+ * ACPI integration
+ * Monitoring tool
Installation
@@ -33,7 +35,7 @@ or anything. Simply install all the files included in this document, and
laptop mode will automatically be started when you're on battery. For
your convenience, a tarball containing an installer can be downloaded at:
-http://www.samwel.tk/laptop_mode/laptop_mode/
+ http://www.samwel.tk/laptop_mode/laptop_mode/
To configure laptop mode, you need to edit the configuration file, which is
located in /etc/default/laptop-mode on Debian-based systems, or in
@@ -209,7 +211,7 @@ Tips & Tricks
this on powerbooks too. I hope that this is a piece of information that
might be useful to the Laptop Mode patch or its users."
-* In syslog.conf, you can prefix entries with a dash ``-'' to omit syncing the
+* In syslog.conf, you can prefix entries with a dash `-` to omit syncing the
file after every logging. When you're using laptop-mode and your disk doesn't
spin down, this is a likely culprit.
@@ -233,83 +235,82 @@ configuration file
It should be installed as /etc/default/laptop-mode on Debian, and as
/etc/sysconfig/laptop-mode on Red Hat, SUSE, Mandrake, and other work-alikes.
---------------------CONFIG FILE BEGIN-------------------------------------------
-# Maximum time, in seconds, of hard drive spindown time that you are
-# comfortable with. Worst case, it's possible that you could lose this
-# amount of work if your battery fails you while in laptop mode.
-#MAX_AGE=600
+Config file::
-# Automatically disable laptop mode when the number of minutes of battery
-# that you have left goes below this threshold.
-MINIMUM_BATTERY_MINUTES=10
+ # Maximum time, in seconds, of hard drive spindown time that you are
+ # comfortable with. Worst case, it's possible that you could lose this
+ # amount of work if your battery fails you while in laptop mode.
+ #MAX_AGE=600
-# Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
-# by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
-# will read a complete MP3 at once, and will then spin down while the MP3/OGG is
-# playing.
-#READAHEAD=4096
+ # Automatically disable laptop mode when the number of minutes of battery
+ # that you have left goes below this threshold.
+ MINIMUM_BATTERY_MINUTES=10
-# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
-#DO_REMOUNTS=1
+ # Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
+ # by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
+ # will read a complete MP3 at once, and will then spin down while the MP3/OGG is
+ # playing.
+ #READAHEAD=4096
-# And shall we add the "noatime" option to that as well? (1=yes)
-#DO_REMOUNT_NOATIME=1
+ # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
+ #DO_REMOUNTS=1
-# Dirty synchronous ratio. At this percentage of dirty pages the process
-# which
-# calls write() does its own writeback
-#DIRTY_RATIO=40
+ # And shall we add the "noatime" option to that as well? (1=yes)
+ #DO_REMOUNT_NOATIME=1
-#
-# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
-# exceeded, the kernel will wake flusher threads which will then reduce the
-# amount of dirty memory to dirty_background_ratio. Set this nice and low,
-# so once some writeout has commenced, we do a lot of it.
-#
-#DIRTY_BACKGROUND_RATIO=5
+ # Dirty synchronous ratio. At this percentage of dirty pages the process
+ # which
+ # calls write() does its own writeback
+ #DIRTY_RATIO=40
-# kernel default dirty buffer age
-#DEF_AGE=30
-#DEF_UPDATE=5
-#DEF_DIRTY_BACKGROUND_RATIO=10
-#DEF_DIRTY_RATIO=40
-#DEF_XFS_AGE_BUFFER=15
-#DEF_XFS_SYNC_INTERVAL=30
-#DEF_XFS_BUFD_INTERVAL=1
+ #
+ # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
+ # exceeded, the kernel will wake flusher threads which will then reduce the
+ # amount of dirty memory to dirty_background_ratio. Set this nice and low,
+ # so once some writeout has commenced, we do a lot of it.
+ #
+ #DIRTY_BACKGROUND_RATIO=5
-# This must be adjusted manually to the value of HZ in the running kernel
-# on 2.4, until the XFS people change their 2.4 external interfaces to work in
-# centisecs. This can be automated, but it's a work in progress that still
-# needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
-# external interfaces, and that is currently always set to 100. So you don't
-# need to change this on 2.6.
-#XFS_HZ=100
+ # kernel default dirty buffer age
+ #DEF_AGE=30
+ #DEF_UPDATE=5
+ #DEF_DIRTY_BACKGROUND_RATIO=10
+ #DEF_DIRTY_RATIO=40
+ #DEF_XFS_AGE_BUFFER=15
+ #DEF_XFS_SYNC_INTERVAL=30
+ #DEF_XFS_BUFD_INTERVAL=1
-# Should the maximum CPU frequency be adjusted down while on battery?
-# Requires CPUFreq to be setup.
-# See Documentation/admin-guide/pm/cpufreq.rst for more info
-#DO_CPU=0
+ # This must be adjusted manually to the value of HZ in the running kernel
+ # on 2.4, until the XFS people change their 2.4 external interfaces to work in
+ # centisecs. This can be automated, but it's a work in progress that still
+ # needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
+ # external interfaces, and that is currently always set to 100. So you don't
+ # need to change this on 2.6.
+ #XFS_HZ=100
-# When on battery what is the maximum CPU speed that the system should
-# use? Legal values are "slowest" for the slowest speed that your
-# CPU is able to operate at, or a value listed in:
-# /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
-# Only applicable if DO_CPU=1.
-#CPU_MAXFREQ=slowest
+ # Should the maximum CPU frequency be adjusted down while on battery?
+ # Requires CPUFreq to be setup.
+ # See Documentation/admin-guide/pm/cpufreq.rst for more info
+ #DO_CPU=0
-# Idle timeout for your hard drive (man hdparm for valid values, -S option)
-# Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
-#AC_HD=244
-#BATT_HD=4
+ # When on battery what is the maximum CPU speed that the system should
+ # use? Legal values are "slowest" for the slowest speed that your
+ # CPU is able to operate at, or a value listed in:
+ # /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
+ # Only applicable if DO_CPU=1.
+ #CPU_MAXFREQ=slowest
-# The drives for which to adjust the idle timeout. Separate them by a space,
-# e.g. HD="/dev/hda /dev/hdb".
-#HD="/dev/hda"
+ # Idle timeout for your hard drive (man hdparm for valid values, -S option)
+ # Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
+ #AC_HD=244
+ #BATT_HD=4
-# Set the spindown timeout on a hard drive?
-#DO_HD=1
+ # The drives for which to adjust the idle timeout. Separate them by a space,
+ # e.g. HD="/dev/hda /dev/hdb".
+ #HD="/dev/hda"
---------------------CONFIG FILE END---------------------------------------------
+ # Set the spindown timeout on a hard drive?
+ #DO_HD=1
Control script
@@ -318,125 +319,126 @@ Control script
Please note that this control script works for the Linux 2.4 and 2.6 series (thanks
to Kiko Piris).
---------------------CONTROL SCRIPT BEGIN----------------------------------------
-#!/bin/bash
+Control script::
-# start or stop laptop_mode, best run by a power management daemon when
-# ac gets connected/disconnected from a laptop
-#
-# install as /sbin/laptop_mode
-#
-# Contributors to this script: Kiko Piris
-# Bart Samwel
-# Micha Feigin
-# Andrew Morton
-# Herve Eychenne
-# Dax Kelson
-#
-# Original Linux 2.4 version by: Jens Axboe
+ #!/bin/bash
-#############################################################################
+ # start or stop laptop_mode, best run by a power management daemon when
+ # ac gets connected/disconnected from a laptop
+ #
+ # install as /sbin/laptop_mode
+ #
+ # Contributors to this script: Kiko Piris
+ # Bart Samwel
+ # Micha Feigin
+ # Andrew Morton
+ # Herve Eychenne
+ # Dax Kelson
+ #
+ # Original Linux 2.4 version by: Jens Axboe
-# Source config
-if [ -f /etc/default/laptop-mode ] ; then
+ #############################################################################
+
+ # Source config
+ if [ -f /etc/default/laptop-mode ] ; then
# Debian
. /etc/default/laptop-mode
-elif [ -f /etc/sysconfig/laptop-mode ] ; then
+ elif [ -f /etc/sysconfig/laptop-mode ] ; then
# Others
- . /etc/sysconfig/laptop-mode
-fi
+ . /etc/sysconfig/laptop-mode
+ fi
-# Don't raise an error if the config file is incomplete
-# set defaults instead:
+ # Don't raise an error if the config file is incomplete
+ # set defaults instead:
-# Maximum time, in seconds, of hard drive spindown time that you are
-# comfortable with. Worst case, it's possible that you could lose this
-# amount of work if your battery fails you while in laptop mode.
-MAX_AGE=${MAX_AGE:-'600'}
+ # Maximum time, in seconds, of hard drive spindown time that you are
+ # comfortable with. Worst case, it's possible that you could lose this
+ # amount of work if your battery fails you while in laptop mode.
+ MAX_AGE=${MAX_AGE:-'600'}
-# Read-ahead, in kilobytes
-READAHEAD=${READAHEAD:-'4096'}
+ # Read-ahead, in kilobytes
+ READAHEAD=${READAHEAD:-'4096'}
-# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
-DO_REMOUNTS=${DO_REMOUNTS:-'1'}
+ # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
+ DO_REMOUNTS=${DO_REMOUNTS:-'1'}
-# And shall we add the "noatime" option to that as well? (1=yes)
-DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
+ # And shall we add the "noatime" option to that as well? (1=yes)
+ DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
-# Shall we adjust the idle timeout on a hard drive?
-DO_HD=${DO_HD:-'1'}
+ # Shall we adjust the idle timeout on a hard drive?
+ DO_HD=${DO_HD:-'1'}
-# Adjust idle timeout on which hard drive?
-HD="${HD:-'/dev/hda'}"
+ # Adjust idle timeout on which hard drive?
+ HD="${HD:-'/dev/hda'}"
-# spindown time for HD (hdparm -S values)
-AC_HD=${AC_HD:-'244'}
-BATT_HD=${BATT_HD:-'4'}
+ # spindown time for HD (hdparm -S values)
+ AC_HD=${AC_HD:-'244'}
+ BATT_HD=${BATT_HD:-'4'}
-# Dirty synchronous ratio. At this percentage of dirty pages the process which
-# calls write() does its own writeback
-DIRTY_RATIO=${DIRTY_RATIO:-'40'}
+ # Dirty synchronous ratio. At this percentage of dirty pages the process which
+ # calls write() does its own writeback
+ DIRTY_RATIO=${DIRTY_RATIO:-'40'}
-# cpu frequency scaling
-# See Documentation/admin-guide/pm/cpufreq.rst for more info
-DO_CPU=${CPU_MANAGE:-'0'}
-CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
+ # cpu frequency scaling
+ # See Documentation/admin-guide/pm/cpufreq.rst for more info
+ DO_CPU=${CPU_MANAGE:-'0'}
+ CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
-#
-# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
-# exceeded, the kernel will wake flusher threads which will then reduce the
-# amount of dirty memory to dirty_background_ratio. Set this nice and low,
-# so once some writeout has commenced, we do a lot of it.
-#
-DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
+ #
+ # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
+ # exceeded, the kernel will wake flusher threads which will then reduce the
+ # amount of dirty memory to dirty_background_ratio. Set this nice and low,
+ # so once some writeout has commenced, we do a lot of it.
+ #
+ DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
-# kernel default dirty buffer age
-DEF_AGE=${DEF_AGE:-'30'}
-DEF_UPDATE=${DEF_UPDATE:-'5'}
-DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
-DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
-DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
-DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
-DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
+ # kernel default dirty buffer age
+ DEF_AGE=${DEF_AGE:-'30'}
+ DEF_UPDATE=${DEF_UPDATE:-'5'}
+ DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
+ DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
+ DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
+ DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
+ DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
-# This must be adjusted manually to the value of HZ in the running kernel
-# on 2.4, until the XFS people change their 2.4 external interfaces to work in
-# centisecs. This can be automated, but it's a work in progress that still needs
-# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
-# interfaces, and that is currently always set to 100. So you don't need to
-# change this on 2.6.
-XFS_HZ=${XFS_HZ:-'100'}
+ # This must be adjusted manually to the value of HZ in the running kernel
+ # on 2.4, until the XFS people change their 2.4 external interfaces to work in
+ # centisecs. This can be automated, but it's a work in progress that still needs
+ # some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
+ # interfaces, and that is currently always set to 100. So you don't need to
+ # change this on 2.6.
+ XFS_HZ=${XFS_HZ:-'100'}
-#############################################################################
+ #############################################################################
-KLEVEL="$(uname -r |
- {
+ KLEVEL="$(uname -r |
+ {
IFS='.' read a b c
echo $a.$b
}
-)"
-case "$KLEVEL" in
+ )"
+ case "$KLEVEL" in
"2.4"|"2.6")
;;
*)
echo "Unhandled kernel version: $KLEVEL ('uname -r' = '$(uname -r)')" >&2
exit 1
;;
-esac
+ esac
-if [ ! -e /proc/sys/vm/laptop_mode ] ; then
+ if [ ! -e /proc/sys/vm/laptop_mode ] ; then
echo "Kernel is not patched with laptop_mode patch." >&2
exit 1
-fi
+ fi
-if [ ! -w /proc/sys/vm/laptop_mode ] ; then
+ if [ ! -w /proc/sys/vm/laptop_mode ] ; then
echo "You do not have enough privileges to enable laptop_mode." >&2
exit 1
-fi
+ fi
-# Remove an option (the first parameter) of the form option=<number> from
-# a mount options string (the rest of the parameters).
-parse_mount_opts () {
+ # Remove an option (the first parameter) of the form option=<number> from
+ # a mount options string (the rest of the parameters).
+ parse_mount_opts () {
OPT="$1"
shift
echo ",$*," | sed \
@@ -444,11 +446,11 @@ parse_mount_opts () {
-e 's/,,*/,/g' \
-e 's/^,//' \
-e 's/,$//'
-}
+ }
-# Remove an option (the first parameter) without any arguments from
-# a mount option string (the rest of the parameters).
-parse_nonumber_mount_opts () {
+ # Remove an option (the first parameter) without any arguments from
+ # a mount option string (the rest of the parameters).
+ parse_nonumber_mount_opts () {
OPT="$1"
shift
echo ",$*," | sed \
@@ -456,20 +458,20 @@ parse_nonumber_mount_opts () {
-e 's/,,*/,/g' \
-e 's/^,//' \
-e 's/,$//'
-}
+ }
-# Find out the state of a yes/no option (e.g. "atime"/"noatime") in
-# fstab for a given filesystem, and use this state to replace the
-# value of the option in another mount options string. The device
-# is the first argument, the option name the second, and the default
-# value the third. The remainder is the mount options string.
-#
-# Example:
-# parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
-#
-# If fstab contains, say, "rw" for this filesystem, then the result
-# will be "defaults,atime".
-parse_yesno_opts_wfstab () {
+ # Find out the state of a yes/no option (e.g. "atime"/"noatime") in
+ # fstab for a given filesystem, and use this state to replace the
+ # value of the option in another mount options string. The device
+ # is the first argument, the option name the second, and the default
+ # value the third. The remainder is the mount options string.
+ #
+ # Example:
+ # parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
+ #
+ # If fstab contains, say, "rw" for this filesystem, then the result
+ # will be "defaults,atime".
+ parse_yesno_opts_wfstab () {
L_DEV="$1"
OPT="$2"
DEF_OPT="$3"
@@ -491,21 +493,21 @@ parse_yesno_opts_wfstab () {
# option not specified in fstab -- choose the default.
echo "$PARSEDOPTS1,$DEF_OPT"
fi
-}
+ }
-# Find out the state of a numbered option (e.g. "commit=NNN") in
-# fstab for a given filesystem, and use this state to replace the
-# value of the option in another mount options string. The device
-# is the first argument, and the option name the second. The
-# remainder is the mount options string in which the replacement
-# must be done.
-#
-# Example:
-# parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
-#
-# If fstab contains, say, "commit=3,rw" for this filesystem, then the
-# result will be "rw,commit=3".
-parse_mount_opts_wfstab () {
+ # Find out the state of a numbered option (e.g. "commit=NNN") in
+ # fstab for a given filesystem, and use this state to replace the
+ # value of the option in another mount options string. The device
+ # is the first argument, and the option name the second. The
+ # remainder is the mount options string in which the replacement
+ # must be done.
+ #
+ # Example:
+ # parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
+ #
+ # If fstab contains, say, "commit=3,rw" for this filesystem, then the
+ # result will be "rw,commit=3".
+ parse_mount_opts_wfstab () {
L_DEV="$1"
OPT="$2"
shift 2
@@ -523,9 +525,9 @@ parse_mount_opts_wfstab () {
# option not specified in fstab: set it to 0
echo "$PARSEDOPTS1,$OPT=0"
fi
-}
+ }
-deduce_fstype () {
+ deduce_fstype () {
MP="$1"
# My root filesystem unfortunately has
# type "unknown" in /etc/mtab. If we encounter
@@ -538,13 +540,13 @@ deduce_fstype () {
exit 0
fi
done
-}
+ }
-if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
+ if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
NOATIME_OPT=",noatime"
-fi
+ fi
-case "$1" in
+ case "$1" in
start)
AGE=$((100*$MAX_AGE))
XFS_AGE=$(($XFS_HZ*$MAX_AGE))
@@ -687,10 +689,9 @@ case "$1" in
exit 1
;;
-esac
+ esac
-exit 0
---------------------CONTROL SCRIPT END------------------------------------------
+ exit 0
ACPI integration
@@ -701,78 +702,76 @@ kick off the laptop_mode script and run hdparm. The part that
automatically disables laptop mode when the battery is low was
written by Jan Topinski.
------------------/etc/acpi/events/ac_adapter BEGIN------------------------------
-event=ac_adapter
-action=/etc/acpi/actions/ac.sh %e
-----------------/etc/acpi/events/ac_adapter END---------------------------------
+/etc/acpi/events/ac_adapter::
+ event=ac_adapter
+ action=/etc/acpi/actions/ac.sh %e
------------------/etc/acpi/events/battery BEGIN---------------------------------
-event=battery.*
-action=/etc/acpi/actions/battery.sh %e
-----------------/etc/acpi/events/battery END------------------------------------
+/etc/acpi/events/battery::
+ event=battery.*
+ action=/etc/acpi/actions/battery.sh %e
-----------------/etc/acpi/actions/ac.sh BEGIN-----------------------------------
-#!/bin/bash
+/etc/acpi/actions/ac.sh::
-# ac on/offline event handler
+ #!/bin/bash
-status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
+ # ac on/offline event handler
-case $status in
- "on-line")
- /sbin/laptop_mode stop
- exit 0
- ;;
- "off-line")
- /sbin/laptop_mode start
- exit 0
- ;;
-esac
----------------------------/etc/acpi/actions/ac.sh END--------------------------
+ status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
+ case $status in
+ "on-line")
+ /sbin/laptop_mode stop
+ exit 0
+ ;;
+ "off-line")
+ /sbin/laptop_mode start
+ exit 0
+ ;;
+ esac
----------------------------/etc/acpi/actions/battery.sh BEGIN-------------------
-#! /bin/bash
-# Automatically disable laptop mode when the battery almost runs out.
+/etc/acpi/actions/battery.sh::
-BATT_INFO=/proc/acpi/battery/$2/state
+ #! /bin/bash
-if [[ -f /proc/sys/vm/laptop_mode ]]
-then
- LM=`cat /proc/sys/vm/laptop_mode`
- if [[ $LM -gt 0 ]]
- then
- if [[ -f $BATT_INFO ]]
+ # Automatically disable laptop mode when the battery almost runs out.
+
+ BATT_INFO=/proc/acpi/battery/$2/state
+
+ if [[ -f /proc/sys/vm/laptop_mode ]]
+ then
+ LM=`cat /proc/sys/vm/laptop_mode`
+ if [[ $LM -gt 0 ]]
then
- # Source the config file only now that we know we need
- if [ -f /etc/default/laptop-mode ] ; then
- # Debian
- . /etc/default/laptop-mode
- elif [ -f /etc/sysconfig/laptop-mode ] ; then
- # Others
- . /etc/sysconfig/laptop-mode
- fi
- MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
+ if [[ -f $BATT_INFO ]]
+ then
+ # Source the config file only now that we know we need
+ if [ -f /etc/default/laptop-mode ] ; then
+ # Debian
+ . /etc/default/laptop-mode
+ elif [ -f /etc/sysconfig/laptop-mode ] ; then
+ # Others
+ . /etc/sysconfig/laptop-mode
+ fi
+ MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
- ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
- if [[ ACTION -eq "discharging" ]]
- then
- PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
- REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
- fi
- if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
- then
- /sbin/laptop_mode stop
- fi
- else
- logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
+ ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
+ if [[ ACTION -eq "discharging" ]]
+ then
+ PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
+ REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
+ fi
+ if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
+ then
+ /sbin/laptop_mode stop
+ fi
+ else
+ logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
+ fi
fi
- fi
-fi
----------------------------/etc/acpi/actions/battery.sh END--------------------
+ fi
Monitoring tool
diff --git a/Documentation/laptops/sony-laptop.txt b/Documentation/laptops/sony-laptop.rst
similarity index 85%
rename from Documentation/laptops/sony-laptop.txt
rename to Documentation/laptops/sony-laptop.rst
index 978b1e615155..9edcc7f6612f 100644
--- a/Documentation/laptops/sony-laptop.txt
+++ b/Documentation/laptops/sony-laptop.rst
@@ -1,7 +1,9 @@
+=========================================
Sony Notebook Control Driver (SNC) Readme
------------------------------------------
- Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
- Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
+=========================================
+
+ - Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
+ - Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
This mini-driver drives the SNC and SPIC device present in the ACPI BIOS of the
Sony Vaio laptops. This driver mixes both devices functions under the same
@@ -10,6 +12,7 @@ obsoleted by sony-laptop now.
Fn keys (hotkeys):
------------------
+
Some models report hotkeys through the SNC or SPIC devices, such events are
reported both through the ACPI subsystem as acpi events and through the INPUT
subsystem. See the logs of /proc/bus/input/devices to find out what those
@@ -28,11 +31,14 @@ If your laptop model supports it, you will find sysfs files in the
/sys/class/backlight/sony/
directory. You will be able to query and set the current screen
brightness:
+
+ ====================== =========================================
brightness get/set screen brightness (an integer
between 0 and 7)
actual_brightness reading from this file will query the HW
to get real brightness value
max_brightness the maximum brightness value
+ ====================== =========================================
Platform specific:
@@ -45,6 +51,8 @@ You then read/write integer values from/to those files by using
standard UNIX tools.
The files are:
+
+ ====================== ==========================================
brightness_default screen brightness which will be set
when the laptop will be rebooted
cdpower power on/off the internal CD drive
@@ -53,21 +61,39 @@ The files are:
(only in debug mode)
bluetoothpower power on/off the internal bluetooth device
fanspeed get/set the fan speed
+ ====================== ==========================================
Note that some files may be missing if they are not supported
by your particular laptop model.
-Example usage:
+Example usage::
+
# echo "1" > /sys/devices/platform/sony-laptop/brightness_default
-sets the lowest screen brightness for the next and later reboots,
+
+sets the lowest screen brightness for the next and later reboots
+
+::
+
# echo "8" > /sys/devices/platform/sony-laptop/brightness_default
-sets the highest screen brightness for the next and later reboots,
+
+sets the highest screen brightness for the next and later reboots
+
+::
+
# cat /sys/devices/platform/sony-laptop/brightness_default
-retrieves the value.
+
+retrieves the value
+
+::
# echo "0" > /sys/devices/platform/sony-laptop/audiopower
-powers off the sound card,
+
+powers off the sound card
+
+::
+
# echo "1" > /sys/devices/platform/sony-laptop/audiopower
+
powers on the sound card.
@@ -76,7 +102,8 @@ RFkill control:
More recent Vaio models expose a consistent set of ACPI methods to
control radio frequency emitting devices. If you are a lucky owner of
such a laptop you will find the necessary rfkill devices under
-/sys/class/rfkill. Check those starting with sony-* in
+/sys/class/rfkill. Check those starting with sony-* in::
+
# grep . /sys/class/rfkill/*/{state,name}
@@ -88,26 +115,29 @@ you are not afraid of any side effects doing strange things with
your ACPI BIOS could have on your laptop), load the driver and
pass the option 'debug=1'.
-REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.
+REPEAT:
+ **DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.**
In your kernel logs you will find the list of all ACPI methods
the SNC device has on your laptop.
* For new models you will see a long list of meaningless method names,
-reading the DSDT table source should reveal that:
+ reading the DSDT table source should reveal that:
+
(1) the SNC device uses an internal capability lookup table
(2) SN00 is used to find values in the lookup table
(3) SN06 and SN07 are used to call into the real methods based on
offsets you can obtain iterating the table using SN00
(4) SN02 used to enable events.
+
Some values in the capability lookup table are more or less known, see
the code for all sony_call_snc_handle calls, others are more obscure.
* For old models you can see the GCDP/GCDP methods used to pwer on/off
-the CD drive, but there are others and they are usually different from
-model to model.
+ the CD drive, but there are others and they are usually different from
+ model to model.
-I HAVE NO IDEA WHAT THOSE METHODS DO.
+**I HAVE NO IDEA WHAT THOSE METHODS DO.**
The sony-laptop driver creates, for some of those methods (the most
current ones found on several Vaio models), an entry under
diff --git a/Documentation/laptops/sonypi.txt b/Documentation/laptops/sonypi.rst
similarity index 87%
rename from Documentation/laptops/sonypi.txt
rename to Documentation/laptops/sonypi.rst
index 606bdb9ce036..2a1975ed7ee4 100644
--- a/Documentation/laptops/sonypi.txt
+++ b/Documentation/laptops/sonypi.rst
@@ -1,11 +1,13 @@
+==================================================
Sony Programmable I/O Control Device Driver Readme
---------------------------------------------------
- Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
- Copyright (C) 2001-2002 Alcôve <www.alcove.com>
- Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
- Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
- Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
- Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
+==================================================
+
+ - Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
+ - Copyright (C) 2001-2002 Alcôve <www.alcove.com>
+ - Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
+ - Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
+ - Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
+ - Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
This driver enables access to the Sony Programmable I/O Control Device which
can be found in many Sony Vaio laptops. Some newer Sony laptops (seems to be
@@ -14,6 +16,7 @@ sonypi device and are not supported at all by this driver.
It will give access (through a user space utility) to some events those laptops
generate, like:
+
- jogdial events (the small wheel on the side of Vaios)
- capture button events (only on Vaio Picturebook series)
- Fn keys
@@ -49,6 +52,7 @@ module argument syntax (<param>=<value> when passing the option to the
module or sonypi.<param>=<value> on the kernel boot line when sonypi is
statically linked into the kernel). Those options are:
+ =============== =======================================================
minor: minor number of the misc device /dev/sonypi,
default is -1 (automatic allocation, see /proc/misc
or kernel logs)
@@ -86,6 +90,8 @@ statically linked into the kernel). Those options are:
will be tried. You can use the following bits to
construct your own event mask (from
drivers/char/sonypi.h):
+
+ ======================== ======
SONYPI_JOGGER_MASK 0x0001
SONYPI_CAPTURE_MASK 0x0002
SONYPI_FNKEY_MASK 0x0004
@@ -100,22 +106,24 @@ statically linked into the kernel). Those options are:
SONYPI_MEMORYSTICK_MASK 0x0800
SONYPI_BATTERY_MASK 0x1000
SONYPI_WIRELESS_MASK 0x2000
+ ======================== ======
useinput: if set (which is the default) two input devices are
created, one which interprets the jogdial events as
mouse events, the other one which acts like a
keyboard reporting the pressing of the special keys.
+ =============== =======================================================
Module use:
-----------
In order to automatically load the sonypi module on use, you can put those
-lines a configuration file in /etc/modprobe.d/:
+lines a configuration file in /etc/modprobe.d/::
alias char-major-10-250 sonypi
options sonypi minor=250
-This supposes the use of minor 250 for the sonypi device:
+This supposes the use of minor 250 for the sonypi device::
# mknod /dev/sonypi c 10 250
@@ -148,5 +156,5 @@ Bugs:
http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2
- since all development was done by reverse engineering, there is
- _absolutely no guarantee_ that this driver will not crash your
+ *absolutely no guarantee* that this driver will not crash your
laptop. Permanently.
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.rst
similarity index 89%
rename from Documentation/laptops/thinkpad-acpi.txt
rename to Documentation/laptops/thinkpad-acpi.rst
index 75ef063622d2..19d52fc3c5e9 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.rst
@@ -1,12 +1,15 @@
- ThinkPad ACPI Extras Driver
+===========================
+ThinkPad ACPI Extras Driver
+===========================
- Version 0.25
- October 16th, 2013
+Version 0.25
- Borislav Deianov <borislav@users.sf.net>
- Henrique de Moraes Holschuh <hmh@hmh.eng.br>
- http://ibm-acpi.sf.net/
+October 16th, 2013
+- Borislav Deianov <borislav@users.sf.net>
+- Henrique de Moraes Holschuh <hmh@hmh.eng.br>
+
+http://ibm-acpi.sf.net/
This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
supports various features of these laptops which are accessible
@@ -91,7 +94,8 @@ yet ready or stabilized, it is expected that this interface will change,
and any and all userspace programs must deal with it.
-Notes about the sysfs interface:
+Notes about the sysfs interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Unlike what was done with the procfs interface, correctness when talking
to the sysfs interfaces will be enforced, as will correctness in the
@@ -129,6 +133,7 @@ Driver version
--------------
procfs: /proc/acpi/ibm/driver
+
sysfs driver attribute: version
The driver name and version. No commands can be written to this file.
@@ -141,9 +146,13 @@ sysfs driver attribute: interface_version
Version of the thinkpad-acpi sysfs interface, as an unsigned long
(output in hex format: 0xAAAABBCC), where:
- AAAA - major revision
- BB - minor revision
- CC - bugfix revision
+
+ AAAA
+ - major revision
+ BB
+ - minor revision
+ CC
+ - bugfix revision
The sysfs interface version changelog for the driver can be found at the
end of this document. Changes to the sysfs interface done by the kernel
@@ -170,6 +179,7 @@ Hot keys
--------
procfs: /proc/acpi/ibm/hotkey
+
sysfs device attribute: hotkey_*
In a ThinkPad, the ACPI HKEY handler is responsible for communicating
@@ -181,7 +191,7 @@ firmware will behave in many situations.
The driver enables the HKEY ("hot key") event reporting automatically
when loaded, and disables it when it is removed.
-The driver will report HKEY events in the following format:
+The driver will report HKEY events in the following format::
ibm/hotkey HKEY 00000080 0000xxxx
@@ -217,9 +227,10 @@ ThinkPads, it is still possible to support some extra hotkeys by
polling the "CMOS NVRAM" at least 10 times per second. The driver
attempts to enables this functionality automatically when required.
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
-The following commands can be written to the /proc/acpi/ibm/hotkey file:
+The following commands can be written to the /proc/acpi/ibm/hotkey file::
echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
@@ -227,7 +238,7 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file:
echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
The following commands have been deprecated and will cause the kernel
-to log a warning:
+to log a warning::
echo enable > /proc/acpi/ibm/hotkey -- does nothing
echo disable > /proc/acpi/ibm/hotkey -- returns an error
@@ -237,7 +248,8 @@ maintain maximum bug-to-bug compatibility, it does not report any masks,
nor does it allow one to manipulate the hot key mask when the firmware
does not support masks at all, even if NVRAM polling is in use.
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
hotkey_bios_enabled:
DEPRECATED, WILL BE REMOVED SOON.
@@ -349,7 +361,8 @@ sysfs notes:
This attribute has poll()/select() support.
-input layer notes:
+input layer notes
+^^^^^^^^^^^^^^^^^
A Hot key is mapped to a single input layer EV_KEY event, possibly
followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
@@ -362,11 +375,13 @@ remapping KEY_UNKNOWN keys.
The events are available in an input device, with the following id:
- Bus: BUS_HOST
- vendor: 0x1014 (PCI_VENDOR_ID_IBM) or
+ ============== ==============================
+ Bus BUS_HOST
+ vendor 0x1014 (PCI_VENDOR_ID_IBM) or
0x17aa (PCI_VENDOR_ID_LENOVO)
- product: 0x5054 ("TP")
- version: 0x4101
+ product 0x5054 ("TP")
+ version 0x4101
+ ============== ==============================
The version will have its LSB incremented if the keymap changes in a
backwards-compatible way. The MSB shall always be 0x41 for this input
@@ -380,9 +395,10 @@ backwards-compatible change for this input device.
Thinkpad-acpi Hot Key event map (version 0x4101):
+======= ======= ============== ==============================================
ACPI Scan
event code Key Notes
-
+======= ======= ============== ==============================================
0x1001 0x00 FN+F1 -
0x1002 0x01 FN+F2 IBM: battery (rare)
@@ -426,7 +442,9 @@ event code Key Notes
or toggle screen expand
0x1009 0x08 FN+F9 -
- .. .. ..
+
+... ... ... ...
+
0x100B 0x0A FN+F11 -
0x100C 0x0B FN+F12 Sleep to disk. You are always
@@ -480,8 +498,11 @@ event code Key Notes
0x1018 0x17 THINKPAD ThinkPad/Access IBM/Lenovo key
0x1019 0x18 unknown
-.. .. ..
+
+... ... ...
+
0x1020 0x1F unknown
+======= ======= ============== ==============================================
The ThinkPad firmware does not allow one to differentiate when most hot
keys are pressed or released (either that, or we don't know how to, yet).
@@ -499,14 +520,17 @@ generate input device EV_KEY events.
In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW
events for switches:
+============== ==============================================
SW_RFKILL_ALL T60 and later hardware rfkill rocker switch
SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A
+============== ==============================================
-Non hotkey ACPI HKEY event map:
--------------------------------
+Non hotkey ACPI HKEY event map
+------------------------------
Events that are never propagated by the driver:
+====== ==================================================
0x2304 System is waking up from suspend to undock
0x2305 System is waking up from suspend to eject bay
0x2404 System is waking up from hibernation to undock
@@ -519,10 +543,12 @@ Events that are never propagated by the driver:
0x6000 KEYBOARD: Numlock key pressed
0x6005 KEYBOARD: Fn key pressed (TO BE VERIFIED)
0x7000 Radio Switch may have changed state
+====== ==================================================
Events that are propagated by the driver to userspace:
+====== =====================================================
0x2313 ALARM: System is waking up from suspend because
the battery is nearly empty
0x2413 ALARM: System is waking up from hibernation because
@@ -544,6 +570,7 @@ Events that are propagated by the driver to userspace:
0x6040 Nvidia Optimus/AC adapter related (TO BE VERIFIED)
0x60C0 X1 Yoga 2016, Tablet mode status changed
0x60F0 Thermal Transformation changed (GMTS, Windows)
+====== =====================================================
Battery nearly empty alarms are a last resort attempt to get the
operating system to hibernate or shutdown cleanly (0x2313), or shutdown
@@ -562,7 +589,8 @@ cycle, or a system shutdown. Obviously, something is very wrong if this
happens.
-Brightness hotkey notes:
+Brightness hotkey notes
+^^^^^^^^^^^^^^^^^^^^^^^
Don't mess with the brightness hotkeys in a Thinkpad. If you want
notifications for OSD, use the sysfs backlight class event support.
@@ -579,7 +607,9 @@ Bluetooth
---------
procfs: /proc/acpi/ibm/bluetooth
+
sysfs device attribute: bluetooth_enable (deprecated)
+
sysfs rfkill class: switch "tpacpi_bluetooth_sw"
This feature shows the presence and current state of a ThinkPad
@@ -588,22 +618,25 @@ Bluetooth device in the internal ThinkPad CDC slot.
If the ThinkPad supports it, the Bluetooth state is stored in NVRAM,
so it is kept across reboots and power-off.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
-If Bluetooth is installed, the following commands can be used:
+If Bluetooth is installed, the following commands can be used::
echo enable > /proc/acpi/ibm/bluetooth
echo disable > /proc/acpi/ibm/bluetooth
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
If the Bluetooth CDC card is installed, it can be enabled /
disabled through the "bluetooth_enable" thinkpad-acpi device
attribute, and its current status can also be queried.
enable:
- 0: disables Bluetooth / Bluetooth is disabled
- 1: enables Bluetooth / Bluetooth is enabled.
+
+ - 0: disables Bluetooth / Bluetooth is disabled
+ - 1: enables Bluetooth / Bluetooth is enabled.
Note: this interface has been superseded by the generic rfkill
class. It has been deprecated, and it will be removed in year
@@ -617,7 +650,7 @@ Video output control -- /proc/acpi/ibm/video
--------------------------------------------
This feature allows control over the devices used for video output -
-LCD, CRT or DVI (if available). The following commands are available:
+LCD, CRT or DVI (if available). The following commands are available::
echo lcd_enable > /proc/acpi/ibm/video
echo lcd_disable > /proc/acpi/ibm/video
@@ -630,9 +663,10 @@ LCD, CRT or DVI (if available). The following commands are available:
echo expand_toggle > /proc/acpi/ibm/video
echo video_switch > /proc/acpi/ibm/video
-NOTE: Access to this feature is restricted to processes owning the
-CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
-enough with some versions of X.org to crash it.
+NOTE:
+ Access to this feature is restricted to processes owning the
+ CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
+ enough with some versions of X.org to crash it.
Each video output device can be enabled or disabled individually.
Reading /proc/acpi/ibm/video shows the status of each device.
@@ -665,18 +699,21 @@ ThinkLight control
------------------
procfs: /proc/acpi/ibm/light
+
sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
The ThinkLight status can be read and set through the procfs interface. A
few models which do not make the status available will show the ThinkLight
-status as "unknown". The available commands are:
+status as "unknown". The available commands are::
echo on > /proc/acpi/ibm/light
echo off > /proc/acpi/ibm/light
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
The ThinkLight sysfs interface is documented by the LED class
documentation, in Documentation/leds/leds-class.rst. The ThinkLight LED name
@@ -691,6 +728,7 @@ CMOS/UCMS control
-----------------
procfs: /proc/acpi/ibm/cmos
+
sysfs device attribute: cmos_command
This feature is mostly used internally by the ACPI firmware to keep the legacy
@@ -707,16 +745,16 @@ The range of valid cmos command numbers is 0 to 21, but not all have an
effect and the behavior varies from model to model. Here is the behavior
on the X40 (tpb is the ThinkPad Buttons utility):
- 0 - Related to "Volume down" key press
- 1 - Related to "Volume up" key press
- 2 - Related to "Mute on" key press
- 3 - Related to "Access IBM" key press
- 4 - Related to "LCD brightness up" key press
- 5 - Related to "LCD brightness down" key press
- 11 - Related to "toggle screen expansion" key press/function
- 12 - Related to "ThinkLight on"
- 13 - Related to "ThinkLight off"
- 14 - Related to "ThinkLight" key press (toggle ThinkLight)
+ - 0 - Related to "Volume down" key press
+ - 1 - Related to "Volume up" key press
+ - 2 - Related to "Mute on" key press
+ - 3 - Related to "Access IBM" key press
+ - 4 - Related to "LCD brightness up" key press
+ - 5 - Related to "LCD brightness down" key press
+ - 11 - Related to "toggle screen expansion" key press/function
+ - 12 - Related to "ThinkLight on"
+ - 13 - Related to "ThinkLight off"
+ - 14 - Related to "ThinkLight" key press (toggle ThinkLight)
The cmos command interface is prone to firmware split-brain problems, as
in newer ThinkPads it is just a compatibility layer. Do not use it, it is
@@ -748,9 +786,10 @@ are aware of the consequences are welcome to enabling it.
Audio mute and microphone mute LEDs are supported, but currently not
visible to userspace. They are used by the snd-hda-intel audio driver.
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
-The available commands are:
+The available commands are::
echo '<LED number> on' >/proc/acpi/ibm/led
echo '<LED number> off' >/proc/acpi/ibm/led
@@ -760,23 +799,24 @@ The <LED number> range is 0 to 15. The set of LEDs that can be
controlled varies from model to model. Here is the common ThinkPad
mapping:
- 0 - power
- 1 - battery (orange)
- 2 - battery (green)
- 3 - UltraBase/dock
- 4 - UltraBay
- 5 - UltraBase battery slot
- 6 - (unknown)
- 7 - standby
- 8 - dock status 1
- 9 - dock status 2
- 10, 11 - (unknown)
- 12 - thinkvantage
- 13, 14, 15 - (unknown)
+ - 0 - power
+ - 1 - battery (orange)
+ - 2 - battery (green)
+ - 3 - UltraBase/dock
+ - 4 - UltraBay
+ - 5 - UltraBase battery slot
+ - 6 - (unknown)
+ - 7 - standby
+ - 8 - dock status 1
+ - 9 - dock status 2
+ - 10, 11 - (unknown)
+ - 12 - thinkvantage
+ - 13, 14, 15 - (unknown)
All of the above can be turned on and off and can be made to blink.
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
The ThinkPad LED sysfs interface is described in detail by the LED class
documentation, in Documentation/leds/leds-class.rst.
@@ -815,7 +855,7 @@ The BEEP method is used internally by the ACPI firmware to provide
audible alerts in various situations. This feature allows the same
sounds to be triggered manually.
-The commands are non-negative integer numbers:
+The commands are non-negative integer numbers::
echo <number> >/proc/acpi/ibm/beep
@@ -823,25 +863,26 @@ The valid <number> range is 0 to 17. Not all numbers trigger sounds
and the sounds vary from model to model. Here is the behavior on the
X40:
- 0 - stop a sound in progress (but use 17 to stop 16)
- 2 - two beeps, pause, third beep ("low battery")
- 3 - single beep
- 4 - high, followed by low-pitched beep ("unable")
- 5 - single beep
- 6 - very high, followed by high-pitched beep ("AC/DC")
- 7 - high-pitched beep
- 9 - three short beeps
- 10 - very long beep
- 12 - low-pitched beep
- 15 - three high-pitched beeps repeating constantly, stop with 0
- 16 - one medium-pitched beep repeating constantly, stop with 17
- 17 - stop 16
+ - 0 - stop a sound in progress (but use 17 to stop 16)
+ - 2 - two beeps, pause, third beep ("low battery")
+ - 3 - single beep
+ - 4 - high, followed by low-pitched beep ("unable")
+ - 5 - single beep
+ - 6 - very high, followed by high-pitched beep ("AC/DC")
+ - 7 - high-pitched beep
+ - 9 - three short beeps
+ - 10 - very long beep
+ - 12 - low-pitched beep
+ - 15 - three high-pitched beeps repeating constantly, stop with 0
+ - 16 - one medium-pitched beep repeating constantly, stop with 17
+ - 17 - stop 16
Temperature sensors
-------------------
procfs: /proc/acpi/ibm/thermal
+
sysfs device attributes: (hwmon "thinkpad") temp*_input
Most ThinkPads include six or more separate temperature sensors but only
@@ -850,10 +891,14 @@ feature shows readings from up to eight different sensors on older
ThinkPads, and up to sixteen different sensors on newer ThinkPads.
For example, on the X40, a typical output may be:
-temperatures: 42 42 45 41 36 -128 33 -128
+
+temperatures:
+ 42 42 45 41 36 -128 33 -128
On the T43/p, a typical output may be:
-temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
+
+temperatures:
+ 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
The mapping of thermal sensors to physical locations varies depending on
system-board model (and thus, on ThinkPad model).
@@ -863,46 +908,53 @@ tries to track down these locations for various models.
Most (newer?) models seem to follow this pattern:
-1: CPU
-2: (depends on model)
-3: (depends on model)
-4: GPU
-5: Main battery: main sensor
-6: Bay battery: main sensor
-7: Main battery: secondary sensor
-8: Bay battery: secondary sensor
-9-15: (depends on model)
+- 1: CPU
+- 2: (depends on model)
+- 3: (depends on model)
+- 4: GPU
+- 5: Main battery: main sensor
+- 6: Bay battery: main sensor
+- 7: Main battery: secondary sensor
+- 8: Bay battery: secondary sensor
+- 9-15: (depends on model)
For the R51 (source: Thomas Gruber):
-2: Mini-PCI
-3: Internal HDD
+
+- 2: Mini-PCI
+- 3: Internal HDD
For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
-2: System board, left side (near PCMCIA slot), reported as HDAPS temp
-3: PCMCIA slot
-9: MCH (northbridge) to DRAM Bus
-10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
- card, under touchpad
-11: Power regulator, underside of system board, below F2 key
+
+- 2: System board, left side (near PCMCIA slot), reported as HDAPS temp
+- 3: PCMCIA slot
+- 9: MCH (northbridge) to DRAM Bus
+- 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
+ card, under touchpad
+- 11: Power regulator, underside of system board, below F2 key
The A31 has a very atypical layout for the thermal sensors
(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
-1: CPU
-2: Main Battery: main sensor
-3: Power Converter
-4: Bay Battery: main sensor
-5: MCH (northbridge)
-6: PCMCIA/ambient
-7: Main Battery: secondary sensor
-8: Bay Battery: secondary sensor
+- 1: CPU
+- 2: Main Battery: main sensor
+- 3: Power Converter
+- 4: Bay Battery: main sensor
+- 5: MCH (northbridge)
+- 6: PCMCIA/ambient
+- 7: Main Battery: secondary sensor
+- 8: Bay Battery: secondary sensor
+
+
+Procfs notes
+^^^^^^^^^^^^
-Procfs notes:
Readings from sensors that are not available return -128.
No commands can be written to this file.
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
+
Sensors that are not available return the ENXIO error. This
status may change at runtime, as there are hotplug thermal
sensors, like those inside the batteries and docks.
@@ -921,6 +973,7 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec
Use it to determine the register holding the fan
speed on some models. To do that, do the following:
+
- make sure the battery is fully charged
- make sure the fan is running
- use above mentioned tool to read out the EC
@@ -941,6 +994,7 @@ LCD brightness control
----------------------
procfs: /proc/acpi/ibm/brightness
+
sysfs backlight device "thinkpad_screen"
This feature allows software control of the LCD brightness on ThinkPad
@@ -985,15 +1039,17 @@ brightness_enable=0 forces it to be disabled. brightness_enable=1
forces it to be enabled when available, even if the standard ACPI
interface is also available.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
- The available commands are:
+The available commands are::
echo up >/proc/acpi/ibm/brightness
echo down >/proc/acpi/ibm/brightness
echo 'level <level>' >/proc/acpi/ibm/brightness
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
The interface is implemented through the backlight sysfs class, which is
poorly documented at this time.
@@ -1038,6 +1094,7 @@ Volume control (Console Audio control)
--------------------------------------
procfs: /proc/acpi/ibm/volume
+
ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC"
NOTE: by default, the volume control interface operates in read-only
@@ -1053,7 +1110,8 @@ Software volume control should be done only in the main AC97/HDA
mixer.
-About the ThinkPad Console Audio control:
+About the ThinkPad Console Audio control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ThinkPads have a built-in amplifier and muting circuit that drives the
console headphone and speakers. This circuit is after the main AC97
@@ -1092,13 +1150,14 @@ normal key presses to the operating system (thinkpad-acpi is not
involved).
-The ThinkPad-ACPI volume control:
+The ThinkPad-ACPI volume control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The preferred way to interact with the Console Audio control is the
ALSA interface.
The legacy procfs interface allows one to read the current state,
-and if volume control is enabled, accepts the following commands:
+and if volume control is enabled, accepts the following commands::
echo up >/proc/acpi/ibm/volume
echo down >/proc/acpi/ibm/volume
@@ -1137,13 +1196,15 @@ Fan control and monitoring: fan speed, fan enable/disable
---------------------------------------------------------
procfs: /proc/acpi/ibm/fan
-sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1,
- pwm1_enable, fan2_input
+
+sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, pwm1_enable, fan2_input
+
sysfs hwmon driver attributes: fan_watchdog
-NOTE NOTE NOTE: fan control operations are disabled by default for
-safety reasons. To enable them, the module parameter "fan_control=1"
-must be given to thinkpad-acpi.
+NOTE NOTE NOTE:
+ fan control operations are disabled by default for
+ safety reasons. To enable them, the module parameter "fan_control=1"
+ must be given to thinkpad-acpi.
This feature attempts to show the current fan speed, control mode and
other fan data that might be available. The speed is read directly
@@ -1154,7 +1215,8 @@ value on other models.
Some Lenovo ThinkPads support a secondary fan. This fan cannot be
controlled separately, it shares the main fan control.
-Fan levels:
+Fan levels
+^^^^^^^^^^
Most ThinkPad fans work in "levels" at the firmware interface. Level 0
stops the fan. The higher the level, the higher the fan speed, although
@@ -1209,9 +1271,10 @@ therefore, not suitable to protect against fan mode changes made through
means other than the "enable", "disable", and "level" procfs fan
commands, or the hwmon fan control sysfs interface.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
-The fan may be enabled or disabled with the following commands:
+The fan may be enabled or disabled with the following commands::
echo enable >/proc/acpi/ibm/fan
echo disable >/proc/acpi/ibm/fan
@@ -1219,7 +1282,7 @@ The fan may be enabled or disabled with the following commands:
Placing a fan on level 0 is the same as disabling it. Enabling a fan
will try to place it in a safe level if it is too slow or disabled.
-The fan level can be controlled with the command:
+The fan level can be controlled with the command::
echo 'level <level>' > /proc/acpi/ibm/fan
@@ -1231,7 +1294,7 @@ compatibility.
On the X31 and X40 (and ONLY on those models), the fan speed can be
controlled to a certain degree. Once the fan is running, it can be
-forced to run faster or slower with the following command:
+forced to run faster or slower with the following command::
echo 'speed <speed>' > /proc/acpi/ibm/fan
@@ -1241,13 +1304,14 @@ effect or the fan speed eventually settles somewhere in that range. The
fan cannot be stopped or started with this command. This functionality
is incomplete, and not available through the sysfs interface.
-To program the safety watchdog, use the "watchdog" command.
+To program the safety watchdog, use the "watchdog" command::
echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
If you want to disable the watchdog, use 0 as the interval.
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
The sysfs interface follows the hwmon subsystem guidelines for the most
part, and the exception is the fan safety watchdog.
@@ -1261,10 +1325,10 @@ to the firmware).
Features not yet implemented by the driver return ENOSYS.
hwmon device attribute pwm1_enable:
- 0: PWM offline (fan is set to full-speed mode)
- 1: Manual PWM control (use pwm1 to set fan level)
- 2: Hardware PWM control (EC "auto" mode)
- 3: reserved (Software PWM control, not implemented yet)
+ - 0: PWM offline (fan is set to full-speed mode)
+ - 1: Manual PWM control (use pwm1 to set fan level)
+ - 2: Hardware PWM control (EC "auto" mode)
+ - 3: reserved (Software PWM control, not implemented yet)
Modes 0 and 2 are not supported by all ThinkPads, and the
driver is not always able to detect this. If it does know a
@@ -1304,7 +1368,9 @@ WAN
---
procfs: /proc/acpi/ibm/wan
+
sysfs device attribute: wwan_enable (deprecated)
+
sysfs rfkill class: switch "tpacpi_wwan_sw"
This feature shows the presence and current state of the built-in
@@ -1316,22 +1382,24 @@ so it is kept across reboots and power-off.
It was tested on a Lenovo ThinkPad X60. It should probably work on other
ThinkPad models which come with this module installed.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
-If the W-WAN card is installed, the following commands can be used:
+If the W-WAN card is installed, the following commands can be used::
echo enable > /proc/acpi/ibm/wan
echo disable > /proc/acpi/ibm/wan
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
If the W-WAN card is installed, it can be enabled /
disabled through the "wwan_enable" thinkpad-acpi device
attribute, and its current status can also be queried.
enable:
- 0: disables WWAN card / WWAN card is disabled
- 1: enables WWAN card / WWAN card is enabled.
+ - 0: disables WWAN card / WWAN card is disabled
+ - 1: enables WWAN card / WWAN card is enabled.
Note: this interface has been superseded by the generic rfkill
class. It has been deprecated, and it will be removed in year
@@ -1354,7 +1422,8 @@ sysfs rfkill class: switch "tpacpi_uwb_sw"
This feature exports an rfkill controller for the UWB device, if one is
present and enabled in the BIOS.
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
rfkill controller switch "tpacpi_uwb_sw": refer to
Documentation/rfkill.txt for details.
@@ -1368,11 +1437,11 @@ This sysfs attribute controls the keyboard "face" that will be shown on the
Lenovo X1 Carbon 2nd gen (2014)'s adaptive keyboard. The value can be read
and set.
-1 = Home mode
-2 = Web-browser mode
-3 = Web-conference mode
-4 = Function mode
-5 = Layflat mode
+- 1 = Home mode
+- 2 = Web-browser mode
+- 3 = Web-conference mode
+- 4 = Function mode
+- 5 = Layflat mode
For more details about which buttons will appear depending on the mode, please
review the laptop's user guide:
@@ -1382,13 +1451,13 @@ Multiple Commands, Module Parameters
------------------------------------
Multiple commands can be written to the proc files in one shot by
-separating them with commas, for example:
+separating them with commas, for example::
echo enable,0xffff > /proc/acpi/ibm/hotkey
echo lcd_disable,crt_enable > /proc/acpi/ibm/video
Commands can also be specified when loading the thinkpad-acpi module,
-for example:
+for example::
modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
@@ -1397,14 +1466,16 @@ Enabling debugging output
-------------------------
The module takes a debug parameter which can be used to selectively
-enable various classes of debugging output, for example:
+enable various classes of debugging output, for example::
modprobe thinkpad_acpi debug=0xffff
will enable all debugging output classes. It takes a bitmask, so
to enable more than one output class, just add their values.
+ ============= ======================================
Debug bitmask Description
+ ============= ======================================
0x8000 Disclose PID of userspace programs
accessing some functions of the driver
0x0001 Initialization and probing
@@ -1415,6 +1486,7 @@ to enable more than one output class, just add their values.
0x0010 Fan control
0x0020 Backlight brightness
0x0040 Audio mixer/volume control
+ ============= ======================================
There is also a kernel build option to enable more debugging
information, which may be necessary to debug driver problems.
@@ -1432,8 +1504,10 @@ the module parameter force_load=1. Regardless of whether this works or
not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
-Sysfs interface changelog:
+Sysfs interface changelog
+^^^^^^^^^^^^^^^^^^^^^^^^^
+========= ===============================================================
0x000100: Initial sysfs support, as a single platform driver and
device.
0x000200: Hot key support for 32 hot keys, and radio slider switch
@@ -1485,3 +1559,4 @@ Sysfs interface changelog:
0x030000: Thermal and fan sysfs attributes were moved to the hwmon
device instead of being attached to the backing platform
device.
+========= ===============================================================
diff --git a/Documentation/laptops/toshiba_haps.txt b/Documentation/laptops/toshiba_haps.rst
similarity index 60%
rename from Documentation/laptops/toshiba_haps.txt
rename to Documentation/laptops/toshiba_haps.rst
index 0c1d88dedbde..11dfc428c080 100644
--- a/Documentation/laptops/toshiba_haps.txt
+++ b/Documentation/laptops/toshiba_haps.rst
@@ -1,18 +1,19 @@
-Kernel driver toshiba_haps
+====================================
Toshiba HDD Active Protection Sensor
====================================
+Kernel driver: toshiba_haps
+
Author: Azael Avalos <coproscefalo@gmail.com>
-0. Contents
------------
+.. 0. Contents
-1. Description
-2. Interface
-3. Accelerometer axes
-4. Supported devices
-5. Usage
+ 1. Description
+ 2. Interface
+ 3. Accelerometer axes
+ 4. Supported devices
+ 5. Usage
1. Description
@@ -32,17 +33,20 @@ file to set the desired protection level or sensor sensibility.
------------
This device comes with 3 methods:
-_STA - Checks existence of the device, returning Zero if the device does not
+
+==== =====================================================================
+_STA Checks existence of the device, returning Zero if the device does not
exists or is not supported.
-PTLV - Sets the desired protection level.
-RSSS - Shuts down the HDD protection interface for a few seconds,
+PTLV Sets the desired protection level.
+RSSS Shuts down the HDD protection interface for a few seconds,
then restores normal operation.
+==== =====================================================================
Note:
-The presence of Solid State Drives (SSD) can make this driver to fail loading,
-given the fact that such drives have no movable parts, and thus, not requiring
-any "protection" as well as failing during the evaluation of the _STA method
-found under this device.
+ The presence of Solid State Drives (SSD) can make this driver to fail loading,
+ given the fact that such drives have no movable parts, and thus, not requiring
+ any "protection" as well as failing during the evaluation of the _STA method
+ found under this device.
3. Accelerometer axes
@@ -66,11 +70,18 @@ conventional HDD and not only SSD, or a combination of both HDD and SSD.
--------
The sysfs files under /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/ are:
-protection_level - The protection_level is readable and writeable, and
+
+================ ============================================================
+protection_level The protection_level is readable and writeable, and
provides a way to let userspace query the current protection
level, as well as set the desired protection level, the
available protection levels are:
- 0 - Disabled | 1 - Low | 2 - Medium | 3 - High
-reset_protection - The reset_protection entry is writeable only, being "1"
+
+ ============ ======= ========== ========
+ 0 - Disabled 1 - Low 2 - Medium 3 - High
+ ============ ======= ========== ========
+
+reset_protection The reset_protection entry is writeable only, being "1"
the only parameter it accepts, it is used to trigger
a reset of the protection interface.
+================ ============================================================
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index 749322060f10..c5f0d44433a2 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -102,7 +102,7 @@ Changing this takes effect whenever an application requests memory.
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.txt.
+information on block I/O debugging is in Documentation/laptops/laptop-mode.rst.
==============================================================
@@ -286,7 +286,7 @@ shared memory segment using hugetlb page.
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.txt.
+controlled by this knob are discussed in Documentation/laptops/laptop-mode.rst.
==============================================================
diff --git a/MAINTAINERS b/MAINTAINERS
index 73000e7d7f19..c63b1b9cbed4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14753,7 +14753,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.txt
+F: Documentation/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 466ebd84ad17..bb734066075f 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.txt>, and say Y or M here.
+ <file:Documentation/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 5d5cc6111081..e53c915761e7 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.txt> for more information.
+ Read <file:Documentation/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.txt> and
+ <file:Documentation/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
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