* [PATCH 05/43] docs: powerpc: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Linas Vepstas, Russell Currey, Sam Bobroff,
Oliver O'Halloran, Bjorn Helgaas, Benjamin Herrenschmidt,
Paul Mackerras, Michael Ellerman, Frederic Barrat,
Andrew Donnellan, Manoj N. Kumar, Matthew R. Ochs, Uma Krishnan,
Qiang Zhao, Li Yang, Greg Kroah-Hartman, Jiri Slaby, linux-pci,
linuxppc-dev, linux-scsi, linux-arm-kernel, Andrew Donnellan
In-Reply-To: <cover.1561723979.git.mchehab+samsung@kernel.org>
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
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: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
Documentation/PCI/pci-error-recovery.rst | 23 ++-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +++-
.../{cpu_families.txt => cpu_families.rst} | 23 +--
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 ++++--
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 ++++++------
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +++++++------
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 ++++++------
Documentation/powerpc/index.rst | 34 ++++
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
Documentation/powerpc/ptrace.rst | 156 ++++++++++++++++++
Documentation/powerpc/ptrace.txt | 151 -----------------
.../{qe_firmware.txt => qe_firmware.rst} | 37 +++--
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 ++--
...al_memory.txt => transactional_memory.rst} | 45 ++---
MAINTAINERS | 6 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
26 files changed, 584 insertions(+), 427 deletions(-)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
create mode 100644 Documentation/powerpc/ptrace.rst
delete mode 100644 Documentation/powerpc/ptrace.txt
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..acc21ecca322 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
.. note::
Implementation details for the powerpc platform are discussed in
- the file Documentation/powerpc/eeh-pci-error-recovery.txt
+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
@@ -422,3 +422,24 @@ That is, the recovery API only requires that:
- drivers/net/cxgb3
- drivers/net/s2io.c
- drivers/net/qlge
+
+>>> As of this writing, there is a growing list of device drivers with
+>>> patches implementing error recovery. Not all of these patches are in
+>>> mainline yet. These may be used as "examples":
+>>>
+>>> drivers/scsi/ipr
+>>> drivers/scsi/sym53c8xx_2
+>>> drivers/scsi/qla2xxx
+>>> drivers/scsi/lpfc
+>>> drivers/next/bnx2.c
+>>> drivers/next/e100.c
+>>> drivers/net/e1000
+>>> drivers/net/e1000e
+>>> drivers/net/ixgb
+>>> drivers/net/ixgbe
+>>> drivers/net/cxgb3
+>>> drivers/net/s2io.c
+>>> drivers/net/qlge
+
+The End
+-------
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+ - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -28,7 +32,7 @@ Introduction
responsible for the initialization of the adapter, setting up the
special path for user space access, and performing error recovery. It
communicates directly the Flash Accelerator Functional Unit (AFU)
- as described in Documentation/powerpc/cxl.txt.
+ as described in Documentation/powerpc/cxl.rst.
The cxlflash driver supports two, mutually exclusive, modes of
operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
if it points to cache inhibited (CI) memory. Currently Linux has no way to
disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
writing the DAWR.
To double check the DAWR is working, run this kernel selftest:
+
tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 0c41d6d463f3..d7fa7c35dd12 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..1ff17268db46
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+:orphan:
+
+=======
+powerpc
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ bootwrapper
+ cpu_families
+ cpu_features
+ cxl
+ cxlflash
+ dawr-power9
+ dscr
+ eeh-pci-error-recovery
+ firmware-assisted-dump
+ hvcs
+ isa-versions
+ mpc52xx
+ pci_iov_resource_on_powernv
+ pmu-ebb
+ ptrace
+ qe_firmware
+ syscall64-abi
+ transactional_memory
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -60,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -73,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.rst b/Documentation/powerpc/ptrace.rst
new file mode 100644
index 000000000000..864d4b6dddd1
--- /dev/null
+++ b/Documentation/powerpc/ptrace.rst
@@ -0,0 +1,156 @@
+======
+Ptrace
+======
+
+GDB intends to support the following hardware debug features of BookE
+processors:
+
+4 hardware breakpoints (IAC)
+2 hardware watchpoints (read, write and read-write) (DAC)
+2 value conditions for the hardware watchpoints (DVC)
+
+For that, we need to extend ptrace so that GDB can query and set these
+resources. Since we're extending, we're trying to create an interface
+that's extendable and that covers both BookE and server processors, so
+that GDB doesn't need to special-case each of them. We added the
+following 3 new ptrace requests.
+
+1. PTRACE_PPC_GETHWDEBUGINFO
+============================
+
+Query for GDB to discover the hardware debug features. The main info to
+be returned here is the minimum alignment for the hardware watchpoints.
+BookE processors don't have restrictions here, but server processors have
+an 8-byte alignment restriction for hardware watchpoints. We'd like to avoid
+adding special cases to GDB based on what it sees in AUXV.
+
+Since we're at it, we added other useful info that the kernel can return to
+GDB: this query will return the number of hardware breakpoints, hardware
+watchpoints and whether it supports a range of addresses and a condition.
+The query will fill the following structure provided by the requesting process::
+
+ struct ppc_debug_info {
+ unit32_t version;
+ unit32_t num_instruction_bps;
+ unit32_t num_data_bps;
+ unit32_t num_condition_regs;
+ unit32_t data_bp_alignment;
+ unit32_t sizeof_condition; /* size of the DVC register */
+ uint64_t features; /* bitmask of the individual flags */
+ };
+
+features will have bits indicating whether there is support for::
+
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+
+2. PTRACE_SETHWDEBUG
+
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
+
+ struct ppc_hw_breakpoint {
+ uint32_t version;
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ uint32_t trigger_type; /* only some combinations allowed */
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
+ uint32_t addr_mode; /* address match mode */
+
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ uint32_t condition_mode; /* break/watchpoint condition flags */
+
+ uint64_t addr;
+ uint64_t addr2;
+ uint64_t condition_value;
+ };
+
+A request specifies one event, not necessarily just one register to be set.
+For instance, if the request is for a watchpoint with a condition, both the
+DAC and DVC registers will be set in the same request.
+
+With this GDB can ask for all kinds of hardware breakpoints and watchpoints
+that the BookE supports. COMEFROM breakpoints available in server processors
+are not contemplated, but that is out of the scope of this work.
+
+ptrace will return an integer (handle) uniquely identifying the breakpoint or
+watchpoint just created. This integer will be used in the PTRACE_DELHWDEBUG
+request to ask for its removal. Return -ENOSPC if the requested breakpoint
+can't be allocated on the registers.
+
+Some examples of using the structure to:
+
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+3. PTRACE_DELHWDEBUG
+
+Takes an integer which identifies an existing breakpoint or watchpoint
+(i.e., the value returned from PTRACE_SETHWDEBUG), and deletes the
+corresponding breakpoint or watchpoint..
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.txt
deleted file mode 100644
index 99c5ce88d0fe..000000000000
--- a/Documentation/powerpc/ptrace.txt
+++ /dev/null
@@ -1,151 +0,0 @@
-GDB intends to support the following hardware debug features of BookE
-processors:
-
-4 hardware breakpoints (IAC)
-2 hardware watchpoints (read, write and read-write) (DAC)
-2 value conditions for the hardware watchpoints (DVC)
-
-For that, we need to extend ptrace so that GDB can query and set these
-resources. Since we're extending, we're trying to create an interface
-that's extendable and that covers both BookE and server processors, so
-that GDB doesn't need to special-case each of them. We added the
-following 3 new ptrace requests.
-
-1. PTRACE_PPC_GETHWDEBUGINFO
-
-Query for GDB to discover the hardware debug features. The main info to
-be returned here is the minimum alignment for the hardware watchpoints.
-BookE processors don't have restrictions here, but server processors have
-an 8-byte alignment restriction for hardware watchpoints. We'd like to avoid
-adding special cases to GDB based on what it sees in AUXV.
-
-Since we're at it, we added other useful info that the kernel can return to
-GDB: this query will return the number of hardware breakpoints, hardware
-watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
-
-struct ppc_debug_info {
- unit32_t version;
- unit32_t num_instruction_bps;
- unit32_t num_data_bps;
- unit32_t num_condition_regs;
- unit32_t data_bp_alignment;
- unit32_t sizeof_condition; /* size of the DVC register */
- uint64_t features; /* bitmask of the individual flags */
-};
-
-features will have bits indicating whether there is support for:
-
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
-
-2. PTRACE_SETHWDEBUG
-
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
-
-struct ppc_hw_breakpoint {
- uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
- uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
- uint32_t addr_mode; /* address match mode */
-
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
- uint32_t condition_mode; /* break/watchpoint condition flags */
-
- uint64_t addr;
- uint64_t addr2;
- uint64_t condition_value;
-};
-
-A request specifies one event, not necessarily just one register to be set.
-For instance, if the request is for a watchpoint with a condition, both the
-DAC and DVC registers will be set in the same request.
-
-With this GDB can ask for all kinds of hardware breakpoints and watchpoints
-that the BookE supports. COMEFROM breakpoints available in server processors
-are not contemplated, but that is out of the scope of this work.
-
-ptrace will return an integer (handle) uniquely identifying the breakpoint or
-watchpoint just created. This integer will be used in the PTRACE_DELHWDEBUG
-request to ask for its removal. Return -ENOSPC if the requested breakpoint
-can't be allocated on the registers.
-
-Some examples of using the structure to:
-
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-3. PTRACE_DELHWDEBUG
-
-Takes an integer which identifies an existing breakpoint or watchpoint
-(i.e., the value returned from PTRACE_SETHWDEBUG), and deletes the
-corresponding breakpoint or watchpoint..
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 9458cdaa5b4b..bad1bbb668bc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4416,7 +4416,7 @@ F: arch/powerpc/platforms/powernv/pci-cxl.c
F: drivers/misc/cxl/
F: include/misc/cxl*
F: include/uapi/misc/cxl.h
-F: Documentation/powerpc/cxl.txt
+F: Documentation/powerpc/cxl.rst
F: Documentation/ABI/testing/sysfs-class-cxl
CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4427,7 +4427,7 @@ L: linux-scsi@vger.kernel.org
S: Supported
F: drivers/scsi/cxlflash/
F: include/uapi/scsi/cxlflash_ioctl.h
-F: Documentation/powerpc/cxlflash.txt
+F: Documentation/powerpc/cxlflash.rst
CYBERPRO FB DRIVER
M: Russell King <linux@armlinux.org.uk>
@@ -12276,7 +12276,7 @@ F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
-F: Documentation/powerpc/eeh-pci-error-recovery.txt
+F: Documentation/powerpc/eeh-pci-error-recovery.rst
F: arch/powerpc/kernel/eeh*.c
F: arch/powerpc/platforms/*/eeh*.c
F: arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index 4d4fd2ad5b7d..d6f48fc845ca 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -910,7 +910,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
*
* Call convention:
*
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
*
* For hypercalls, the register convention is as follows:
* r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index ba38c4bb2a88..417df7e19281 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -430,7 +430,7 @@ static void qe_upload_microcode(const void *base,
/*
* Upload a microcode to the I-RAM at a specific address.
*
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
* uploading.
*
* Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
* using the 2.6 Linux kernel kref construct.
*
* For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
*/
#include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
/* Structure that defines QE firmware binary files.
*
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
* fields.
*/
struct qe_firmware {
--
2.21.0
^ permalink raw reply related
* [PATCH 25/43] docs: laptops: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Arnd Bergmann, Greg Kroah-Hartman, Darren Hart,
Andy Shevchenko, platform-driver-x86, Andy Shevchenko
In-Reply-To: <cover.1561723979.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>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
---
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 e5eb04f673ae..92d335837c52 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4373,7 +4373,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 cc8a52d2ce83..8aa3d0bd5b80 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14830,7 +14830,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 c318501773bc..1f616844fb87 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -448,7 +448,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"
@@ -500,7 +500,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
* [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, MyungJoo Ham, Chanwoo Choi, Rafael J. Wysocki,
Len Brown, linux-acpi
In-Reply-To: <cover.1561723979.git.mchehab+samsung@kernel.org>
The intel-int3496.txt file is a documentation for an ACPI driver.
There's no reason to keep it on a separate directory.
So, instead of keeping it on some random location, move it
to a sub-directory inside the ACPI documentation dir,
renaming it to .rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/extcon-intel-int3496.rst} | 14 ++++++++++----
Documentation/firmware-guide/acpi/index.rst | 1 +
MAINTAINERS | 6 +++---
3 files changed, 14 insertions(+), 7 deletions(-)
rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
similarity index 66%
rename from Documentation/extcon/intel-int3496.txt
rename to Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
index 8155dbc7fad3..5137ca834b54 100644
--- a/Documentation/extcon/intel-int3496.txt
+++ b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
@@ -1,5 +1,6 @@
+=====================================================
Intel INT3496 ACPI device extcon driver documentation
------------------------------------------------------
+=====================================================
The Intel INT3496 ACPI device extcon driver is a driver for ACPI
devices with an acpi-id of INT3496, such as found for example on
@@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
The ACPI devices exposes this functionality by returning an array with up
to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
-Index 0: The input gpio for the id-pin, this is always present and valid
-Index 1: The output gpio for enabling Vbus output from the device to the otg
+======= =====================================================================
+Index 0 The input gpio for the id-pin, this is always present and valid
+Index 1 The output gpio for enabling Vbus output from the device to the otg
port, write 1 to enable the Vbus output (this gpio descriptor may
be absent or invalid)
-Index 2: The output gpio for muxing of the data pins between the USB host and
+Index 2 The output gpio for muxing of the data pins between the USB host and
the USB peripheral controller, write 1 to mux to the peripheral
controller
+======= =====================================================================
There is a mapping between indices and GPIO connection IDs as follows
+
+ ======= =======
id index 0
vbus index 1
mux index 2
+ ======= =======
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index ae609eec4679..90c90d42d9ad 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -24,3 +24,4 @@ ACPI Support
acpi-lid
lpit
video_extension
+ extcon-intel-int3496
diff --git a/MAINTAINERS b/MAINTAINERS
index fd6fab0dec77..2cf8abf6d48e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -321,7 +321,7 @@ F: drivers/pnp/pnpacpi/
F: include/linux/acpi.h
F: include/linux/fwnode.h
F: include/acpi/
-F: Documentation/acpi/
+F: Documentation/firmware-guide/acpi/
F: Documentation/ABI/testing/sysfs-bus-acpi
F: Documentation/ABI/testing/configfs-acpi
F: drivers/pci/*acpi*
@@ -4896,7 +4896,7 @@ S: Maintained
F: Documentation/
F: scripts/kernel-doc
X: Documentation/ABI/
-X: Documentation/acpi/
+X: Documentation/firmware-guide/acpi/
X: Documentation/devicetree/
X: Documentation/i2c/
X: Documentation/media/
@@ -6073,7 +6073,7 @@ S: Maintained
F: drivers/extcon/
F: include/linux/extcon/
F: include/linux/extcon.h
-F: Documentation/extcon/
+F: Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
F: Documentation/devicetree/bindings/extcon/
EXYNOS DP DRIVER
--
2.21.0
^ permalink raw reply related
* [PATCH 36/43] docs: rapidio: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Matt Porter, Alexandre Bounine
In-Reply-To: <cover.1561723979.git.mchehab+samsung@kernel.org>
Rename the rapidio documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/rapidio/index.rst | 15 +++++
.../{mport_cdev.txt => mport_cdev.rst} | 47 ++++++-------
.../rapidio/{rapidio.txt => rapidio.rst} | 39 +++++++----
.../rapidio/{rio_cm.txt => rio_cm.rst} | 66 ++++++++++++-------
.../rapidio/{sysfs.txt => sysfs.rst} | 4 ++
.../rapidio/{tsi721.txt => tsi721.rst} | 45 ++++++++-----
drivers/rapidio/Kconfig | 2 +-
7 files changed, 141 insertions(+), 77 deletions(-)
create mode 100644 Documentation/rapidio/index.rst
rename Documentation/rapidio/{mport_cdev.txt => mport_cdev.rst} (84%)
rename Documentation/rapidio/{rapidio.txt => rapidio.rst} (97%)
rename Documentation/rapidio/{rio_cm.txt => rio_cm.rst} (76%)
rename Documentation/rapidio/{sysfs.txt => sysfs.rst} (75%)
rename Documentation/rapidio/{tsi721.txt => tsi721.rst} (79%)
diff --git a/Documentation/rapidio/index.rst b/Documentation/rapidio/index.rst
new file mode 100644
index 000000000000..ab7b5541b346
--- /dev/null
+++ b/Documentation/rapidio/index.rst
@@ -0,0 +1,15 @@
+:orphan:
+
+===========================
+The Linux RapidIO Subsystem
+===========================
+
+.. toctree::
+ :maxdepth: 1
+
+ rapidio
+ sysfs
+
+ tsi721
+ mport_cdev
+ rio_cm
diff --git a/Documentation/rapidio/mport_cdev.txt b/Documentation/rapidio/mport_cdev.rst
similarity index 84%
rename from Documentation/rapidio/mport_cdev.txt
rename to Documentation/rapidio/mport_cdev.rst
index a53f786ee2e9..df77a7f7be7d 100644
--- a/Documentation/rapidio/mport_cdev.txt
+++ b/Documentation/rapidio/mport_cdev.rst
@@ -1,13 +1,9 @@
+==================================================================
RapidIO subsystem mport character device driver (rio_mport_cdev.c)
==================================================================
-Version History:
-----------------
- 1.0.0 - Initial driver release.
-
-==================================================================
-
-I. Overview
+1. Overview
+===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Freescale,
@@ -29,40 +25,41 @@ Using available set of ioctl commands user-space applications can perform
following RapidIO bus and subsystem operations:
- Reads and writes from/to configuration registers of mport devices
- (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
+ (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
- Reads and writes from/to configuration registers of remote RapidIO devices.
This operations are defined as RapidIO Maintenance reads/writes in RIO spec.
- (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
+ (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
- Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET)
- Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET)
- Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET)
- Query capabilities and RapidIO link configuration of mport devices
- (RIO_MPORT_GET_PROPERTIES)
+ (RIO_MPORT_GET_PROPERTIES)
- Enable/Disable reporting of RapidIO doorbell events to user-space applications
- (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
+ (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
- Enable/Disable reporting of RIO port-write events to user-space applications
- (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
+ (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
- Query/Control type of events reported through this driver: doorbells,
port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK)
- Configure/Map mport's outbound requests window(s) for specific size,
RapidIO destination ID, hopcount and request type
- (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
+ (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
- Configure/Map mport's inbound requests window(s) for specific size,
RapidIO base address and local memory base address
- (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
+ (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
- Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers
to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA)
- Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER).
Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data
transfer modes.
- Check/Wait for completion of asynchronous DMA data transfer
- (RIO_WAIT_FOR_ASYNC)
+ (RIO_WAIT_FOR_ASYNC)
- Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL).
This allows implementation of various RapidIO fabric enumeration algorithms
as user-space applications while using remaining functionality provided by
kernel RapidIO subsystem.
-II. Hardware Compatibility
+2. Hardware Compatibility
+=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
@@ -78,29 +75,35 @@ functionality of their platform when planning to use this driver:
specific DMA engine support and therefore DMA data transfers mport_cdev driver
are not available.
-III. Module parameters
+3. Module parameters
+====================
-- 'dma_timeout' - DMA transfer completion timeout (in msec, default value 3000).
+- 'dma_timeout'
+ - DMA transfer completion timeout (in msec, default value 3000).
This parameter set a maximum completion wait time for SYNC mode DMA
transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.
-- 'dbg_level' - This parameter allows to control amount of debug information
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional blocks.
For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-IV. Known problems
+4. Known problems
+=================
None.
-V. User-space Applications and API
+5. User-space Applications and API
+==================================
API library and applications that use this device driver are available from
RapidIO.org.
-VI. TODO List
+6. TODO List
+============
- Add support for sending/receiving "raw" RapidIO messaging packets.
- Add memory mapped DMA data transfers as an option when RapidIO-specific DMA
diff --git a/Documentation/rapidio/rapidio.txt b/Documentation/rapidio/rapidio.rst
similarity index 97%
rename from Documentation/rapidio/rapidio.txt
rename to Documentation/rapidio/rapidio.rst
index 28fbd877f85a..fb8942d3ba85 100644
--- a/Documentation/rapidio/rapidio.txt
+++ b/Documentation/rapidio/rapidio.rst
@@ -1,6 +1,6 @@
- The Linux RapidIO Subsystem
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============
+Introduction
+============
The RapidIO standard is a packet-based fabric interconnect standard designed for
use in embedded systems. Development of the RapidIO standard is directed by the
@@ -11,7 +11,7 @@ This document describes the basics of the Linux RapidIO subsystem and provides
information on its major components.
1 Overview
-----------
+==========
Because the RapidIO subsystem follows the Linux device model it is integrated
into the kernel similarly to other buses by defining RapidIO-specific device and
@@ -22,7 +22,7 @@ architecture-specific interfaces that provide support for common RapidIO
subsystem operations.
2. Core Components
-------------------
+==================
A typical RapidIO network is a combination of endpoints and switches.
Each of these components is represented in the subsystem by an associated data
@@ -30,6 +30,7 @@ structure. The core logical components of the RapidIO subsystem are defined
in include/linux/rio.h file.
2.1 Master Port
+---------------
A master port (or mport) is a RapidIO interface controller that is local to the
processor executing the Linux code. A master port generates and receives RapidIO
@@ -46,6 +47,7 @@ includes rio_ops data structure which contains pointers to hardware specific
implementations of RapidIO functions.
2.2 Device
+----------
A RapidIO device is any endpoint (other than mport) or switch in the network.
All devices are presented in the RapidIO subsystem by corresponding rio_dev data
@@ -53,6 +55,7 @@ structure. Devices form one global device list and per-network device lists
(depending on number of available mports and networks).
2.3 Switch
+----------
A RapidIO switch is a special class of device that routes packets between its
ports towards their final destination. The packet destination port within a
@@ -66,6 +69,7 @@ specific switch drivers that are designed to provide hardware-specific
implementation of common switch management routines.
2.4 Network
+-----------
A RapidIO network is a combination of interconnected endpoint and switch devices.
Each RapidIO network known to the system is represented by corresponding rio_net
@@ -74,11 +78,13 @@ ports that form the same network. It also contains a pointer to the default
master port that is used to communicate with devices within the network.
2.5 Device Drivers
+------------------
RapidIO device-specific drivers follow Linux Kernel Driver Model and are
intended to support specific RapidIO devices attached to the RapidIO network.
2.6 Subsystem Interfaces
+------------------------
RapidIO interconnect specification defines features that may be used to provide
one or more common service layers for all participating RapidIO devices. These
@@ -90,7 +96,7 @@ subsystem interfaces. This allows to have multiple common services attached to
the same device without blocking attachment of a device-specific driver.
3. Subsystem Initialization
----------------------------
+===========================
In order to initialize the RapidIO subsystem, a platform must initialize and
register at least one master port within the RapidIO network. To register mport
@@ -105,7 +111,7 @@ RapidIO subsystem can be configured to be built as a statically linked or
modular component of the kernel (see details below).
4. Enumeration and Discovery
-----------------------------
+============================
4.1 Overview
------------
@@ -168,14 +174,16 @@ on RapidIO subsystem build configuration:
(b) If the RapidIO subsystem core is built as a loadable module, in addition
to the method shown above, the host destination ID(s) can be specified using
traditional methods of passing module parameter "hdid=" during its loading:
+
- from command line: "modprobe rapidio hdid=-1,7", or
- from modprobe configuration file using configuration command "options",
like in this example: "options rapidio hdid=-1,7". An example of modprobe
configuration file is provided in the section below.
- NOTES:
+NOTES:
(i) if "hdid=" parameter is omitted all available mport will be assigned
destination ID = -1;
+
(ii) the "hdid=" parameter in systems with multiple mports can have
destination ID assignments omitted from the end of list (default = -1).
@@ -317,8 +325,7 @@ must ensure that they are loaded before the enumeration/discovery starts.
This process can be automated by specifying pre- or post- dependencies in the
RapidIO-specific modprobe configuration file as shown in the example below.
- File /etc/modprobe.d/rapidio.conf:
- ----------------------------------
+File /etc/modprobe.d/rapidio.conf::
# Configure RapidIO subsystem modules
@@ -335,17 +342,21 @@ RapidIO-specific modprobe configuration file as shown in the example below.
--------------------------
-NOTE: In the example above, one of "softdep" commands must be removed or
-commented out to keep required module loading sequence.
+NOTE:
+ In the example above, one of "softdep" commands must be removed or
+ commented out to keep required module loading sequence.
-A. References
--------------
+5. References
+=============
[1] RapidIO Trade Association. RapidIO Interconnect Specifications.
http://www.rapidio.org.
+
[2] Rapidio TA. Technology Comparisons.
http://www.rapidio.org/education/technology_comparisons/
+
[3] RapidIO support for Linux.
http://lwn.net/Articles/139118/
+
[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005
http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf
diff --git a/Documentation/rapidio/rio_cm.txt b/Documentation/rapidio/rio_cm.rst
similarity index 76%
rename from Documentation/rapidio/rio_cm.txt
rename to Documentation/rapidio/rio_cm.rst
index 27aa401f1126..5294430a7a74 100644
--- a/Documentation/rapidio/rio_cm.txt
+++ b/Documentation/rapidio/rio_cm.rst
@@ -1,13 +1,10 @@
+==========================================================================
RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
==========================================================================
-Version History:
-----------------
- 1.0.0 - Initial driver release.
-==========================================================================
-
-I. Overview
+1. Overview
+===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Prodrive Technologies,
@@ -41,79 +38,98 @@ in /dev directory common for all registered RapidIO mport devices.
Following ioctl commands are available to user-space applications:
-- RIO_CM_MPORT_GET_LIST : Returns to caller list of local mport devices that
+- RIO_CM_MPORT_GET_LIST:
+ Returns to caller list of local mport devices that
support messaging operations (number of entries up to RIO_MAX_MPORTS).
Each list entry is combination of mport's index in the system and RapidIO
destination ID assigned to the port.
-- RIO_CM_EP_GET_LIST_SIZE : Returns number of messaging capable remote endpoints
+- RIO_CM_EP_GET_LIST_SIZE:
+ Returns number of messaging capable remote endpoints
in a RapidIO network associated with the specified mport device.
-- RIO_CM_EP_GET_LIST : Returns list of RapidIO destination IDs for messaging
+- RIO_CM_EP_GET_LIST:
+ Returns list of RapidIO destination IDs for messaging
capable remote endpoints (peers) available in a RapidIO network associated
with the specified mport device.
-- RIO_CM_CHAN_CREATE : Creates RapidIO message exchange channel data structure
+- RIO_CM_CHAN_CREATE:
+ Creates RapidIO message exchange channel data structure
with channel ID assigned automatically or as requested by a caller.
-- RIO_CM_CHAN_BIND : Binds the specified channel data structure to the specified
+- RIO_CM_CHAN_BIND:
+ Binds the specified channel data structure to the specified
mport device.
-- RIO_CM_CHAN_LISTEN : Enables listening for connection requests on the specified
+- RIO_CM_CHAN_LISTEN:
+ Enables listening for connection requests on the specified
channel.
-- RIO_CM_CHAN_ACCEPT : Accepts a connection request from peer on the specified
+- RIO_CM_CHAN_ACCEPT:
+ Accepts a connection request from peer on the specified
channel. If wait timeout for this request is specified by a caller it is
a blocking call. If timeout set to 0 this is non-blocking call - ioctl
handler checks for a pending connection request and if one is not available
exits with -EGAIN error status immediately.
-- RIO_CM_CHAN_CONNECT : Sends a connection request to a remote peer/channel.
-- RIO_CM_CHAN_SEND : Sends a data message through the specified channel.
+- RIO_CM_CHAN_CONNECT:
+ Sends a connection request to a remote peer/channel.
+- RIO_CM_CHAN_SEND:
+ Sends a data message through the specified channel.
The handler for this request assumes that message buffer specified by
a caller includes the reserved space for a packet header required by
this driver.
-- RIO_CM_CHAN_RECEIVE : Receives a data message through a connected channel.
+- RIO_CM_CHAN_RECEIVE:
+ Receives a data message through a connected channel.
If the channel does not have an incoming message ready to return this ioctl
handler will wait for new message until timeout specified by a caller
expires. If timeout value is set to 0, ioctl handler uses a default value
defined by MAX_SCHEDULE_TIMEOUT.
-- RIO_CM_CHAN_CLOSE : Closes a specified channel and frees associated buffers.
+- RIO_CM_CHAN_CLOSE:
+ Closes a specified channel and frees associated buffers.
If the specified channel is in the CONNECTED state, sends close notification
to the remote peer.
The ioctl command codes and corresponding data structures intended for use by
user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'.
-II. Hardware Compatibility
+2. Hardware Compatibility
+=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
subsystem with limitations set by available mport HW implementation of messaging
mailboxes.
-III. Module parameters
+3. Module parameters
+====================
-- 'dbg_level' - This parameter allows to control amount of debug information
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional block.
For mask definitions see 'drivers/rapidio/devices/rio_cm.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-- 'cmbox' - Number of RapidIO mailbox to use (default value is 1).
+- 'cmbox'
+ - Number of RapidIO mailbox to use (default value is 1).
This parameter allows to set messaging mailbox number that will be used
within entire RapidIO network. It can be used when default mailbox is
used by other device drivers or is not supported by some nodes in the
RapidIO network.
-- 'chstart' - Start channel number for dynamic assignment. Default value - 256.
+- 'chstart'
+ - Start channel number for dynamic assignment. Default value - 256.
Allows to exclude channel numbers below this parameter from dynamic
allocation to avoid conflicts with software components that use
reserved predefined channel numbers.
-IV. Known problems
+4. Known problems
+=================
None.
-V. User-space Applications and API Library
+5. User-space Applications and API Library
+==========================================
Messaging API library and applications that use this device driver are available
from RapidIO.org.
-VI. TODO List
+6. TODO List
+============
- Add support for system notification messages (reserved channel 0).
diff --git a/Documentation/rapidio/sysfs.txt b/Documentation/rapidio/sysfs.rst
similarity index 75%
rename from Documentation/rapidio/sysfs.txt
rename to Documentation/rapidio/sysfs.rst
index a1adac888e6e..540f72683496 100644
--- a/Documentation/rapidio/sysfs.txt
+++ b/Documentation/rapidio/sysfs.rst
@@ -1,3 +1,7 @@
+=============
+Sysfs entries
+=============
+
The RapidIO sysfs files have moved to:
Documentation/ABI/testing/sysfs-bus-rapidio and
Documentation/ABI/testing/sysfs-class-rapidio
diff --git a/Documentation/rapidio/tsi721.txt b/Documentation/rapidio/tsi721.rst
similarity index 79%
rename from Documentation/rapidio/tsi721.txt
rename to Documentation/rapidio/tsi721.rst
index cd2a2935d51d..42aea438cd20 100644
--- a/Documentation/rapidio/tsi721.txt
+++ b/Documentation/rapidio/tsi721.rst
@@ -1,7 +1,9 @@
+=========================================================================
RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
=========================================================================
-I. Overview
+1. Overview
+===========
This driver implements all currently defined RapidIO mport callback functions.
It supports maintenance read and write operations, inbound and outbound RapidIO
@@ -17,7 +19,9 @@ into the corresponding message queue. Messaging callbacks are implemented to be
fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
1. Module parameters:
-- 'dbg_level' - This parameter allows to control amount of debug information
+
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
This parameter can be changed bit masks that correspond to the specific
functional block.
@@ -25,37 +29,44 @@ fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-- 'dma_desc_per_channel' - This parameter defines number of hardware buffer
+- 'dma_desc_per_channel'
+ - This parameter defines number of hardware buffer
descriptors allocated for each registered Tsi721 DMA channel.
Its default value is 128.
-- 'dma_txqueue_sz' - DMA transactions queue size. Defines number of pending
+- 'dma_txqueue_sz'
+ - DMA transactions queue size. Defines number of pending
transaction requests that can be accepted by each DMA channel.
Default value is 16.
-- 'dma_sel' - DMA channel selection mask. Bitmask that defines which hardware
+- 'dma_sel'
+ - DMA channel selection mask. Bitmask that defines which hardware
DMA channels (0 ... 6) will be registered with DmaEngine core.
If bit is set to 1, the corresponding DMA channel will be registered.
DMA channels not selected by this mask will not be used by this device
driver. Default value is 0x7f (use all channels).
-- 'pcie_mrrs' - override value for PCIe Maximum Read Request Size (MRRS).
+- 'pcie_mrrs'
+ - override value for PCIe Maximum Read Request Size (MRRS).
This parameter gives an ability to override MRRS value set during PCIe
configuration process. Tsi721 supports read request sizes up to 4096B.
Value for this parameter must be set as defined by PCIe specification:
0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B.
Default value is '-1' (= keep platform setting).
-- 'mbox_sel' - RIO messaging MBOX selection mask. This is a bitmask that defines
+- 'mbox_sel'
+ - RIO messaging MBOX selection mask. This is a bitmask that defines
messaging MBOXes are managed by this device driver. Mask bits 0 - 3
correspond to MBOX0 - MBOX3. MBOX is under driver's control if the
corresponding bit is set to '1'. Default value is 0x0f (= all).
-II. Known problems
+2. Known problems
+=================
None.
-III. DMA Engine Support
+3. DMA Engine Support
+=====================
Tsi721 mport driver supports DMA data transfers between local system memory and
remote RapidIO devices. This functionality is implemented according to SLAVE
@@ -68,17 +79,21 @@ One BDMA channel is reserved for generation of maintenance read/write requests.
If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included,
this driver will accept DMA-specific module parameter:
- "dma_desc_per_channel" - defines number of hardware buffer descriptors used by
+
+ "dma_desc_per_channel"
+ - defines number of hardware buffer descriptors used by
each BDMA channel of Tsi721 (by default - 128).
-IV. Version History
+4. Version History
- 1.1.0 - DMA operations re-worked to support data scatter/gather lists larger
+ ===== ====================================================================
+ 1.1.0 DMA operations re-worked to support data scatter/gather lists larger
than hardware buffer descriptors ring.
- 1.0.0 - Initial driver release.
+ 1.0.0 Initial driver release.
+ ===== ====================================================================
-V. License
------------------------------------------------
+5. License
+===========
Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved.
diff --git a/drivers/rapidio/Kconfig b/drivers/rapidio/Kconfig
index fadafc64705f..467e8fa06904 100644
--- a/drivers/rapidio/Kconfig
+++ b/drivers/rapidio/Kconfig
@@ -86,7 +86,7 @@ config RAPIDIO_CHMAN
This option includes RapidIO channelized messaging driver which
provides socket-like interface to allow sharing of single RapidIO
messaging mailbox between multiple user-space applications.
- See "Documentation/rapidio/rio_cm.txt" for driver description.
+ See "Documentation/rapidio/rio_cm.rst" for driver description.
config RAPIDIO_MPORT_CDEV
tristate "RapidIO /dev mport device driver"
--
2.21.0
^ permalink raw reply related
* [PATCH 42/43] docs: move gcc_plugins.txt to core-api and rename to .rst
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Kees Cook, Emese Revfy
In-Reply-To: <cover.1561723979.git.mchehab+samsung@kernel.org>
The gcc_plugins.txt file is already a ReST file. Move it
to the core-api book while renaming it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/{gcc-plugins.txt => core-api/gcc-plugins.rst} | 0
Documentation/core-api/index.rst | 2 +-
MAINTAINERS | 2 +-
scripts/gcc-plugins/Kconfig | 2 +-
4 files changed, 3 insertions(+), 3 deletions(-)
rename Documentation/{gcc-plugins.txt => core-api/gcc-plugins.rst} (100%)
diff --git a/Documentation/gcc-plugins.txt b/Documentation/core-api/gcc-plugins.rst
similarity index 100%
rename from Documentation/gcc-plugins.txt
rename to Documentation/core-api/gcc-plugins.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 2466a4c51031..d1e5b95bf86d 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -35,7 +35,7 @@ Core utilities
boot-time-mm
memory-hotplug
protection-keys
-
+ gcc-plugins
Interfaces for kernel debugging
===============================
diff --git a/MAINTAINERS b/MAINTAINERS
index 2cf8abf6d48e..7ba6d174f49f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6609,7 +6609,7 @@ S: Maintained
F: scripts/gcc-plugins/
F: scripts/gcc-plugin.sh
F: scripts/Makefile.gcc-plugins
-F: Documentation/gcc-plugins.txt
+F: Documentation/core-api/gcc-plugins.rst
GASKET DRIVER FRAMEWORK
M: Rob Springer <rspringer@google.com>
diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig
index e9c677a53c74..d33de0b9f4f5 100644
--- a/scripts/gcc-plugins/Kconfig
+++ b/scripts/gcc-plugins/Kconfig
@@ -23,7 +23,7 @@ config GCC_PLUGINS
GCC plugins are loadable modules that provide extra features to the
compiler. They are useful for runtime instrumentation and static analysis.
- See Documentation/gcc-plugins.txt for details.
+ See Documentation/core-api/gcc-plugins.rst for details.
menu "GCC plugins"
depends on GCC_PLUGINS
--
2.21.0
^ permalink raw reply related
* [PATCH 11/43] docs: console.txt: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Bartlomiej Zolnierkiewicz, Greg Kroah-Hartman,
Jiri Slaby, dri-devel, linux-fbdev
In-Reply-To: <cover.1561723979.git.mchehab+samsung@kernel.org>
Convert this small file to ReST in preparation for adding it to
the driver-api book.
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>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
---
.../console/{console.txt => console.rst} | 63 ++++++++++---------
Documentation/fb/fbcon.rst | 4 +-
drivers/tty/Kconfig | 2 +-
3 files changed, 38 insertions(+), 31 deletions(-)
rename Documentation/console/{console.txt => console.rst} (80%)
diff --git a/Documentation/console/console.txt b/Documentation/console/console.rst
similarity index 80%
rename from Documentation/console/console.txt
rename to Documentation/console/console.rst
index d73c2ab4beda..b374141b027e 100644
--- a/Documentation/console/console.txt
+++ b/Documentation/console/console.rst
@@ -1,3 +1,6 @@
+:orphan:
+
+===============
Console Drivers
===============
@@ -17,25 +20,26 @@ of driver occupying the consoles.) They can only take over the console that is
occupied by the system driver. In the same token, if the modular driver is
released by the console, the system driver will take over.
-Modular drivers, from the programmer's point of view, have to call:
+Modular drivers, from the programmer's point of view, have to call::
do_take_over_console() - load and bind driver to console layer
give_up_console() - unload driver; it will only work if driver
is fully unbound
-In newer kernels, the following are also available:
+In newer kernels, the following are also available::
do_register_con_driver()
do_unregister_con_driver()
If sysfs is enabled, the contents of /sys/class/vtconsole can be
examined. This shows the console backends currently registered by the
-system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus:
+system which are named vtcon<n> where <n> is an integer from 0 to 15.
+Thus::
ls /sys/class/vtconsole
. .. vtcon0 vtcon1
-Each directory in /sys/class/vtconsole has 3 files:
+Each directory in /sys/class/vtconsole has 3 files::
ls /sys/class/vtconsole/vtcon0
. .. bind name uevent
@@ -46,27 +50,29 @@ What do these files signify?
read, or acts to bind or unbind the driver to the virtual consoles
when written to. The possible values are:
- 0 - means the driver is not bound and if echo'ed, commands the driver
+ 0
+ - means the driver is not bound and if echo'ed, commands the driver
to unbind
- 1 - means the driver is bound and if echo'ed, commands the driver to
+ 1
+ - means the driver is bound and if echo'ed, commands the driver to
bind
- 2. name - read-only file. Shows the name of the driver in this format:
+ 2. name - read-only file. Shows the name of the driver in this format::
- cat /sys/class/vtconsole/vtcon0/name
- (S) VGA+
+ cat /sys/class/vtconsole/vtcon0/name
+ (S) VGA+
- '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
- commanded to bind or unbind
+ '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
+ commanded to bind or unbind
- 'VGA+' is the name of the driver
+ 'VGA+' is the name of the driver
- cat /sys/class/vtconsole/vtcon1/name
- (M) frame buffer device
+ cat /sys/class/vtconsole/vtcon1/name
+ (M) frame buffer device
- In this case, '(M)' stands for a (M)odular driver, one that can be
- directly commanded to bind or unbind.
+ In this case, '(M)' stands for a (M)odular driver, one that can be
+ directly commanded to bind or unbind.
3. uevent - ignore this file
@@ -75,14 +81,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other
hand, will bind the driver to the consoles that are currently occupied by a
system driver.
-NOTE1: Binding and unbinding must be selected in Kconfig. It's under:
+NOTE1:
+ Binding and unbinding must be selected in Kconfig. It's under::
-Device Drivers -> Character devices -> Support for binding and unbinding
-console drivers
+ Device Drivers ->
+ Character devices ->
+ Support for binding and unbinding console drivers
-NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
-unbinding will not succeed. An example of an application that sets the console
-to KD_GRAPHICS is X.
+NOTE2:
+ If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
+ unbinding will not succeed. An example of an application that sets the
+ console to KD_GRAPHICS is X.
How useful is this feature? This is very useful for console driver
developers. By unbinding the driver from the console layer, one can unload the
@@ -92,10 +101,10 @@ framebuffer console to VGA console and vice versa, this feature also makes
this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
for more details.)
-Notes for developers:
-=====================
+Notes for developers
+====================
-do_take_over_console() is now broken up into:
+do_take_over_console() is now broken up into::
do_register_con_driver()
do_bind_con_driver() - private function
@@ -104,7 +113,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must
be fully unbound for this call to succeed. con_is_bound() will check if the
driver is bound or not.
-Guidelines for console driver writers:
+Guidelines for console driver writers
=====================================
In order for binding to and unbinding from the console to properly work,
@@ -140,6 +149,4 @@ The current crop of console drivers should still work correctly, but binding
and unbinding them may cause problems. With minimal fixes, these drivers can
be made to work correctly.
-==========================
Antonino Daplas <adaplas@pol.net>
-
diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst
index 1da65b9000de..26bc5cdaabab 100644
--- a/Documentation/fb/fbcon.rst
+++ b/Documentation/fb/fbcon.rst
@@ -187,7 +187,7 @@ the hardware. Thus, in a VGA console::
Assuming the VGA driver can be unloaded, one must first unbind the VGA driver
from the console layer before unloading the driver. The VGA driver cannot be
unloaded if it is still bound to the console layer. (See
-Documentation/console/console.txt for more information).
+Documentation/console/console.rst for more information).
This is more complicated in the case of the framebuffer console (fbcon),
because fbcon is an intermediate layer between the console and the drivers::
@@ -204,7 +204,7 @@ fbcon. Thus, there is no need to explicitly unbind the fbdev drivers from
fbcon.
So, how do we unbind fbcon from the console? Part of the answer is in
-Documentation/console/console.txt. To summarize:
+Documentation/console/console.rst. To summarize:
Echo a value to the bind file that represents the framebuffer console
driver. So assuming vtcon1 represents fbcon, then::
diff --git a/drivers/tty/Kconfig b/drivers/tty/Kconfig
index 0e3e4dacbc12..1cb50f19d58c 100644
--- a/drivers/tty/Kconfig
+++ b/drivers/tty/Kconfig
@@ -93,7 +93,7 @@ config VT_HW_CONSOLE_BINDING
select the console driver that will serve as the backend for the
virtual terminals.
- See <file:Documentation/console/console.txt> for more
+ See <file:Documentation/console/console.rst> for more
information. For framebuffer console users, please refer to
<file:Documentation/fb/fbcon.rst>.
--
2.21.0
^ permalink raw reply related
* [PATCH 20/43] docs: rbtree.txt: fix Sphinx build warnings
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561723979.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 08/43] docs: lp855x-driver.txt: convert to ReST and move to kernel-api
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561723979.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 1606f6cac24d..e909436a2fa3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15906,7 +15906,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 2/9] docs: trace: fix a broken label
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Masami Hiramatsu
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
Sphinx warnings about his:
Documentation/trace/kprobetrace.rst:68: WARNING: undefined label: user_mem_access (if the link has no caption the label must precede a section header)
The problem is quite simple: Sphinx wants a blank line after
references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
---
Documentation/trace/kprobetrace.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index fbb314bfa112..89ba487d4399 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -96,6 +96,7 @@ which shows given pointer in "symbol+offset" style.
For $comm, the default type is "string"; any other type is invalid.
.. _user_mem_access:
+
User Memory Access
------------------
Kprobe events supports user-space memory access. For that purpose, you can use
--
2.21.0
^ permalink raw reply related
* [PATCH 9/9] platform: x86: get rid of a non-existent document
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Darren Hart, Andy Shevchenko,
platform-driver-x86
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
Changeset 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt")
removed the x86-laptop-drivers.txt file, but forgot to update its
Kconfig.
Fixes: 163ede97a9a2 ("Documentation: platform: Delete x86-laptop-drivers.txt")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
drivers/platform/x86/Kconfig | 3 ---
1 file changed, 3 deletions(-)
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index bd15b47abcb4..c318501773bc 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -433,9 +433,6 @@ config COMPAL_LAPTOP
It adds support for rfkill, Bluetooth, WLAN, LCD brightness, hwmon
and battery charging level control.
- For a (possibly incomplete) list of supported laptops, please refer
- to: Documentation/platform/x86-laptop-drivers.txt
-
config SONY_LAPTOP
tristate "Sony Laptop Extras"
depends on ACPI
--
2.21.0
^ permalink raw reply related
* [PATCH 4/9] dt: leds-lm36274.txt: fix a broken reference to ti-lmu.txt
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jacek Anaszewski, Pavel Machek, Dan Murphy,
Rob Herring, Mark Rutland, linux-leds, devicetree
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
There's a typo there:
ti_lmu.txt -> ti-lmu.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Pavel Machek <pavel@ucw.cz>
Acked-by: Dan Murphy <dmurphy@ti.com>
---
Documentation/devicetree/bindings/leds/leds-lm36274.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/devicetree/bindings/leds/leds-lm36274.txt b/Documentation/devicetree/bindings/leds/leds-lm36274.txt
index 456a589c65f0..39c230d59a4d 100644
--- a/Documentation/devicetree/bindings/leds/leds-lm36274.txt
+++ b/Documentation/devicetree/bindings/leds/leds-lm36274.txt
@@ -6,7 +6,7 @@ up to 29V total output voltage. The 11-bit LED current is programmable via
the I2C bus and/or controlled via a logic level PWM input from 60 uA to 30 mA.
Parent device properties are documented in
-Documentation/devicetree/bindings/mfd/ti_lmu.txt
+Documentation/devicetree/bindings/mfd/ti-lmu.txt
Regulator properties are documented in
Documentation/devicetree/bindings/regulator/lm363x-regulator.txt
--
2.21.0
^ permalink raw reply related
* [PATCH 1/9] hrtimer: Use a bullet for the returns bullet list
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Thomas Gleixner
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
That gets rid of this warning:
./kernel/time/hrtimer.c:1119: WARNING: Block quote ends without a blank line; unexpected unindent.
and displays nicely both at the source code and at the produced
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
kernel/time/hrtimer.c | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
index edb230aba3d1..5ee77f1a8a92 100644
--- a/kernel/time/hrtimer.c
+++ b/kernel/time/hrtimer.c
@@ -1114,9 +1114,10 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
* @timer: hrtimer to stop
*
* Returns:
- * 0 when the timer was not active
- * 1 when the timer was active
- * -1 when the timer is currently executing the callback function and
+ *
+ * * 0 when the timer was not active
+ * * 1 when the timer was active
+ * * -1 when the timer is currently executing the callback function and
* cannot be stopped
*/
int hrtimer_try_to_cancel(struct hrtimer *timer)
--
2.21.0
^ permalink raw reply related
* [PATCH 8/9] drm: fix a reference for a renamed file: fb/modedb.rst
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Maarten Lankhorst, Maxime Ripard, Sean Paul,
David Airlie, Daniel Vetter, dri-devel
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
Due to two patches being applied about the same time, the
reference for modedb.rst file got wrong:
Documentation/fb/modedb.txt is now Documentation/fb/modedb.rst.
Fixes: 1bf4e09227c3 ("drm/modes: Allow to specify rotation and reflection on the commandline")
Fixes: ab42b818954c ("docs: fb: convert docs to ReST and rename to *.rst")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
drivers/gpu/drm/drm_modes.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index 57e6408288c8..4645af681ef8 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -1680,7 +1680,7 @@ static int drm_mode_parse_cmdline_options(char *str, size_t len,
*
* Additionals options can be provided following the mode, using a comma to
* separate each option. Valid options can be found in
- * Documentation/fb/modedb.txt.
+ * Documentation/fb/modedb.rst.
*
* The intermediate drm_cmdline_mode structure is required to store additional
* options from the command line modline like the force-enable/disable flag.
--
2.21.0
^ permalink raw reply related
* [PATCH 7/9] docs: gpu: add msm-crash-dump.rst to the index.rst file
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Airlie, Daniel Vetter, Maarten Lankhorst,
Maxime Ripard, Sean Paul, dri-devel
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
This file is currently orphaned.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/gpu/drivers.rst | 1 +
Documentation/gpu/msm-crash-dump.rst | 2 --
2 files changed, 1 insertion(+), 2 deletions(-)
diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 4bfb7068e9f7..6c88c57b90cf 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -20,6 +20,7 @@ GPU Driver Documentation
xen-front
afbc
komeda-kms
+ msm-crash-dump
.. only:: subproject and html
diff --git a/Documentation/gpu/msm-crash-dump.rst b/Documentation/gpu/msm-crash-dump.rst
index 240ef200f76c..757cd257e0d8 100644
--- a/Documentation/gpu/msm-crash-dump.rst
+++ b/Documentation/gpu/msm-crash-dump.rst
@@ -1,5 +1,3 @@
-:orphan:
-
=====================
MSM Crash Dump Format
=====================
--
2.21.0
^ permalink raw reply related
* [PATCH 5/9] docs: fix some broken references due to txt->rst renames
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rob Herring, Mark Rutland, Jani Nikula,
Joonas Lahtinen, Rodrigo Vivi, David Airlie, Daniel Vetter,
Ajay Gupta, devicetree, intel-gfx, dri-devel, linux-i2c,
Wolfram Sang, Daniel Vetter
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
There are three left-overs from the recent file renames,
probably due to some other conflicting patch.
Fix them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Wolfram Sang <wsa@the-dreams.de>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
Documentation/devicetree/bindings/arm/idle-states.txt | 2 +-
drivers/gpu/drm/i915/intel_runtime_pm.h | 2 +-
drivers/i2c/busses/i2c-nvidia-gpu.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt
index 3bdbe675b9e6..d8d9aa7167e8 100644
--- a/Documentation/devicetree/bindings/arm/idle-states.txt
+++ b/Documentation/devicetree/bindings/arm/idle-states.txt
@@ -703,4 +703,4 @@ cpus {
https://www.devicetree.org/specifications/
[6] ARM Linux Kernel documentation - Booting AArch64 Linux
- Documentation/arm64/booting.txt
+ Documentation/arm64/booting.rst
diff --git a/drivers/gpu/drm/i915/intel_runtime_pm.h b/drivers/gpu/drm/i915/intel_runtime_pm.h
index 473c4850c01d..2ee8f9522e05 100644
--- a/drivers/gpu/drm/i915/intel_runtime_pm.h
+++ b/drivers/gpu/drm/i915/intel_runtime_pm.h
@@ -45,7 +45,7 @@ enum i915_drm_suspend_mode {
* to be disabled. This shouldn't happen and we'll print some error messages in
* case it happens.
*
- * For more, read the Documentation/power/runtime_pm.txt.
+ * For more, read the Documentation/power/runtime_pm.rst.
*/
struct intel_runtime_pm {
atomic_t wakeref_count;
diff --git a/drivers/i2c/busses/i2c-nvidia-gpu.c b/drivers/i2c/busses/i2c-nvidia-gpu.c
index cfc76b5de726..5a1235fd86bb 100644
--- a/drivers/i2c/busses/i2c-nvidia-gpu.c
+++ b/drivers/i2c/busses/i2c-nvidia-gpu.c
@@ -364,7 +364,7 @@ static void gpu_i2c_remove(struct pci_dev *pdev)
/*
* We need gpu_i2c_suspend() even if it is stub, for runtime pm to work
* correctly. Without it, lspci shows runtime pm status as "D0" for the card.
- * Documentation/power/pci.txt also insists for driver to provide this.
+ * Documentation/power/pci.rst also insists for driver to provide this.
*/
static __maybe_unused int gpu_i2c_suspend(struct device *dev)
{
--
2.21.0
^ permalink raw reply related
* [PATCH 6/9] docs: virtual: there are two orphan docs there
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Paolo Bonzini, Radim Krčmář, kvm
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/virtual/kvm/amd-memory-encryption.rst | 2 ++
Documentation/virtual/kvm/vcpu-requests.rst | 2 ++
2 files changed, 4 insertions(+)
diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst
index d18c97b4e140..6c37ff9a0a3c 100644
--- a/Documentation/virtual/kvm/amd-memory-encryption.rst
+++ b/Documentation/virtual/kvm/amd-memory-encryption.rst
@@ -1,3 +1,5 @@
+:orphan:
+
======================================
Secure Encrypted Virtualization (SEV)
======================================
diff --git a/Documentation/virtual/kvm/vcpu-requests.rst b/Documentation/virtual/kvm/vcpu-requests.rst
index 5feb3706a7ae..c1807a1b92e6 100644
--- a/Documentation/virtual/kvm/vcpu-requests.rst
+++ b/Documentation/virtual/kvm/vcpu-requests.rst
@@ -1,3 +1,5 @@
+:orphan:
+
=================
KVM VCPU Requests
=================
--
2.21.0
^ permalink raw reply related
* [PATCH 0/9] Some doc fixes
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Maarten Lankhorst, linux-leds, kvm,
Radim Krčmář, dri-devel, intel-gfx,
Joonas Lahtinen, Rob Herring, platform-driver-x86, Paolo Bonzini,
Sean Paul, Darren Hart, Jacek Anaszewski, linux-i2c, Ajay Gupta,
Jani Nikula, Thomas Gleixner, David Airlie, Mark Rutland,
Pavel Machek, Maxime Ripard, Dan Murphy, devicetree,
Andy Shevchenko, Rodrigo Vivi, Daniel Vetter
This patch series is against linux-next (next-20190627). I doubt those
would apply cleanly against docs next tree.
So, please apply it via the subsystem trees. Otherwise, they could
be pushed by the end of the merge window or for -rc1 via a docs tree.
Most, if not all were I already sent.
Mauro Carvalho Chehab (9):
hrtimer: Use a bullet for the returns bullet list
docs: trace: fix a broken label
docs: signal: fix a kernel-doc markup
dt: leds-lm36274.txt: fix a broken reference to ti-lmu.txt
docs: fix some broken references due to txt->rst renames
docs: virtual: there are two orphan docs there
docs: gpu: add msm-crash-dump.rst to the index.rst file
drm: fix a reference for a renamed file: fb/modedb.rst
platform: x86: get rid of a non-existent document
Documentation/devicetree/bindings/arm/idle-states.txt | 2 +-
Documentation/devicetree/bindings/leds/leds-lm36274.txt | 2 +-
Documentation/gpu/drivers.rst | 1 +
Documentation/gpu/msm-crash-dump.rst | 2 --
Documentation/trace/kprobetrace.rst | 1 +
Documentation/virtual/kvm/amd-memory-encryption.rst | 2 ++
Documentation/virtual/kvm/vcpu-requests.rst | 2 ++
drivers/gpu/drm/drm_modes.c | 2 +-
drivers/gpu/drm/i915/intel_runtime_pm.h | 2 +-
drivers/i2c/busses/i2c-nvidia-gpu.c | 2 +-
drivers/platform/x86/Kconfig | 3 ---
kernel/signal.c | 2 +-
kernel/time/hrtimer.c | 7 ++++---
13 files changed, 16 insertions(+), 14 deletions(-)
--
2.21.0
^ permalink raw reply
* [PATCH 3/9] docs: signal: fix a kernel-doc markup
From: Mauro Carvalho Chehab @ 2019-06-28 12:12 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561723736.git.mchehab+samsung@kernel.org>
The kernel-doc parser doesn't handle expressions with %foo*.
Instead, when an asterisk should be part of a constant, it
uses an alternative notation: `foo*`.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
kernel/signal.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/kernel/signal.c b/kernel/signal.c
index 91b789dd6e72..10a826855b59 100644
--- a/kernel/signal.c
+++ b/kernel/signal.c
@@ -349,7 +349,7 @@ void task_clear_jobctl_pending(struct task_struct *task, unsigned long mask)
* @task has %JOBCTL_STOP_PENDING set and is participating in a group stop.
* Group stop states are cleared and the group stop count is consumed if
* %JOBCTL_STOP_CONSUME was set. If the consumption completes the group
- * stop, the appropriate %SIGNAL_* flags are set.
+ * stop, the appropriate `SIGNAL_*` flags are set.
*
* CONTEXT:
* Must be called with @task->sighand->siglock held.
--
2.21.0
^ permalink raw reply related
* Re: [PATCH 2/2] drivers/perf: Add CCPI2 PMU support in ThunderX2 UNCORE driver.
From: Will Deacon @ 2019-06-28 9:08 UTC (permalink / raw)
To: Ganapatrao Kulkarni
Cc: Ganapatrao Kulkarni, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org,
linux-arm-kernel@lists.infradead.org, Will.Deacon@arm.com,
mark.rutland@arm.com, corbet@lwn.net, jnair, rrichter, jglauber
In-Reply-To: <CAKTKpr7PXFzQBHrJt+Ko=JaB+-5FdpNu+ByfkWmAm8OeiPem3w@mail.gmail.com>
Hi again, Ganapat,
Thanks for the quick reply.
On Fri, Jun 28, 2019 at 11:09:33AM +0530, Ganapatrao Kulkarni wrote:
> On Thu, Jun 27, 2019 at 3:27 PM Will Deacon <will@kernel.org> wrote:
> > On Fri, Jun 14, 2019 at 05:42:46PM +0000, Ganapatrao Kulkarni wrote:
> > > CCPI2 is a low-latency high-bandwidth serial interface for connecting
> > > ThunderX2 processors. This patch adds support to capture CCPI2 perf events.
> > >
> > > Signed-off-by: Ganapatrao Kulkarni <gkulkarni@marvell.com>
> > > ---
> > > drivers/perf/thunderx2_pmu.c | 179 ++++++++++++++++++++++++++++++-----
> > > 1 file changed, 157 insertions(+), 22 deletions(-)
> > >
> > > diff --git a/drivers/perf/thunderx2_pmu.c b/drivers/perf/thunderx2_pmu.c
> > > index 43d76c85da56..3791ac9b897d 100644
> > > --- a/drivers/perf/thunderx2_pmu.c
> > > +++ b/drivers/perf/thunderx2_pmu.c
> > > @@ -16,7 +16,9 @@
> > > * they need to be sampled before overflow(i.e, at every 2 seconds).
> > > */
> > >
> > > -#define TX2_PMU_MAX_COUNTERS 4
> > > +#define TX2_PMU_DMC_L3C_MAX_COUNTERS 4
> >
> > I find it odd that you rename this...
>
> i am not sure, how to avoid this since dmc/l3c have 4 counters and ccpi2 has 8.
> i will try to make this better in v2.
> >
> > > +#define TX2_PMU_CCPI2_MAX_COUNTERS 8
> > > +
> > > #define TX2_PMU_DMC_CHANNELS 8
> > > #define TX2_PMU_L3_TILES 16
> > >
> > > @@ -28,11 +30,22 @@
> > > */
> > > #define DMC_EVENT_CFG(idx, val) ((val) << (((idx) * 8) + 1))
> > >
> > > +#define GET_EVENTID_CCPI2(ev) ((ev->hw.config) & 0x1ff)
> > > +/* bits[3:0] to select counters, starts from 8, bit[3] set always. */
> > > +#define GET_COUNTERID_CCPI2(ev) ((ev->hw.idx) & 0x7)
> > > +#define CCPI2_COUNTER_OFFSET 8
> >
> >
> > ... but leave GET_EVENTID alone, even though it only applies to DMC/L3C
> > events. Saying that, if you have the event you can figure out its type,
> > so could you avoid the need for additional macros entirely and just use
> > the correct masks based on the corresponding PMU type? That might also
> > avoid some of the conditional control flow you're introducing elsewhere.
>
> sure, i will add mask as argument to macro.
> >
> > > #define L3C_COUNTER_CTL 0xA8
> > > #define L3C_COUNTER_DATA 0xAC
> > > #define DMC_COUNTER_CTL 0x234
> > > #define DMC_COUNTER_DATA 0x240
> > >
> > > +#define CCPI2_PERF_CTL 0x108
> > > +#define CCPI2_COUNTER_CTL 0x10C
> > > +#define CCPI2_COUNTER_SEL 0x12c
> > > +#define CCPI2_COUNTER_DATA_L 0x130
> > > +#define CCPI2_COUNTER_DATA_H 0x134
> > > +
> > > /* L3C event IDs */
> > > #define L3_EVENT_READ_REQ 0xD
> > > #define L3_EVENT_WRITEBACK_REQ 0xE
> > > @@ -51,9 +64,16 @@
> > > #define DMC_EVENT_READ_TXNS 0xF
> > > #define DMC_EVENT_MAX 0x10
> > >
> > > +#define CCPI2_EVENT_REQ_PKT_SENT 0x3D
> > > +#define CCPI2_EVENT_SNOOP_PKT_SENT 0x65
> > > +#define CCPI2_EVENT_DATA_PKT_SENT 0x105
> > > +#define CCPI2_EVENT_GIC_PKT_SENT 0x12D
> > > +#define CCPI2_EVENT_MAX 0x200
> > > +
> > > enum tx2_uncore_type {
> > > PMU_TYPE_L3C,
> > > PMU_TYPE_DMC,
> > > + PMU_TYPE_CCPI2,
> > > PMU_TYPE_INVALID,
> > > };
> > >
> > > @@ -73,8 +93,8 @@ struct tx2_uncore_pmu {
> > > u32 max_events;
> > > u64 hrtimer_interval;
> > > void __iomem *base;
> > > - DECLARE_BITMAP(active_counters, TX2_PMU_MAX_COUNTERS);
> > > - struct perf_event *events[TX2_PMU_MAX_COUNTERS];
> > > + DECLARE_BITMAP(active_counters, TX2_PMU_CCPI2_MAX_COUNTERS);
> > > + struct perf_event *events[TX2_PMU_DMC_L3C_MAX_COUNTERS];
> >
> > Hmm, that looks very odd. Why are they now different sizes?
>
> events[ ] is used to hold reference to active events to use in timer
> callback, which is not applicable to ccpi2, hence 4.
> active_counters is set to max of both. i.e, 8. i will try to make it
> better readable in v2.
Thanks. I suspect renaming the field would help a lot, or perhaps reworking
your data structures so that you have a union of ccpi2 and dmc/l2c
structures where necessary.
> > > struct device *dev;
> > > struct hrtimer hrtimer;
> > > const struct attribute_group **attr_groups;
> > > @@ -92,7 +112,21 @@ static inline struct tx2_uncore_pmu *pmu_to_tx2_pmu(struct pmu *pmu)
> > > return container_of(pmu, struct tx2_uncore_pmu, pmu);
> > > }
> > >
> > > -PMU_FORMAT_ATTR(event, "config:0-4");
> > > +#define TX2_PMU_FORMAT_ATTR(_var, _name, _format) \
> > > +static ssize_t \
> > > +__tx2_pmu_##_var##_show(struct device *dev, \
> > > + struct device_attribute *attr, \
> > > + char *page) \
> > > +{ \
> > > + BUILD_BUG_ON(sizeof(_format) >= PAGE_SIZE); \
> > > + return sprintf(page, _format "\n"); \
> > > +} \
> > > + \
> > > +static struct device_attribute format_attr_##_var = \
> > > + __ATTR(_name, 0444, __tx2_pmu_##_var##_show, NULL)
> > > +
> > > +TX2_PMU_FORMAT_ATTR(event, event, "config:0-4");
> > > +TX2_PMU_FORMAT_ATTR(event_ccpi2, event, "config:0-9");
> >
> > This doesn't look right. Can perf deal with overlapping fields? It seems
> > wrong that we'd allow the user to specify both, for example.
>
> I am not sure what is the issue here? both are different PMUs
> root@SBR-26> cat /sys/bus/event_source/devices/uncore_dmc_0/format/event
> config:0-4
> root@SBR-26> cat /sys/bus/event_source/devices/uncore_ccpi2_0/format/event
> config:0-9
Ah, sorry about that. I got _var and _name the wrong way around and thought
you were introducing a file called event_ccpi2! What you have looks fine.
Will
^ permalink raw reply
* Re: [PATCH v5 01/18] kunit: test: add KUnit test runner core
From: Brendan Higgins @ 2019-06-28 8:09 UTC (permalink / raw)
To: Stephen Boyd
Cc: Frank Rowand, Greg KH, Josh Poimboeuf, Kees Cook, Kieran Bingham,
Luis Chamberlain, Peter Zijlstra, Rob Herring, shuah,
Theodore Ts'o, Masahiro Yamada, devicetree, dri-devel,
kunit-dev, open list:DOCUMENTATION, linux-fsdevel, linux-kbuild,
Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK,
linux-nvdimm, linux-um, Sasha Levin, Bird, Timothy,
Amir Goldstein, Dan Carpenter, Daniel Vetter, Jeff Dike,
Joel Stanley, Julia Lawall, Kevin Hilman, Knut Omang,
Logan Gunthorpe, Michael Ellerman, Petr Mladek, Randy Dunlap,
Richard Weinberger, David Rientjes, Steven Rostedt, wfg
In-Reply-To: <20190627181636.5EA752064A@mail.kernel.org>
On Thu, Jun 27, 2019 at 11:16 AM Stephen Boyd <sboyd@kernel.org> wrote:
>
> Quoting Brendan Higgins (2019-06-26 16:00:40)
> > On Tue, Jun 25, 2019 at 8:41 PM Stephen Boyd <sboyd@kernel.org> wrote:
> >
> > > scenario like below, but where it is a problem. There could be three
> > > CPUs, or even one CPU and three threads if you want to describe the
> > > extra thread scenario.
> > >
> > > Here's my scenario where it isn't needed:
> > >
> > > CPU0 CPU1
> > > ---- ----
> > > kunit_run_test(&test)
> > > test_case_func()
> > > ....
> > > [mock hardirq]
> > > kunit_set_success(&test)
> > > [hardirq ends]
> > > ...
> > > complete(&test_done)
> > > wait_for_completion(&test_done)
> > > kunit_get_success(&test)
> > >
> > > We don't need to care about having locking here because success or
> > > failure only happens in one place and it's synchronized with the
> > > completion.
> >
> > Here is the scenario I am concerned about:
> >
> > CPU0 CPU1 CPU2
> > ---- ---- ----
> > kunit_run_test(&test)
> > test_case_func()
> > ....
> > schedule_work(foo_func)
> > [mock hardirq] foo_func()
> > ... ...
> > kunit_set_success(false) kunit_set_success(false)
> > [hardirq ends] ...
> > ...
> > complete(&test_done)
> > wait_for_completion(...)
> > kunit_get_success(&test)
> >
> > In my scenario, since both CPU1 and CPU2 update the success status of
> > the test simultaneously, even though they are setting it to the same
> > value. If my understanding is correct, this could result in a
> > write-tear on some architectures in some circumstances. I suppose we
> > could just make it an atomic boolean, but I figured locking is also
> > fine, and generally preferred.
>
> This is what we have WRITE_ONCE() and READ_ONCE() for. Maybe you could
> just use that in the getter and setters and remove the lock if it isn't
> used for anything else.
>
> It may also be a good idea to have a kunit_fail_test() API that fails
> the test passed in with a WRITE_ONCE(false). Otherwise, the test is
> assumed successful and it isn't even possible for a test to change the
> state from failure to success due to a logical error because the API
> isn't available. Then we don't really need to have a generic
> kunit_set_success() function at all. We could have a kunit_test_failed()
> function too that replaces the kunit_get_success() function. That would
> read better in an if condition.
You know what, I think you are right.
Sorry, for not realizing this earlier, I think you mentioned something
along these lines a long time ago.
Thanks for your patience!
> >
> > Also, to be clear, I am onboard with dropping then IRQ stuff for now.
> > I am fine moving to a mutex for the time being.
> >
>
> Ok.
Thanks!
^ permalink raw reply
* Re: [PATCH v5 17/18] kernel/sysctl-test: Add null pointer test for sysctl.c:proc_dointvec()
From: Brendan Higgins @ 2019-06-28 8:01 UTC (permalink / raw)
To: Luis Chamberlain
Cc: Iurii Zaikin, linux-api, Michael Kerrisk (man-pages),
Frank Rowand, Greg KH, Josh Poimboeuf, Kees Cook, Kieran Bingham,
Peter Zijlstra, Rob Herring, Stephen Boyd, shuah,
Theodore Ts'o, Masahiro Yamada, devicetree, dri-devel,
kunit-dev, open list:DOCUMENTATION, linux-fsdevel, linux-kbuild,
Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK,
linux-nvdimm, linux-um, Sasha Levin, Bird, Timothy,
Amir Goldstein, Dan Carpenter, Daniel Vetter, Jeff Dike,
Joel Stanley, Julia Lawall, Kevin Hilman, Knut Omang,
Logan Gunthorpe, Michael Ellerman, Petr Mladek, Randy Dunlap,
Richard Weinberger, David Rientjes, Steven Rostedt, wfg
In-Reply-To: <20190627061021.GE19023@42.do-not-panic.com>
On Wed, Jun 26, 2019 at 11:10 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
>
> On Wed, Jun 26, 2019 at 09:07:43PM -0700, Iurii Zaikin wrote:
> > On Tue, Jun 25, 2019 at 7:17 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
> > > > +static void sysctl_test_dointvec_table_maxlen_unset(struct kunit *test)
> > > > +{
> > > > + struct ctl_table table = {
> > > > + .procname = "foo",
> > > > + .data = &test_data.int_0001,
> > > > + .maxlen = 0,
> > > > + .mode = 0644,
> > > > + .proc_handler = proc_dointvec,
> > > > + .extra1 = &i_zero,
> > > > + .extra2 = &i_one_hundred,
> > > > + };
> > > > + void *buffer = kunit_kzalloc(test, sizeof(int), GFP_USER);
> > > > + size_t len;
> > > > + loff_t pos;
> > > > +
> > > > + len = 1234;
> > > > + KUNIT_EXPECT_EQ(test, 0, proc_dointvec(&table, 0, buffer, &len, &pos));
> > > > + KUNIT_EXPECT_EQ(test, (size_t)0, len);
> > > > + len = 1234;
> > > > + KUNIT_EXPECT_EQ(test, 0, proc_dointvec(&table, 1, buffer, &len, &pos));
> > > > + KUNIT_EXPECT_EQ(test, (size_t)0, len);
> > > > +}
> > >
> > > In a way this is also testing for general kernel API changes. This is and the
> > > last one were good examples. So this is not just testing functionality
> > > here. There is no wrong or write answer if 0 or -EINVAL was returned
> > > other than the fact that we have been doing this for years.
> > >
> > > Its a perhaps small but important difference for some of these tests. I
> > > *do* think its worth clarifying through documentation which ones are
> > > testing for API consistency Vs proper correctness.
> >
> > You make a good point that the test codifies the existing behavior of
> > the function in lieu of formal documentation. However, the test cases
> > were derived from examining the source code of the function under test
> > and attempting to cover all branches. The assertions were added only
> > for the values that appeared to be set deliberately in the
> > implementation. And it makes sense to me to test that the code does
> > exactly what the implementation author intended.
>
> I'm not arguing against adding them. I'm suggesting that it is different
> to test for API than for correctness of intended functionality, and
> it would be wise to make it clear which test cases are for API and which
> for correctness.
I see later on that some of the API stuff you are talking about is
public APIs from the standpoint of user (outside of LInux) visible. To
be clear, is that what you mean by public APIs throughout, or would
you distinguish between correctness tests, internal API tests, and
external API tests?
> This will come up later for other kunit tests and it would be great
> to set precendent so that other kunit tests can follow similar
> practices to ensure its clear what is API realted Vs correctness of
> intended functionality.
>
> In fact, I'm not yet sure if its possible to test public kernel API to
> userspace with kunit, but if it is possible... well, that could make
> linux-api folks happy as they could enable us to codify interpreation of
> what is expected into kunit test cases, and we'd ensure that the
> codified interpretation is not only documented in man pages but also
> through formal kunit test cases.
>
> A regression in linux-api then could be formalized through a proper
> kunit tests case. And if an API evolves, it would force developers to
> update the respective kunit which codifies that contract.
Yep, I think that is long term hope. Some of the file system interface
stuff that requires a filesystem to be mounted somewhere might get a
little weird/difficult, but I suspect we should be able to do it
eventually. I mean it's all just C code right? Should mostly boil down
to someone figuring out how to do it the first time.
> > > > +static void sysctl_test_dointvec_single_less_int_min(struct kunit *test)
> > > > +{
> > > > + struct ctl_table table = {
> > > > + .procname = "foo",
> > > > + .data = &test_data.int_0001,
> > > > + .maxlen = sizeof(int),
> > > > + .mode = 0644,
> > > > + .proc_handler = proc_dointvec,
> > > > + .extra1 = &i_zero,
> > > > + .extra2 = &i_one_hundred,
> > > > + };
> > > > + char input[32];
> > > > + size_t len = sizeof(input) - 1;
> > > > + loff_t pos = 0;
> > > > + unsigned long abs_of_less_than_min = (unsigned long)INT_MAX
> > > > + - (INT_MAX + INT_MIN) + 1;
> > > > +
> > > > + KUNIT_EXPECT_LT(test,
> > > > + (size_t)snprintf(input, sizeof(input), "-%lu",
> > > > + abs_of_less_than_min),
> > > > + sizeof(input));
> > > > +
> > > > + table.data = kunit_kzalloc(test, sizeof(int), GFP_USER);
> > > > + KUNIT_EXPECT_EQ(test, -EINVAL,
> > > > + proc_dointvec(&table, 1, input, &len, &pos));
> > > > + KUNIT_EXPECT_EQ(test, sizeof(input) - 1, len);
> > > > + KUNIT_EXPECT_EQ(test, 0, ((int *)table.data)[0]);
> > > > +}
> > >
> > > API test.
> > >
> > Not sure why.
>
> Because you are codifying that we *definitely* return -EINVAL on
> overlow. Some parts of the kernel return -ERANGE for overflows for
> instance.
>
> It would be a generic test for overflow if it would just test
> for any error.
>
> It is a fine and good test to keep. All these tests are good to keep.
>
> > I believe there has been a real bug with int overflow in
> > proc_dointvec.
> > Covering it with test seems like a good idea.
>
> Oh definitely.
>
> > > > +static void sysctl_test_dointvec_single_greater_int_max(struct kunit *test)
> > > > +{
> > > > + struct ctl_table table = {
> > > > + .procname = "foo",
> > > > + .data = &test_data.int_0001,
> > > > + .maxlen = sizeof(int),
> > > > + .mode = 0644,
> > > > + .proc_handler = proc_dointvec,
> > > > + .extra1 = &i_zero,
> > > > + .extra2 = &i_one_hundred,
> > > > + };
> > > > + char input[32];
> > > > + size_t len = sizeof(input) - 1;
> > > > + loff_t pos = 0;
> > > > + unsigned long greater_than_max = (unsigned long)INT_MAX + 1;
> > > > +
> > > > + KUNIT_EXPECT_GT(test, greater_than_max, (unsigned long)INT_MAX);
> > > > + KUNIT_EXPECT_LT(test, (size_t)snprintf(input, sizeof(input), "%lu",
> > > > + greater_than_max),
> > > > + sizeof(input));
> > > > + table.data = kunit_kzalloc(test, sizeof(int), GFP_USER);
> > > > + KUNIT_EXPECT_EQ(test, -EINVAL,
> > > > + proc_dointvec(&table, 1, input, &len, &pos));
> > > > + KUNIT_EXPECT_EQ(test, sizeof(input) - 1, len);
> > > > + KUNIT_EXPECT_EQ(test, 0, ((int *)table.data)[0]);
> > > > +}
> > > > +
> > >
> > > API test.
> > >
> > > > +static struct kunit_case sysctl_test_cases[] = {
> > > > + KUNIT_CASE(sysctl_test_dointvec_null_tbl_data),
> > > > + KUNIT_CASE(sysctl_test_dointvec_table_maxlen_unset),
> > > > + KUNIT_CASE(sysctl_test_dointvec_table_len_is_zero),
> > > > + KUNIT_CASE(sysctl_test_dointvec_table_read_but_position_set),
> > > > + KUNIT_CASE(sysctl_test_dointvec_happy_single_positive),
> > > > + KUNIT_CASE(sysctl_test_dointvec_happy_single_negative),
> > > > + KUNIT_CASE(sysctl_test_dointvec_single_less_int_min),
> > > > + KUNIT_CASE(sysctl_test_dointvec_single_greater_int_max),
> > > > + {}
> > > > +};
> > >
> > > Oh all are API tests.. perhaps then just rename then
> > > sysctl_test_cases to sysctl_api_test_cases.
> > >
> > > Would be good to add at least *two* other tests cases for this
> > > example, one which does a valid read and one which does a valid write.
> > Added valid reads. There already are 2 valid writes.
>
> Thanks.
>
> > > If that is done either we add another kunit test module for correctness
> > > or just extend the above and use prefix / postfixes on the functions
> > > to distinguish between API / correctness somehow.
> > >
> > > > +
> > > > +static struct kunit_module sysctl_test_module = {
> > > > + .name = "sysctl_test",
> > > > + .test_cases = sysctl_test_cases,
> > > > +};
> > > > +
> > > > +module_test(sysctl_test_module);
> > > > diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
> > > > index cbdfae3798965..389b8986f5b77 100644
> > > > --- a/lib/Kconfig.debug
> > > > +++ b/lib/Kconfig.debug
> > > > @@ -1939,6 +1939,16 @@ config TEST_SYSCTL
> > > >
> > > > If unsure, say N.
> > > >
> > > > +config SYSCTL_KUNIT_TEST
> > > > + bool "KUnit test for sysctl"
> > > > + depends on KUNIT
> > > > + help
> > > > + This builds the proc sysctl unit test, which runs on boot. For more
> > > > + information on KUnit and unit tests in general please refer to the
> > > > + KUnit documentation in Documentation/dev-tools/kunit/.
> > >
> > > A little more description here would help. It is testing for API and
> > > hopefully also correctness (if extended with those two examples I
> > > mentioned).
> > >
> > Added "Tests the API contract and implementation correctness of sysctl."
>
> Yes, much clearer, thanks!
Cheers!
^ permalink raw reply
* Re: [linux-kernel-mentees] [PATCH v2] Doc : doc-guide : Fix a typo
From: Sheriff Esseson @ 2019-06-28 7:43 UTC (permalink / raw)
To: skhan; +Cc: linux-kernel-mentees, linux-doc, linux-kernel, corbet
In-Reply-To: <20190628063342.27613-1-sheriffesseson@gmail.com>
On Fri, Jun 28, 2019 at 07:33:42AM +0100, Sheriff Esseson wrote:
> fix the disjunction by replacing "of" with "or".
>
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
>
> changes in v2:
> - cc-ed Corbet.
>
> Documentation/doc-guide/kernel-doc.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index f96059767..192c36af3 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -359,7 +359,7 @@ Domain`_ references.
> ``monospaced font``.
>
> Useful if you need to use special characters that would otherwise have some
> - meaning either by kernel-doc script of by reStructuredText.
> + meaning either by kernel-doc script or by reStructuredText.
>
> This is particularly useful if you need to use things like ``%ph`` inside
> a function description.
> --
> 2.22.0
>
make respose inline.
^ permalink raw reply
* Re: [PATCH 2/2] mm, slab: Extend vm/drop_caches to shrink kmem slabs
From: Michal Hocko @ 2019-06-28 7:31 UTC (permalink / raw)
To: Waiman Long
Cc: Christoph Lameter, Pekka Enberg, David Rientjes, Joonsoo Kim,
Andrew Morton, Alexander Viro, Jonathan Corbet, Luis Chamberlain,
Kees Cook, Johannes Weiner, Vladimir Davydov, linux-mm, linux-doc,
linux-fsdevel, cgroups, linux-kernel, Roman Gushchin,
Shakeel Butt, Andrea Arcangeli
In-Reply-To: <5cb05d2c-39a7-f138-b0b9-4b03d6008999@redhat.com>
On Thu 27-06-19 17:16:04, Waiman Long wrote:
> On 6/27/19 11:15 AM, Michal Hocko wrote:
> > On Mon 24-06-19 13:42:19, Waiman Long wrote:
> >> With the slub memory allocator, the numbers of active slab objects
> >> reported in /proc/slabinfo are not real because they include objects
> >> that are held by the per-cpu slab structures whether they are actually
> >> used or not. The problem gets worse the more CPUs a system have. For
> >> instance, looking at the reported number of active task_struct objects,
> >> one will wonder where all the missing tasks gone.
> >>
> >> I know it is hard and costly to get a real count of active objects.
> > What exactly is expensive? Why cannot slabinfo reduce the number of
> > active objects by per-cpu cached objects?
> >
> The number of cachelines that needs to be accessed in order to get an
> accurate count will be much higher if we need to iterate through all the
> per-cpu structures. In addition, accessing the per-cpu partial list will
> be racy.
Why is all that a problem for a root only interface that should be used
quite rarely (it is not something that you should be reading hundreds
time per second, right)?
--
Michal Hocko
SUSE Labs
^ permalink raw reply
* Re: [PATCH 1/2] mm, memcontrol: Add memcg_iterate_all()
From: Michal Hocko @ 2019-06-28 7:10 UTC (permalink / raw)
To: Waiman Long
Cc: Christoph Lameter, Pekka Enberg, David Rientjes, Joonsoo Kim,
Andrew Morton, Alexander Viro, Jonathan Corbet, Luis Chamberlain,
Kees Cook, Johannes Weiner, Vladimir Davydov, linux-mm, linux-doc,
linux-fsdevel, cgroups, linux-kernel, Roman Gushchin,
Shakeel Butt, Andrea Arcangeli
In-Reply-To: <2213070d-34c3-4f40-d780-ac371a9cbbbe@redhat.com>
On Thu 27-06-19 17:03:06, Waiman Long wrote:
> On 6/27/19 11:07 AM, Michal Hocko wrote:
> > On Mon 24-06-19 13:42:18, Waiman Long wrote:
> >> Add a memcg_iterate_all() function for iterating all the available
> >> memory cgroups and call the given callback function for each of the
> >> memory cgruops.
> > Why is a trivial wrapper any better than open coded usage of the
> > iterator?
>
> Because the iterator is only defined within memcontrol.c. So an
> alternative may be to put the iterator into a header file that can be
> used by others. Will take a look at that.
That would be preferred.
Thanks!
--
Michal Hocko
SUSE Labs
^ permalink raw reply
* Re: [PATCH next v2] softirq: enable MAX_SOFTIRQ_TIME tuning with sysctl, max_softirq_time_msecs
From: Zhiqiang Liu @ 2019-06-28 6:52 UTC (permalink / raw)
To: tglx, corbet, Kees Cook, Eric Dumazet
Cc: Andrew Morton, manfred, jwilk, dvyukov, feng.tang, sunilmut,
quentin.perret, linux, alex.popov, linux-doc, linux-kernel,
linux-fsdevel, wangxiaogang (F), Zhoukang (A), Mingfangsen,
tedheadster
In-Reply-To: <53770380-053e-70b6-f75e-a0e00bf35c30@huawei.com>
Friendly ping ...
On 2019/6/25 11:13, Zhiqiang Liu wrote:
> From: Zhiqiang liu <liuzhiqiang26@huawei.com>
>
> In __do_softirq func, MAX_SOFTIRQ_TIME was set to 2ms via experimentation by
> commit c10d73671 ("softirq: reduce latencies") in 2013, which was designed
> to reduce latencies for various network workloads. The key reason is that the
> maximum number of microseconds in one NAPI polling cycle in net_rx_action func
> was set to 2 jiffies, so different HZ settting will lead to different latencies.
>
> However, commit 7acf8a1e8 ("Replace 2 jiffies with sysctl netdev_budget_usecs
> to enable softirq tuning") adopts netdev_budget_usecs to tun maximum number of
> microseconds in one NAPI polling cycle. So the latencies of net_rx_action can be
> controlled by sysadmins to copy with hardware changes over time.
>
> Correspondingly, the MAX_SOFTIRQ_TIME should be able to be tunned by sysadmins,
> who knows best about hardware performance, for excepted tradeoff between latence
> and fairness. Here, we add sysctl variable max_softirq_time_msecs to replace
> MAX_SOFTIRQ_TIME with 2ms default value.
>
> Note: max_softirq_time_msecs will be coverted to jiffies, and any budget
> value will be rounded up to the next jiffies, which relates to CONFIG_HZ.
> The time accuracy of jiffies will result in a certain difference
> between the setting jiffies of max_softirq_time_msecs and the actual
> value, which is in one jiffies range.
>
> Signed-off-by: Zhiqiang liu <liuzhiqiang26@huawei.com>
> ---
> Documentation/sysctl/kernel.txt | 17 +++++++++++++++++
> kernel/softirq.c | 8 +++++---
> kernel/sysctl.c | 9 +++++++++
> 3 files changed, 31 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
> index f0c86fbb3b48..23b36393f150 100644
> --- a/Documentation/sysctl/kernel.txt
> +++ b/Documentation/sysctl/kernel.txt
> @@ -44,6 +44,7 @@ show up in /proc/sys/kernel:
> - kexec_load_disabled
> - kptr_restrict
> - l2cr [ PPC only ]
> +- max_softirq_time_msecs
> - modprobe ==> Documentation/debugging-modules.txt
> - modules_disabled
> - msg_next_id [ sysv ipc ]
> @@ -445,6 +446,22 @@ This flag controls the L2 cache of G3 processor boards. If
>
> ==============================================================
>
> +max_softirq_time_msecs:
> +
> +Maximum number of milliseconds to break the loop of restarting softirq
> +processing for at most MAX_SOFTIRQ_RESTART times in __do_softirq().
> +max_softirq_time_msecs will be coverted to jiffies, and any budget
> +value will be rounded up to the next jiffies, which relates to CONFIG_HZ.
> +The time accuracy of jiffies will result in a certain difference
> +between the setting jiffies of max_softirq_time_msecs and the actual
> +value, which is in one jiffies range.
> +
> +max_softirq_time_msecs is a non-negative integer value, and setting
> +negative value is meaningless and will return error.
> +Default: 2
> +
> +==============================================================
> +
> modules_disabled:
>
> A toggle value indicating if modules are allowed to be loaded
> diff --git a/kernel/softirq.c b/kernel/softirq.c
> index a6b81c6b6bff..1e456db70093 100644
> --- a/kernel/softirq.c
> +++ b/kernel/softirq.c
> @@ -199,7 +199,8 @@ EXPORT_SYMBOL(__local_bh_enable_ip);
>
> /*
> * We restart softirq processing for at most MAX_SOFTIRQ_RESTART times,
> - * but break the loop if need_resched() is set or after 2 ms.
> + * but break the loop if need_resched() is set or after
> + * max_softirq_time_msecs msecs.
> * The MAX_SOFTIRQ_TIME provides a nice upper bound in most cases, but in
> * certain cases, such as stop_machine(), jiffies may cease to
> * increment and so we need the MAX_SOFTIRQ_RESTART limit as
> @@ -210,7 +211,7 @@ EXPORT_SYMBOL(__local_bh_enable_ip);
> * we want to handle softirqs as soon as possible, but they
> * should not be able to lock up the box.
> */
> -#define MAX_SOFTIRQ_TIME msecs_to_jiffies(2)
> +unsigned int __read_mostly max_softirq_time_msecs = 2;
> #define MAX_SOFTIRQ_RESTART 10
>
> #ifdef CONFIG_TRACE_IRQFLAGS
> @@ -248,7 +249,8 @@ static inline void lockdep_softirq_end(bool in_hardirq) { }
>
> asmlinkage __visible void __softirq_entry __do_softirq(void)
> {
> - unsigned long end = jiffies + MAX_SOFTIRQ_TIME;
> + unsigned long end = jiffies +
> + msecs_to_jiffies(max_softirq_time_msecs);
> unsigned long old_flags = current->flags;
> int max_restart = MAX_SOFTIRQ_RESTART;
> struct softirq_action *h;
> diff --git a/kernel/sysctl.c b/kernel/sysctl.c
> index 1beca96fb625..96ff292ce7f6 100644
> --- a/kernel/sysctl.c
> +++ b/kernel/sysctl.c
> @@ -118,6 +118,7 @@ extern unsigned int sysctl_nr_open_min, sysctl_nr_open_max;
> #ifndef CONFIG_MMU
> extern int sysctl_nr_trim_pages;
> #endif
> +extern unsigned int max_softirq_time_msecs;
>
> /* Constants used for minimum and maximum */
> #ifdef CONFIG_LOCKUP_DETECTOR
> @@ -1276,6 +1277,14 @@ static struct ctl_table kern_table[] = {
> .extra2 = &one,
> },
> #endif
> + {
> + .procname = "max_softirq_time_msecs",
> + .data = &max_softirq_time_msecs,
> + .maxlen = sizeof(unsigned int),
> + .mode = 0644,
> + .proc_handler = proc_dointvec_minmax,
> + .extra1 = &zero,
> + },
> { }
> };
>
^ permalink raw reply
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