2020-10-29 07:37:43

by Mauro Carvalho Chehab

Subject: [PATCH 00/33] ABI: add it to the documentation build system

Hi Greg,

As requested, this is a rebased version on the top of v5.10-rc1
adding support for having the Linux ABI documentted inside
the Linux admin manual.

When compared with the version I sent years ago, this
version has:

- a logic to detect duplicated ABI symbols;
- it auto-generate cross-reference markups for ABI symbols,
ABI files and .rst files;
- Other files from 5.10-rc1 required adjustments in order
to be accepted by the script in rst-source mode;
- Some bug fixes.

PS.: I didn't try to merge it against linux-next yet. So,
I won't doubt that applying it could cause some conflicts.

Feel free to review it.

Regards,
Mauro


Mauro Carvalho Chehab (33):
scripts: get_abi.pl: change script to allow parsing in ReST mode
scripts: get_abi.pl: fix parsing on ReST mode
scripts: get_abi.pl: Allow optionally record from where a line came
from
scripts: get_abi.pl: improve its parser to better catch up indentation
scripts: get_abi.pl: cleanup ABI cross-reference logic
scripts: get_abi.pl: detect duplicated ABI definitions
scripts: get_abi.pl: output users in ReST format
scripts: get_abi.pl: prevent duplicated file names
scripts: get_abi.pl: use bold font for ABI definitions
scripts: get_abi.pl: auto-generate cross references
docs: kernellog.py: add support for info()
docs: kernel_abi.py: add a script to parse ABI documentation
docs: kernel_abi.py: fix UTF-8 support
docs: kernel_abi.py: make it compatible with Sphinx 1.7+
docs: kernel_abi.py: use --enable-lineno for get_abi.pl
docs: kernel_abi.py: Handle with a lazy Sphinx parser
docs: add ABI documentation to the admin-guide book
docs: ABI: README: specify that files should be ReST compatible
docs: ABI: stable: make files ReST compatible
docs: ABI: testing: make the files compatible with ReST output
docs: ABI: make it parse ABI/stable as ReST-compatible files
docs: ABI: create a 2-depth index for ABI
docs: ABI: don't escape ReST-incompatible chars from obsolete and
removed
docs: abi-testing.rst: enable --rst-sources when building docs
docs: Kconfig/Makefile: add a check for broken ABI files
docs: ABI: convert testing/configfs-acpi to ReST
docs: ABI: fix syntax to be parsed using ReST notation
docs: ABI: vdso: use the right format for ABI
docs: ABI: sysfs-bus-nvdimm: use the right format for ABI
docs: ABI: cleanup several ABI documents
docs: ABI: change read/write attributes
docs: ABI: stable: remove a duplicated documentation
docs: ABI: unify /sys/class/leds/<led>/max_brightness documentation

Documentation/ABI/README | 10 +-
Documentation/ABI/obsolete/sysfs-class-dax | 8 +-
.../ABI/obsolete/sysfs-driver-hid-roccat-pyra | 3 +
Documentation/ABI/obsolete/sysfs-gpio | 2 +
Documentation/ABI/removed/devfs | 1 +
Documentation/ABI/removed/raw1394 | 1 +
Documentation/ABI/removed/sysfs-class-rfkill | 2 +-
Documentation/ABI/removed/video1394 | 1 +
Documentation/ABI/stable/firewire-cdev | 67 ++--
Documentation/ABI/stable/sysfs-acpi-pmprofile | 26 +-
Documentation/ABI/stable/sysfs-bus-firewire | 3 +
Documentation/ABI/stable/sysfs-bus-nvmem | 19 +-
Documentation/ABI/stable/sysfs-bus-usb | 6 +-
Documentation/ABI/stable/sysfs-bus-vmbus | 7 -
Documentation/ABI/stable/sysfs-bus-w1 | 1 +
.../ABI/stable/sysfs-class-backlight | 1 +
.../ABI/stable/sysfs-class-infiniband | 93 +++--
Documentation/ABI/stable/sysfs-class-rfkill | 13 +-
Documentation/ABI/stable/sysfs-class-tpm | 94 ++---
Documentation/ABI/stable/sysfs-devices | 5 +-
.../ABI/stable/sysfs-driver-firmware-zynqmp | 62 ++--
Documentation/ABI/stable/sysfs-driver-ib_srp | 1 +
Documentation/ABI/stable/sysfs-driver-speakup | 4 +
.../ABI/stable/sysfs-firmware-efi-vars | 4 +
.../ABI/stable/sysfs-firmware-opal-dump | 5 +
.../ABI/stable/sysfs-firmware-opal-elog | 2 +
Documentation/ABI/stable/sysfs-hypervisor-xen | 3 +
Documentation/ABI/stable/vdso | 11 +-
Documentation/ABI/testing/configfs-acpi | 34 +-
Documentation/ABI/testing/configfs-most | 135 ++++---
.../ABI/testing/configfs-spear-pcie-gadget | 36 +-
Documentation/ABI/testing/configfs-usb-gadget | 83 +++--
.../ABI/testing/configfs-usb-gadget-ecm | 12 +-
.../ABI/testing/configfs-usb-gadget-eem | 10 +-
.../ABI/testing/configfs-usb-gadget-hid | 10 +-
.../ABI/testing/configfs-usb-gadget-loopback | 6 +-
.../testing/configfs-usb-gadget-mass-storage | 18 +-
.../ABI/testing/configfs-usb-gadget-midi | 14 +-
.../ABI/testing/configfs-usb-gadget-printer | 6 +-
.../ABI/testing/configfs-usb-gadget-rndis | 16 +-
.../testing/configfs-usb-gadget-sourcesink | 18 +-
.../ABI/testing/configfs-usb-gadget-subset | 10 +-
.../ABI/testing/configfs-usb-gadget-uac1 | 18 +-
.../ABI/testing/configfs-usb-gadget-uac2 | 14 +-
.../ABI/testing/configfs-usb-gadget-uvc | 220 ++++++-----
.../ABI/testing/debugfs-cec-error-inj | 2 +-
.../ABI/testing/debugfs-driver-habanalabs | 12 +-
Documentation/ABI/testing/debugfs-ec | 11 +-
Documentation/ABI/testing/debugfs-moxtet | 30 +-
.../ABI/testing/debugfs-pfo-nx-crypto | 28 +-
Documentation/ABI/testing/debugfs-pktcdvd | 13 +-
.../ABI/testing/debugfs-turris-mox-rwtm | 15 +-
Documentation/ABI/testing/debugfs-wilco-ec | 21 +-
Documentation/ABI/testing/dell-smbios-wmi | 32 +-
Documentation/ABI/testing/dev-kmsg | 27 +-
Documentation/ABI/testing/evm | 17 +-
Documentation/ABI/testing/gpio-cdev | 13 +-
Documentation/ABI/testing/ima_policy | 30 +-
Documentation/ABI/testing/procfs-diskstats | 46 ++-
Documentation/ABI/testing/procfs-smaps_rollup | 48 +--
Documentation/ABI/testing/pstore | 19 +-
Documentation/ABI/testing/sysfs-block | 38 +-
Documentation/ABI/testing/sysfs-block-device | 2 +
Documentation/ABI/testing/sysfs-block-rnbd | 4 +-
Documentation/ABI/testing/sysfs-bus-acpi | 19 +-
.../testing/sysfs-bus-coresight-devices-cti | 60 +--
.../testing/sysfs-bus-coresight-devices-etb10 | 21 +-
.../testing/sysfs-bus-coresight-devices-etm3x | 10 +-
.../testing/sysfs-bus-coresight-devices-etm4x | 76 ++--
.../testing/sysfs-bus-coresight-devices-stm | 2 +-
.../testing/sysfs-bus-coresight-devices-tmc | 20 +-
Documentation/ABI/testing/sysfs-bus-css | 3 +
Documentation/ABI/testing/sysfs-bus-dfl | 2 +
.../sysfs-bus-event_source-devices-dfl_fme | 14 +-
.../sysfs-bus-event_source-devices-format | 3 +-
.../sysfs-bus-event_source-devices-hv_24x7 | 6 +-
.../sysfs-bus-event_source-devices-hv_gpci | 7 +-
Documentation/ABI/testing/sysfs-bus-fcoe | 68 ++--
Documentation/ABI/testing/sysfs-bus-fsl-mc | 12 +-
.../ABI/testing/sysfs-bus-i2c-devices-fsa9480 | 26 +-
.../ABI/testing/sysfs-bus-i2c-devices-pca954x | 27 +-
Documentation/ABI/testing/sysfs-bus-i3c | 2 +
Documentation/ABI/testing/sysfs-bus-iio | 30 +-
.../sysfs-bus-iio-adc-envelope-detector | 5 +-
.../ABI/testing/sysfs-bus-iio-adc-hi8435 | 5 +
.../ABI/testing/sysfs-bus-iio-adc-stm32 | 3 +
.../ABI/testing/sysfs-bus-iio-cros-ec | 2 +-
.../ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 | 8 +-
.../ABI/testing/sysfs-bus-iio-distance-srf08 | 7 +-
.../testing/sysfs-bus-iio-frequency-ad9523 | 2 +
.../testing/sysfs-bus-iio-frequency-adf4371 | 10 +-
.../ABI/testing/sysfs-bus-iio-health-afe440x | 12 +-
.../ABI/testing/sysfs-bus-iio-light-isl29018 | 6 +-
.../ABI/testing/sysfs-bus-iio-lptimer-stm32 | 29 +-
.../sysfs-bus-iio-magnetometer-hmc5843 | 19 +-
.../sysfs-bus-iio-temperature-max31856 | 19 +-
.../ABI/testing/sysfs-bus-iio-timer-stm32 | 137 ++++---
.../testing/sysfs-bus-intel_th-devices-gth | 11 +-
.../testing/sysfs-bus-intel_th-devices-msc | 4 +
Documentation/ABI/testing/sysfs-bus-most | 6 +-
.../ABI/testing/sysfs-bus-moxtet-devices | 6 +-
Documentation/ABI/testing/sysfs-bus-nfit | 2 +-
Documentation/ABI/testing/sysfs-bus-nvdimm | 6 +
Documentation/ABI/testing/sysfs-bus-papr-pmem | 23 +-
Documentation/ABI/testing/sysfs-bus-pci | 22 +-
.../testing/sysfs-bus-pci-devices-aer_stats | 119 +++---
.../ABI/testing/sysfs-bus-pci-devices-catpt | 1 +
.../testing/sysfs-bus-pci-drivers-ehci_hcd | 4 +-
Documentation/ABI/testing/sysfs-bus-rapidio | 23 +-
Documentation/ABI/testing/sysfs-bus-rbd | 37 +-
Documentation/ABI/testing/sysfs-bus-siox | 3 +
.../ABI/testing/sysfs-bus-thunderbolt | 58 +--
Documentation/ABI/testing/sysfs-bus-usb | 32 +-
.../testing/sysfs-bus-usb-devices-usbsevseg | 7 +-
Documentation/ABI/testing/sysfs-bus-vfio-mdev | 10 +-
.../sysfs-class-backlight-driver-lm3533 | 26 +-
Documentation/ABI/testing/sysfs-class-bdi | 1 -
.../ABI/testing/sysfs-class-chromeos | 15 +-
Documentation/ABI/testing/sysfs-class-cxl | 23 +-
Documentation/ABI/testing/sysfs-class-devfreq | 6 +-
Documentation/ABI/testing/sysfs-class-devlink | 30 +-
Documentation/ABI/testing/sysfs-class-extcon | 34 +-
.../ABI/testing/sysfs-class-fpga-manager | 5 +-
Documentation/ABI/testing/sysfs-class-gnss | 2 +
Documentation/ABI/testing/sysfs-class-led | 28 +-
.../testing/sysfs-class-led-driver-el15203000 | 229 ++++++------
.../ABI/testing/sysfs-class-led-driver-lm3533 | 44 ++-
.../ABI/testing/sysfs-class-led-driver-sc27xx | 4 +-
.../ABI/testing/sysfs-class-led-flash | 27 +-
.../ABI/testing/sysfs-class-led-multicolor | 23 +-
.../testing/sysfs-class-led-trigger-netdev | 7 +
.../testing/sysfs-class-led-trigger-usbport | 1 +
.../ABI/testing/sysfs-class-leds-gt683r | 8 +-
Documentation/ABI/testing/sysfs-class-mic | 52 ++-
Documentation/ABI/testing/sysfs-class-net | 61 +++-
.../ABI/testing/sysfs-class-net-cdc_ncm | 6 +-
.../ABI/testing/sysfs-class-net-phydev | 2 +
Documentation/ABI/testing/sysfs-class-ocxl | 17 +-
Documentation/ABI/testing/sysfs-class-pktcdvd | 36 +-
Documentation/ABI/testing/sysfs-class-power | 85 ++++-
.../ABI/testing/sysfs-class-power-mp2629 | 1 +
.../ABI/testing/sysfs-class-power-twl4030 | 33 +-
.../ABI/testing/sysfs-class-power-wilco | 18 +-
Documentation/ABI/testing/sysfs-class-rapidio | 46 +--
Documentation/ABI/testing/sysfs-class-rc | 30 +-
.../ABI/testing/sysfs-class-regulator | 36 +-
.../ABI/testing/sysfs-class-remoteproc | 14 +-
.../ABI/testing/sysfs-class-rnbd-client | 93 ++---
...ysfs-class-rtc-rtc0-device-rtc_calibration | 1 +
.../ABI/testing/sysfs-class-rtrs-client | 23 +-
.../ABI/testing/sysfs-class-scsi_host | 7 +-
Documentation/ABI/testing/sysfs-class-typec | 12 +-
Documentation/ABI/testing/sysfs-class-uwb_rc | 13 +-
.../ABI/testing/sysfs-class-watchdog | 7 +-
Documentation/ABI/testing/sysfs-dev | 7 +-
.../ABI/testing/sysfs-devices-mapping | 41 ++-
.../ABI/testing/sysfs-devices-memory | 15 +-
.../testing/sysfs-devices-platform-ACPI-TAD | 4 +
.../sysfs-devices-platform-_UDC_-gadget | 10 +-
.../ABI/testing/sysfs-devices-platform-docg3 | 10 +-
.../ABI/testing/sysfs-devices-platform-ipmi | 52 +--
.../sysfs-devices-platform-sh_mobile_lcdc_fb | 8 +-
.../sysfs-devices-platform-stratix10-rsu | 10 +
.../ABI/testing/sysfs-devices-system-cpu | 101 ++++--
.../ABI/testing/sysfs-devices-system-ibm-rtl | 6 +-
.../testing/sysfs-driver-bd9571mwv-regulator | 4 +
Documentation/ABI/testing/sysfs-driver-genwqe | 11 +-
.../ABI/testing/sysfs-driver-hid-lenovo | 10 +
.../testing/sysfs-driver-hid-logitech-lg4ff | 18 +-
.../ABI/testing/sysfs-driver-hid-ntrig | 13 +-
.../ABI/testing/sysfs-driver-hid-roccat-kone | 19 +
.../ABI/testing/sysfs-driver-hid-wiimote | 12 +-
.../ABI/testing/sysfs-driver-input-exc3000 | 2 +
.../ABI/testing/sysfs-driver-jz4780-efuse | 6 +-
.../ABI/testing/sysfs-driver-pciback | 6 +-
.../ABI/testing/sysfs-driver-samsung-laptop | 13 +-
.../ABI/testing/sysfs-driver-toshiba_acpi | 26 ++
.../ABI/testing/sysfs-driver-toshiba_haps | 2 +
Documentation/ABI/testing/sysfs-driver-ufs | 228 +++++++++---
.../ABI/testing/sysfs-driver-w1_ds28e17 | 3 +
.../ABI/testing/sysfs-driver-w1_therm | 75 ++--
Documentation/ABI/testing/sysfs-driver-wacom | 4 +-
Documentation/ABI/testing/sysfs-firmware-acpi | 237 ++++++------
.../ABI/testing/sysfs-firmware-dmi-entries | 50 +--
.../ABI/testing/sysfs-firmware-efi-esrt | 28 +-
.../testing/sysfs-firmware-efi-runtime-map | 14 +-
Documentation/ABI/testing/sysfs-firmware-gsmi | 2 +-
.../ABI/testing/sysfs-firmware-memmap | 16 +-
.../ABI/testing/sysfs-firmware-qemu_fw_cfg | 20 +-
Documentation/ABI/testing/sysfs-firmware-sfi | 6 +-
.../ABI/testing/sysfs-firmware-sgi_uv | 6 +-
.../testing/sysfs-firmware-turris-mox-rwtm | 10 +-
Documentation/ABI/testing/sysfs-fs-ext4 | 4 +-
Documentation/ABI/testing/sysfs-fs-f2fs | 48 ++-
.../ABI/testing/sysfs-hypervisor-xen | 13 +-
.../ABI/testing/sysfs-kernel-boot_params | 23 +-
.../ABI/testing/sysfs-kernel-mm-hugepages | 12 +-
Documentation/ABI/testing/sysfs-kernel-mm-ksm | 5 +-
Documentation/ABI/testing/sysfs-kernel-slab | 3 +
Documentation/ABI/testing/sysfs-module | 17 +-
.../ABI/testing/sysfs-platform-asus-laptop | 21 +-
.../ABI/testing/sysfs-platform-asus-wmi | 1 +
Documentation/ABI/testing/sysfs-platform-at91 | 10 +-
.../ABI/testing/sysfs-platform-dell-laptop | 10 +-
.../ABI/testing/sysfs-platform-dell-smbios | 4 +-
.../ABI/testing/sysfs-platform-dfl-fme | 14 +-
Documentation/ABI/testing/sysfs-platform-dptf | 11 +-
.../ABI/testing/sysfs-platform-eeepc-laptop | 14 +-
.../testing/sysfs-platform-i2c-demux-pinctrl | 4 +-
.../ABI/testing/sysfs-platform-ideapad-laptop | 9 +-
.../sysfs-platform-intel-wmi-sbl-fw-update | 1 +
.../sysfs-platform-intel-wmi-thunderbolt | 1 +
Documentation/ABI/testing/sysfs-platform-kim | 1 +
.../testing/sysfs-platform-mellanox-bootctl | 50 ++-
.../testing/sysfs-platform-phy-rcar-gen3-usb2 | 10 +-
.../ABI/testing/sysfs-platform-renesas_usb3 | 10 +-
.../ABI/testing/sysfs-platform-sst-atom | 13 +-
.../ABI/testing/sysfs-platform-usbip-vudc | 11 +-
.../ABI/testing/sysfs-platform-wilco-ec | 1 +
Documentation/ABI/testing/sysfs-power | 21 +-
Documentation/ABI/testing/sysfs-profiling | 2 +-
Documentation/ABI/testing/sysfs-ptp | 2 +-
Documentation/ABI/testing/sysfs-uevent | 10 +-
Documentation/ABI/testing/sysfs-wusb_cbaf | 3 +-
Documentation/ABI/testing/usb-charger-uevent | 82 +++--
Documentation/ABI/testing/usb-uevent | 32 +-
Documentation/Kconfig | 10 +
Documentation/Makefile | 5 +
Documentation/admin-guide/abi-obsolete.rst | 11 +
Documentation/admin-guide/abi-removed.rst | 5 +
Documentation/admin-guide/abi-stable.rst | 14 +
Documentation/admin-guide/abi-testing.rst | 20 +
Documentation/admin-guide/abi.rst | 11 +
Documentation/admin-guide/index.rst | 2 +
Documentation/conf.py | 3 +-
Documentation/sphinx/kernel_abi.py | 194 ++++++++++
Documentation/sphinx/kernellog.py | 6 +-
lib/Kconfig.debug | 2 +
scripts/get_abi.pl | 342 ++++++++++++------
239 files changed, 3767 insertions(+), 2111 deletions(-)
create mode 100644 Documentation/admin-guide/abi-obsolete.rst
create mode 100644 Documentation/admin-guide/abi-removed.rst
create mode 100644 Documentation/admin-guide/abi-stable.rst
create mode 100644 Documentation/admin-guide/abi-testing.rst
create mode 100644 Documentation/admin-guide/abi.rst
create mode 100644 Documentation/sphinx/kernel_abi.py

--
2.26.2

2020-10-29 08:38:57

by Greg Kroah-Hartman

Subject: Re: [PATCH 00/33] ABI: add it to the documentation build system

On Wed, Oct 28, 2020 at 03:22:58PM +0100, Mauro Carvalho Chehab wrote:
> Hi Greg,
>
> As requested, this is a rebased version on the top of v5.10-rc1
> adding support for having the Linux ABI documentted inside
> the Linux admin manual.
>
> When compared with the version I sent years ago, this
> version has:
>
> - a logic to detect duplicated ABI symbols;
> - it auto-generate cross-reference markups for ABI symbols,
> ABI files and .rst files;
> - Other files from 5.10-rc1 required adjustments in order
> to be accepted by the script in rst-source mode;
> - Some bug fixes.
>
> PS.: I didn't try to merge it against linux-next yet. So,
> I won't doubt that applying it could cause some conflicts.
>
> Feel free to review it.

After applying the first 10 patches, and running it, I see a bunch of
these types of warnings:

Use of uninitialized value $kernelversion in substitution (s///) at ./scripts/get_abi.pl line 444.
Use of uninitialized value $users in substitution (s///) at ./scripts/get_abi.pl line 446.
Use of uninitialized value $users in substitution (s///) at ./scripts/get_abi.pl line 447.

When doing something like:
$ ./scripts/get_abi.pl search usb --dir Documentation/ABI/stable/

Is that expected?

thanks,

greg k-h

2020-10-29 08:38:59

by Mauro Carvalho Chehab

Subject: [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output

From: Mauro Carvalho Chehab <[email protected]>

Some files over there won't parse well by Sphinx.

Fix them.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../ABI/testing/configfs-spear-pcie-gadget | 36 +--
Documentation/ABI/testing/configfs-usb-gadget | 83 +++---
.../ABI/testing/configfs-usb-gadget-hid | 10 +-
.../ABI/testing/configfs-usb-gadget-rndis | 16 +-
.../ABI/testing/configfs-usb-gadget-uac1 | 18 +-
.../ABI/testing/configfs-usb-gadget-uvc | 220 +++++++++-------
Documentation/ABI/testing/debugfs-ec | 11 +-
Documentation/ABI/testing/debugfs-pktcdvd | 11 +-
Documentation/ABI/testing/dev-kmsg | 27 +-
Documentation/ABI/testing/evm | 17 +-
Documentation/ABI/testing/ima_policy | 30 ++-
Documentation/ABI/testing/procfs-diskstats | 40 +--
Documentation/ABI/testing/sysfs-block | 38 +--
Documentation/ABI/testing/sysfs-block-device | 2 +
Documentation/ABI/testing/sysfs-bus-acpi | 18 +-
.../sysfs-bus-event_source-devices-format | 3 +-
.../ABI/testing/sysfs-bus-i2c-devices-pca954x | 27 +-
Documentation/ABI/testing/sysfs-bus-iio | 11 +
.../sysfs-bus-iio-adc-envelope-detector | 5 +-
.../ABI/testing/sysfs-bus-iio-cros-ec | 2 +-
.../ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 | 8 +-
.../ABI/testing/sysfs-bus-iio-lptimer-stm32 | 29 ++-
.../sysfs-bus-iio-magnetometer-hmc5843 | 19 +-
.../sysfs-bus-iio-temperature-max31856 | 19 +-
.../ABI/testing/sysfs-bus-iio-timer-stm32 | 137 ++++++----
.../testing/sysfs-bus-intel_th-devices-msc | 4 +
Documentation/ABI/testing/sysfs-bus-nfit | 2 +-
.../testing/sysfs-bus-pci-devices-aer_stats | 119 +++++----
Documentation/ABI/testing/sysfs-bus-rapidio | 23 +-
.../ABI/testing/sysfs-bus-thunderbolt | 40 +--
Documentation/ABI/testing/sysfs-bus-usb | 30 ++-
.../testing/sysfs-bus-usb-devices-usbsevseg | 7 +-
Documentation/ABI/testing/sysfs-bus-vfio-mdev | 10 +-
Documentation/ABI/testing/sysfs-class-cxl | 15 +-
Documentation/ABI/testing/sysfs-class-led | 2 +-
.../testing/sysfs-class-led-driver-el15203000 | 229 ++++++++---------
.../ABI/testing/sysfs-class-led-driver-sc27xx | 4 +-
Documentation/ABI/testing/sysfs-class-mic | 52 ++--
Documentation/ABI/testing/sysfs-class-ocxl | 3 +
Documentation/ABI/testing/sysfs-class-power | 73 +++++-
.../ABI/testing/sysfs-class-power-twl4030 | 33 +--
Documentation/ABI/testing/sysfs-class-rc | 30 ++-
.../ABI/testing/sysfs-class-scsi_host | 7 +-
Documentation/ABI/testing/sysfs-class-typec | 12 +-
.../testing/sysfs-devices-platform-ACPI-TAD | 4 +
.../ABI/testing/sysfs-devices-platform-docg3 | 10 +-
.../sysfs-devices-platform-sh_mobile_lcdc_fb | 8 +-
.../ABI/testing/sysfs-devices-system-cpu | 99 +++++---
.../ABI/testing/sysfs-devices-system-ibm-rtl | 6 +-
.../testing/sysfs-driver-bd9571mwv-regulator | 4 +
Documentation/ABI/testing/sysfs-driver-genwqe | 11 +-
.../testing/sysfs-driver-hid-logitech-lg4ff | 18 +-
.../ABI/testing/sysfs-driver-hid-wiimote | 11 +-
.../ABI/testing/sysfs-driver-samsung-laptop | 13 +-
.../ABI/testing/sysfs-driver-toshiba_acpi | 26 ++
.../ABI/testing/sysfs-driver-toshiba_haps | 2 +
Documentation/ABI/testing/sysfs-driver-wacom | 4 +-
Documentation/ABI/testing/sysfs-firmware-acpi | 237 +++++++++---------
.../ABI/testing/sysfs-firmware-dmi-entries | 50 ++--
Documentation/ABI/testing/sysfs-firmware-gsmi | 2 +-
.../ABI/testing/sysfs-firmware-memmap | 16 +-
Documentation/ABI/testing/sysfs-fs-ext4 | 4 +-
.../ABI/testing/sysfs-hypervisor-xen | 13 +-
.../ABI/testing/sysfs-kernel-boot_params | 23 +-
.../ABI/testing/sysfs-kernel-mm-hugepages | 12 +-
.../ABI/testing/sysfs-platform-asus-laptop | 21 +-
.../ABI/testing/sysfs-platform-asus-wmi | 1 +
Documentation/ABI/testing/sysfs-platform-at91 | 10 +-
.../ABI/testing/sysfs-platform-eeepc-laptop | 14 +-
.../ABI/testing/sysfs-platform-ideapad-laptop | 9 +-
.../sysfs-platform-intel-wmi-thunderbolt | 1 +
.../ABI/testing/sysfs-platform-sst-atom | 13 +-
.../ABI/testing/sysfs-platform-usbip-vudc | 11 +-
Documentation/ABI/testing/sysfs-ptp | 2 +-
Documentation/ABI/testing/sysfs-uevent | 10 +-
75 files changed, 1328 insertions(+), 869 deletions(-)

diff --git a/Documentation/ABI/testing/configfs-spear-pcie-gadget b/Documentation/ABI/testing/configfs-spear-pcie-gadget
index 840c324ef34d..cf877bd341df 100644
--- a/Documentation/ABI/testing/configfs-spear-pcie-gadget
+++ b/Documentation/ABI/testing/configfs-spear-pcie-gadget
@@ -10,22 +10,24 @@ Description:
This interfaces can be used to show spear's PCIe device capability.

Nodes are only visible when configfs is mounted. To mount configfs
- in /config directory use:
- # mount -t configfs none /config/
+ in /config directory use::

- For nth PCIe Device Controller
- /config/pcie-gadget.n/
- link ... used to enable ltssm and read its status.
- int_type ...used to configure and read type of supported
- interrupt
- no_of_msi ... used to configure number of MSI vector needed and
+ # mount -t configfs none /config/
+
+ For nth PCIe Device Controller /config/pcie-gadget.n/:
+
+ =============== ======================================================
+ link used to enable ltssm and read its status.
+ int_type used to configure and read type of supported interrupt
+ no_of_msi used to configure number of MSI vector needed and
to read no of MSI granted.
- inta ... write 1 to assert INTA and 0 to de-assert.
- send_msi ... write MSI vector to be sent.
- vendor_id ... used to write and read vendor id (hex)
- device_id ... used to write and read device id (hex)
- bar0_size ... used to write and read bar0_size
- bar0_address ... used to write and read bar0 mapped area in hex.
- bar0_rw_offset ... used to write and read offset of bar0 where
- bar0_data will be written or read.
- bar0_data ... used to write and read data at bar0_rw_offset.
+ inta write 1 to assert INTA and 0 to de-assert.
+ send_msi write MSI vector to be sent.
+ vendor_id used to write and read vendor id (hex)
+ device_id used to write and read device id (hex)
+ bar0_size used to write and read bar0_size
+ bar0_address used to write and read bar0 mapped area in hex.
+ bar0_rw_offset used to write and read offset of bar0 where bar0_data
+ will be written or read.
+ bar0_data used to write and read data at bar0_rw_offset.
+ =============== ======================================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget
index 4594cc2435e8..dc351e9af80a 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget
+++ b/Documentation/ABI/testing/configfs-usb-gadget
@@ -12,22 +12,24 @@ Description:

The attributes of a gadget:

- UDC - bind a gadget to UDC/unbind a gadget;
- write UDC's name found in /sys/class/udc/*
- to bind a gadget, empty string "" to unbind.
+ ================ ============================================
+ UDC bind a gadget to UDC/unbind a gadget;
+ write UDC's name found in /sys/class/udc/*
+ to bind a gadget, empty string "" to unbind.

- max_speed - maximum speed the driver supports. Valid
- names are super-speed-plus, super-speed,
- high-speed, full-speed, and low-speed.
+ max_speed maximum speed the driver supports. Valid
+ names are super-speed-plus, super-speed,
+ high-speed, full-speed, and low-speed.

- bDeviceClass - USB device class code
- bDeviceSubClass - USB device subclass code
- bDeviceProtocol - USB device protocol code
- bMaxPacketSize0 - maximum endpoint 0 packet size
- bcdDevice - bcd device release number
- bcdUSB - bcd USB specification version number
- idProduct - product ID
- idVendor - vendor ID
+ bDeviceClass USB device class code
+ bDeviceSubClass USB device subclass code
+ bDeviceProtocol USB device protocol code
+ bMaxPacketSize0 maximum endpoint 0 packet size
+ bcdDevice bcd device release number
+ bcdUSB bcd USB specification version number
+ idProduct product ID
+ idVendor vendor ID
+ ================ ============================================

What: /config/usb-gadget/gadget/configs
Date: Jun 2013
@@ -41,8 +43,10 @@ KernelVersion: 3.11
Description:
The attributes of a configuration:

- bmAttributes - configuration characteristics
- MaxPower - maximum power consumption from the bus
+ ================ ======================================
+ bmAttributes configuration characteristics
+ MaxPower maximum power consumption from the bus
+ ================ ======================================

What: /config/usb-gadget/gadget/configs/config/strings
Date: Jun 2013
@@ -57,7 +61,9 @@ KernelVersion: 3.11
Description:
The attributes:

- configuration - configuration description
+ ================ =========================
+ configuration configuration description
+ ================ =========================


What: /config/usb-gadget/gadget/functions
@@ -76,8 +82,10 @@ Description:

The attributes:

- compatible_id - 8-byte string for "Compatible ID"
- sub_compatible_id - 8-byte string for "Sub Compatible ID"
+ ================= =====================================
+ compatible_id 8-byte string for "Compatible ID"
+ sub_compatible_id 8-byte string for "Sub Compatible ID"
+ ================= =====================================

What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>/<property>
Date: May 2014
@@ -89,16 +97,19 @@ Description:

The attributes:

- type - value 1..7 for interpreting the data
- 1: unicode string
- 2: unicode string with environment variable
- 3: binary
- 4: little-endian 32-bit
- 5: big-endian 32-bit
- 6: unicode string with a symbolic link
- 7: multiple unicode strings
- data - blob of data to be interpreted depending on
+ ===== ===============================================
+ type value 1..7 for interpreting the data
+
+ - 1: unicode string
+ - 2: unicode string with environment variable
+ - 3: binary
+ - 4: little-endian 32-bit
+ - 5: big-endian 32-bit
+ - 6: unicode string with a symbolic link
+ - 7: multiple unicode strings
+ data blob of data to be interpreted depending on
type
+ ===== ===============================================

What: /config/usb-gadget/gadget/strings
Date: Jun 2013
@@ -113,9 +124,11 @@ KernelVersion: 3.11
Description:
The attributes:

- serialnumber - gadget's serial number (string)
- product - gadget's product description
- manufacturer - gadget's manufacturer description
+ ============ =================================
+ serialnumber gadget's serial number (string)
+ product gadget's product description
+ manufacturer gadget's manufacturer description
+ ============ =================================

What: /config/usb-gadget/gadget/os_desc
Date: May 2014
@@ -123,8 +136,10 @@ KernelVersion: 3.16
Description:
This group contains "OS String" extension handling attributes.

- use - flag turning "OS Desctiptors" support on/off
- b_vendor_code - one-byte value used for custom per-device and
+ ============= ===============================================
+ use flag turning "OS Desctiptors" support on/off
+ b_vendor_code one-byte value used for custom per-device and
per-interface requests
- qw_sign - an identifier to be reported as "OS String"
+ qw_sign an identifier to be reported as "OS String"
proper
+ ============= ===============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-hid b/Documentation/ABI/testing/configfs-usb-gadget-hid
index f12e00e6baa3..748705c4cb58 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-hid
+++ b/Documentation/ABI/testing/configfs-usb-gadget-hid
@@ -4,8 +4,10 @@ KernelVersion: 3.19
Description:
The attributes:

- protocol - HID protocol to use
- report_desc - blob corresponding to HID report descriptors
+ ============= ============================================
+ protocol HID protocol to use
+ report_desc blob corresponding to HID report descriptors
except the data passed through /dev/hidg<N>
- report_length - HID report length
- subclass - HID device subclass to use
+ report_length HID report length
+ subclass HID device subclass to use
+ ============= ============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis
index 137399095d74..9416eda7fe93 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-rndis
+++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis
@@ -4,14 +4,16 @@ KernelVersion: 3.11
Description:
The attributes:

- ifname - network device interface name associated with
+ ========= =============================================
+ ifname network device interface name associated with
this function instance
- qmult - queue length multiplier for high and
+ qmult queue length multiplier for high and
super speed
- host_addr - MAC address of host's end of this
+ host_addr MAC address of host's end of this
Ethernet over USB link
- dev_addr - MAC address of device's end of this
+ dev_addr MAC address of device's end of this
Ethernet over USB link
- class - USB interface class, default is 02 (hex)
- subclass - USB interface subclass, default is 06 (hex)
- protocol - USB interface protocol, default is 00 (hex)
+ class USB interface class, default is 02 (hex)
+ subclass USB interface subclass, default is 06 (hex)
+ protocol USB interface protocol, default is 00 (hex)
+ ========= =============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1
index abfe447c848f..dc23fd776943 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uac1
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1
@@ -4,11 +4,13 @@ KernelVersion: 4.14
Description:
The attributes:

- c_chmask - capture channel mask
- c_srate - capture sampling rate
- c_ssize - capture sample size (bytes)
- p_chmask - playback channel mask
- p_srate - playback sampling rate
- p_ssize - playback sample size (bytes)
- req_number - the number of pre-allocated request
- for both capture and playback
+ ========== ===================================
+ c_chmask capture channel mask
+ c_srate capture sampling rate
+ c_ssize capture sample size (bytes)
+ p_chmask playback channel mask
+ p_srate playback sampling rate
+ p_ssize playback sample size (bytes)
+ req_number the number of pre-allocated request
+ for both capture and playback
+ ========== ===================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc
index 809765bd9573..cee81b0347bb 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uvc
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc
@@ -3,9 +3,11 @@ Date: Dec 2014
KernelVersion: 4.0
Description: UVC function directory

- streaming_maxburst - 0..15 (ss only)
- streaming_maxpacket - 1..1023 (fs), 1..3072 (hs/ss)
- streaming_interval - 1..16
+ =================== =============================
+ streaming_maxburst 0..15 (ss only)
+ streaming_maxpacket 1..1023 (fs), 1..3072 (hs/ss)
+ streaming_interval 1..16
+ =================== =============================

What: /config/usb-gadget/gadget/functions/uvc.name/control
Date: Dec 2014
@@ -13,8 +15,11 @@ KernelVersion: 4.0
Description: Control descriptors

All attributes read only:
- bInterfaceNumber - USB interface number for this
- streaming interface
+
+ ================ =============================
+ bInterfaceNumber USB interface number for this
+ streaming interface
+ ================ =============================

What: /config/usb-gadget/gadget/functions/uvc.name/control/class
Date: Dec 2014
@@ -47,13 +52,16 @@ KernelVersion: 4.0
Description: Default output terminal descriptors

All attributes read only:
- iTerminal - index of string descriptor
- bSourceID - id of the terminal to which this terminal
+
+ ============== =============================================
+ iTerminal index of string descriptor
+ bSourceID id of the terminal to which this terminal
is connected
- bAssocTerminal - id of the input terminal to which this output
+ bAssocTerminal id of the input terminal to which this output
terminal is associated
- wTerminalType - terminal type
- bTerminalID - a non-zero id of this terminal
+ wTerminalType terminal type
+ bTerminalID a non-zero id of this terminal
+ ============== =============================================

What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera
Date: Dec 2014
@@ -66,16 +74,19 @@ KernelVersion: 4.0
Description: Default camera terminal descriptors

All attributes read only:
- bmControls - bitmap specifying which controls are
- supported for the video stream
- wOcularFocalLength - the value of Locular
- wObjectiveFocalLengthMax- the value of Lmin
- wObjectiveFocalLengthMin- the value of Lmax
- iTerminal - index of string descriptor
- bAssocTerminal - id of the output terminal to which
- this terminal is connected
- wTerminalType - terminal type
- bTerminalID - a non-zero id of this terminal
+
+ ======================== ====================================
+ bmControls bitmap specifying which controls are
+ supported for the video stream
+ wOcularFocalLength the value of Locular
+ wObjectiveFocalLengthMax the value of Lmin
+ wObjectiveFocalLengthMin the value of Lmax
+ iTerminal index of string descriptor
+ bAssocTerminal id of the output terminal to which
+ this terminal is connected
+ wTerminalType terminal type
+ bTerminalID a non-zero id of this terminal
+ ======================== ====================================

What: /config/usb-gadget/gadget/functions/uvc.name/control/processing
Date: Dec 2014
@@ -88,13 +99,16 @@ KernelVersion: 4.0
Description: Default processing unit descriptors

All attributes read only:
- iProcessing - index of string descriptor
- bmControls - bitmap specifying which controls are
+
+ =============== ========================================
+ iProcessing index of string descriptor
+ bmControls bitmap specifying which controls are
supported for the video stream
- wMaxMultiplier - maximum digital magnification x100
- bSourceID - id of the terminal to which this unit is
+ wMaxMultiplier maximum digital magnification x100
+ bSourceID id of the terminal to which this unit is
connected
- bUnitID - a non-zero id of this unit
+ bUnitID a non-zero id of this unit
+ =============== ========================================

What: /config/usb-gadget/gadget/functions/uvc.name/control/header
Date: Dec 2014
@@ -114,8 +128,11 @@ KernelVersion: 4.0
Description: Streaming descriptors

All attributes read only:
- bInterfaceNumber - USB interface number for this
- streaming interface
+
+ ================ =============================
+ bInterfaceNumber USB interface number for this
+ streaming interface
+ ================ =============================

What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class
Date: Dec 2014
@@ -148,13 +165,16 @@ KernelVersion: 4.0
Description: Default color matching descriptors

All attributes read only:
- bMatrixCoefficients - matrix used to compute luma and
- chroma values from the color primaries
- bTransferCharacteristics- optoelectronic transfer
- characteristic of the source picutre,
- also called the gamma function
- bColorPrimaries - color primaries and the reference
- white
+
+ ======================== ======================================
+ bMatrixCoefficients matrix used to compute luma and
+ chroma values from the color primaries
+ bTransferCharacteristics optoelectronic transfer
+ characteristic of the source picutre,
+ also called the gamma function
+ bColorPrimaries color primaries and the reference
+ white
+ ======================== ======================================

What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg
Date: Dec 2014
@@ -168,47 +188,52 @@ Description: Specific MJPEG format descriptors

All attributes read only,
except bmaControls and bDefaultFrameIndex:
- bFormatIndex - unique id for this format descriptor;
+
+ =================== =====================================
+ bFormatIndex unique id for this format descriptor;
only defined after parent header is
linked into the streaming class;
read-only
- bmaControls - this format's data for bmaControls in
+ bmaControls this format's data for bmaControls in
the streaming header
- bmInterfaceFlags - specifies interlace information,
+ bmInterfaceFlags specifies interlace information,
read-only
- bAspectRatioY - the X dimension of the picture aspect
+ bAspectRatioY the X dimension of the picture aspect
ratio, read-only
- bAspectRatioX - the Y dimension of the picture aspect
+ bAspectRatioX the Y dimension of the picture aspect
ratio, read-only
- bmFlags - characteristics of this format,
+ bmFlags characteristics of this format,
read-only
- bDefaultFrameIndex - optimum frame index for this stream
+ bDefaultFrameIndex optimum frame index for this stream
+ =================== =====================================

What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name/name
Date: Dec 2014
KernelVersion: 4.0
Description: Specific MJPEG frame descriptors

- bFrameIndex - unique id for this framedescriptor;
- only defined after parent format is
- linked into the streaming header;
- read-only
- dwFrameInterval - indicates how frame interval can be
- programmed; a number of values
- separated by newline can be specified
- dwDefaultFrameInterval - the frame interval the device would
- like to use as default
- dwMaxVideoFrameBufferSize- the maximum number of bytes the
- compressor will produce for a video
- frame or still image
- dwMaxBitRate - the maximum bit rate at the shortest
- frame interval in bps
- dwMinBitRate - the minimum bit rate at the longest
- frame interval in bps
- wHeight - height of decoded bitmap frame in px
- wWidth - width of decoded bitmam frame in px
- bmCapabilities - still image support, fixed frame-rate
- support
+ ========================= =====================================
+ bFrameIndex unique id for this framedescriptor;
+ only defined after parent format is
+ linked into the streaming header;
+ read-only
+ dwFrameInterval indicates how frame interval can be
+ programmed; a number of values
+ separated by newline can be specified
+ dwDefaultFrameInterval the frame interval the device would
+ like to use as default
+ dwMaxVideoFrameBufferSize the maximum number of bytes the
+ compressor will produce for a video
+ frame or still image
+ dwMaxBitRate the maximum bit rate at the shortest
+ frame interval in bps
+ dwMinBitRate the minimum bit rate at the longest
+ frame interval in bps
+ wHeight height of decoded bitmap frame in px
+ wWidth width of decoded bitmam frame in px
+ bmCapabilities still image support, fixed frame-rate
+ support
+ ========================= =====================================

What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed
Date: Dec 2014
@@ -220,50 +245,54 @@ Date: Dec 2014
KernelVersion: 4.0
Description: Specific uncompressed format descriptors

- bFormatIndex - unique id for this format descriptor;
+ ================== =======================================
+ bFormatIndex unique id for this format descriptor;
only defined after parent header is
linked into the streaming class;
read-only
- bmaControls - this format's data for bmaControls in
+ bmaControls this format's data for bmaControls in
the streaming header
- bmInterfaceFlags - specifies interlace information,
+ bmInterfaceFlags specifies interlace information,
read-only
- bAspectRatioY - the X dimension of the picture aspect
+ bAspectRatioY the X dimension of the picture aspect
ratio, read-only
- bAspectRatioX - the Y dimension of the picture aspect
+ bAspectRatioX the Y dimension of the picture aspect
ratio, read-only
- bDefaultFrameIndex - optimum frame index for this stream
- bBitsPerPixel - number of bits per pixel used to
+ bDefaultFrameIndex optimum frame index for this stream
+ bBitsPerPixel number of bits per pixel used to
specify color in the decoded video
frame
- guidFormat - globally unique id used to identify
+ guidFormat globally unique id used to identify
stream-encoding format
+ ================== =======================================

What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name/name
Date: Dec 2014
KernelVersion: 4.0
Description: Specific uncompressed frame descriptors

- bFrameIndex - unique id for this framedescriptor;
- only defined after parent format is
- linked into the streaming header;
- read-only
- dwFrameInterval - indicates how frame interval can be
- programmed; a number of values
- separated by newline can be specified
- dwDefaultFrameInterval - the frame interval the device would
- like to use as default
- dwMaxVideoFrameBufferSize- the maximum number of bytes the
- compressor will produce for a video
- frame or still image
- dwMaxBitRate - the maximum bit rate at the shortest
- frame interval in bps
- dwMinBitRate - the minimum bit rate at the longest
- frame interval in bps
- wHeight - height of decoded bitmap frame in px
- wWidth - width of decoded bitmam frame in px
- bmCapabilities - still image support, fixed frame-rate
- support
+ ========================= =====================================
+ bFrameIndex unique id for this framedescriptor;
+ only defined after parent format is
+ linked into the streaming header;
+ read-only
+ dwFrameInterval indicates how frame interval can be
+ programmed; a number of values
+ separated by newline can be specified
+ dwDefaultFrameInterval the frame interval the device would
+ like to use as default
+ dwMaxVideoFrameBufferSize the maximum number of bytes the
+ compressor will produce for a video
+ frame or still image
+ dwMaxBitRate the maximum bit rate at the shortest
+ frame interval in bps
+ dwMinBitRate the minimum bit rate at the longest
+ frame interval in bps
+ wHeight height of decoded bitmap frame in px
+ wWidth width of decoded bitmam frame in px
+ bmCapabilities still image support, fixed frame-rate
+ support
+ ========================= =====================================

What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header
Date: Dec 2014
@@ -276,17 +305,20 @@ KernelVersion: 4.0
Description: Specific streaming header descriptors

All attributes read only:
- bTriggerUsage - how the host software will respond to
+
+ ==================== =====================================
+ bTriggerUsage how the host software will respond to
a hardware trigger interrupt event
- bTriggerSupport - flag specifying if hardware
+ bTriggerSupport flag specifying if hardware
triggering is supported
- bStillCaptureMethod - method of still image caputre
+ bStillCaptureMethod method of still image caputre
supported
- bTerminalLink - id of the output terminal to which
+ bTerminalLink id of the output terminal to which
the video endpoint of this interface
is connected
- bmInfo - capabilities of this video streaming
+ bmInfo capabilities of this video streaming
interface
+ ==================== =====================================

What: /sys/class/udc/udc.name/device/gadget/video4linux/video.name/function_name
Date: May 2018
diff --git a/Documentation/ABI/testing/debugfs-ec b/Documentation/ABI/testing/debugfs-ec
index 6546115a94da..ab6099daa8f5 100644
--- a/Documentation/ABI/testing/debugfs-ec
+++ b/Documentation/ABI/testing/debugfs-ec
@@ -6,7 +6,7 @@ Description:
General information like which GPE is assigned to the EC and whether
the global lock should get used.
Knowing the EC GPE one can watch the amount of HW events related to
-the EC here (XY -> GPE number from /sys/kernel/debug/ec/*/gpe):
+the EC here (XY -> GPE number from `/sys/kernel/debug/ec/*/gpe`):
/sys/firmware/acpi/interrupts/gpeXY

The io file is binary and a userspace tool located here:
@@ -14,7 +14,8 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec/
should get used to read out the 256 Embedded Controller registers
or writing to them.

-CAUTION: Do not write to the Embedded Controller if you don't know
-what you are doing! Rebooting afterwards also is a good idea.
-This can influence the way your machine is cooled and fans may
-not get switched on again after you did a wrong write.
+CAUTION:
+ Do not write to the Embedded Controller if you don't know
+ what you are doing! Rebooting afterwards also is a good idea.
+ This can influence the way your machine is cooled and fans may
+ not get switched on again after you did a wrong write.
diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd
index cf11736acb76..787907d70462 100644
--- a/Documentation/ABI/testing/debugfs-pktcdvd
+++ b/Documentation/ABI/testing/debugfs-pktcdvd
@@ -4,16 +4,15 @@ KernelVersion: 2.6.20
Contact: Thomas Maier <[email protected]>
Description:

-debugfs interface
------------------
-
The pktcdvd module (packet writing driver) creates
these files in debugfs:

/sys/kernel/debug/pktcdvd/pktcdvd[0-7]/
+
+ ==== ====== ====================================
info (0444) Lots of driver statistics and infos.
+ ==== ====== ====================================

-Example:
--------
+Example::

-cat /sys/kernel/debug/pktcdvd/pktcdvd0/info
+ cat /sys/kernel/debug/pktcdvd/pktcdvd0/info
diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg
index 3c0bb76e3417..a377b6c093c9 100644
--- a/Documentation/ABI/testing/dev-kmsg
+++ b/Documentation/ABI/testing/dev-kmsg
@@ -6,6 +6,7 @@ Description: The /dev/kmsg character device node provides userspace access
to the kernel's printk buffer.

Injecting messages:
+
Every write() to the opened device node places a log entry in
the kernel's printk buffer.

@@ -21,6 +22,7 @@ Description: The /dev/kmsg character device node provides userspace access
the messages can always be reliably determined.

Accessing the buffer:
+
Every read() from the opened device node receives one record
of the kernel's printk buffer.

@@ -48,6 +50,7 @@ Description: The /dev/kmsg character device node provides userspace access
if needed, without limiting the interface to a single reader.

The device supports seek with the following parameters:
+
SEEK_SET, 0
seek to the first entry in the buffer
SEEK_END, 0
@@ -87,18 +90,22 @@ Description: The /dev/kmsg character device node provides userspace access
readable context of the message, for reliable processing in
userspace.

- Example:
- 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored)
- SUBSYSTEM=acpi
- DEVICE=+acpi:PNP0A03:00
- 6,339,5140900,-;NET: Registered protocol family 10
- 30,340,5690716,-;udevd[80]: starting version 181
+ Example::
+
+ 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored)
+ SUBSYSTEM=acpi
+ DEVICE=+acpi:PNP0A03:00
+ 6,339,5140900,-;NET: Registered protocol family 10
+ 30,340,5690716,-;udevd[80]: starting version 181

The DEVICE= key uniquely identifies devices the following way:
- b12:8 - block dev_t
- c127:3 - char dev_t
- n8 - netdev ifindex
- +sound:card0 - subsystem:devname
+
+ ============ =================
+ b12:8 block dev_t
+ c127:3 char dev_t
+ n8 netdev ifindex
+ +sound:card0 subsystem:devname
+ ============ =================

The flags field carries '-' by default. A 'c' indicates a
fragment of a line. Note, that these hints about continuation
diff --git a/Documentation/ABI/testing/evm b/Documentation/ABI/testing/evm
index 201d10319fa1..3c477ba48a31 100644
--- a/Documentation/ABI/testing/evm
+++ b/Documentation/ABI/testing/evm
@@ -17,26 +17,33 @@ Description:
echoing a value to <securityfs>/evm made up of the
following bits:

+ === ==================================================
Bit Effect
+ === ==================================================
0 Enable HMAC validation and creation
1 Enable digital signature validation
2 Permit modification of EVM-protected metadata at
runtime. Not supported if HMAC validation and
creation is enabled.
31 Disable further runtime modification of EVM policy
+ === ==================================================

- For example:
+ For example::

- echo 1 ><securityfs>/evm
+ echo 1 ><securityfs>/evm

will enable HMAC validation and creation

- echo 0x80000003 ><securityfs>/evm
+ ::
+
+ echo 0x80000003 ><securityfs>/evm

will enable HMAC and digital signature validation and
HMAC creation and disable all further modification of policy.

- echo 0x80000006 ><securityfs>/evm
+ ::
+
+ echo 0x80000006 ><securityfs>/evm

will enable digital signature validation, permit
modification of EVM-protected metadata and
@@ -65,7 +72,7 @@ Description:
Shows the set of extended attributes used to calculate or
validate the EVM signature, and allows additional attributes
to be added at runtime. Any signatures generated after
- additional attributes are added (and on files posessing those
+ additional attributes are added (and on files possessing those
additional attributes) will only be valid if the same
additional attributes are configured on system boot. Writing
a single period (.) will lock the xattr list from any further
diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy
index cd572912c593..e35263f97fc1 100644
--- a/Documentation/ABI/testing/ima_policy
+++ b/Documentation/ABI/testing/ima_policy
@@ -15,19 +15,22 @@ Description:
IMA appraisal, if configured, uses these file measurements
for local measurement appraisal.

- rule format: action [condition ...]
+ ::

- action: measure | dont_measure | appraise | dont_appraise |
- audit | hash | dont_hash
- condition:= base | lsm [option]
+ rule format: action [condition ...]
+
+ action: measure | dont_measure | appraise | dont_appraise |
+ audit | hash | dont_hash
+ condition:= base | lsm [option]
base: [[func=] [mask=] [fsmagic=] [fsuuid=] [uid=]
[euid=] [fowner=] [fsname=]]
lsm: [[subj_user=] [subj_role=] [subj_type=]
[obj_user=] [obj_role=] [obj_type=]]
option: [[appraise_type=]] [template=] [permit_directio]
[appraise_flag=] [keyrings=]
- base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]
- [FIRMWARE_CHECK]
+ base:
+ func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK]MODULE_CHECK]
+ [FIRMWARE_CHECK]
[KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]
[KEXEC_CMDLINE] [KEY_CHECK]
mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]
@@ -37,8 +40,9 @@ Description:
uid:= decimal value
euid:= decimal value
fowner:= decimal value
- lsm: are LSM specific
- option: appraise_type:= [imasig] [imasig|modsig]
+ lsm: are LSM specific
+ option:
+ appraise_type:= [imasig] [imasig|modsig]
appraise_flag:= [check_blacklist]
Currently, blacklist check is only for files signed with appended
signature.
@@ -49,7 +53,7 @@ Description:
(eg, ima-ng). Only valid when action is "measure".
pcr:= decimal value

- default policy:
+ default policy:
# PROC_SUPER_MAGIC
dont_measure fsmagic=0x9fa0
dont_appraise fsmagic=0x9fa0
@@ -97,7 +101,8 @@ Description:

Examples of LSM specific definitions:

- SELinux:
+ SELinux::
+
dont_measure obj_type=var_log_t
dont_appraise obj_type=var_log_t
dont_measure obj_type=auditd_log_t
@@ -105,10 +110,11 @@ Description:
measure subj_user=system_u func=FILE_CHECK mask=MAY_READ
measure subj_role=system_r func=FILE_CHECK mask=MAY_READ

- Smack:
+ Smack::
+
measure subj_user=_ func=FILE_CHECK mask=MAY_READ

- Example of measure rules using alternate PCRs:
+ Example of measure rules using alternate PCRs::

measure func=KEXEC_KERNEL_CHECK pcr=4
measure func=KEXEC_INITRAMFS_CHECK pcr=5
diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats
index 70dcaf2481f4..df5a3a8c1edf 100644
--- a/Documentation/ABI/testing/procfs-diskstats
+++ b/Documentation/ABI/testing/procfs-diskstats
@@ -6,28 +6,32 @@ Description:
of block devices. Each line contains the following 14
fields:

- 1 - major number
- 2 - minor mumber
- 3 - device name
- 4 - reads completed successfully
- 5 - reads merged
- 6 - sectors read
- 7 - time spent reading (ms)
- 8 - writes completed
- 9 - writes merged
- 10 - sectors written
- 11 - time spent writing (ms)
- 12 - I/Os currently in progress
- 13 - time spent doing I/Os (ms)
- 14 - weighted time spent doing I/Os (ms)
+ == ===================================
+ 1 major number
+ 2 minor mumber
+ 3 device name
+ 4 reads completed successfully
+ 5 reads merged
+ 6 sectors read
+ 7 time spent reading (ms)
+ 8 writes completed
+ 9 writes merged
+ 10 sectors written
+ 11 time spent writing (ms)
+ 12 I/Os currently in progress
+ 13 time spent doing I/Os (ms)
+ 14 weighted time spent doing I/Os (ms)
+ == ===================================

Kernel 4.18+ appends four more fields for discard
tracking putting the total at 18:

- 15 - discards completed successfully
- 16 - discards merged
- 17 - sectors discarded
- 18 - time spent discarding
+ == ===================================
+ 15 discards completed successfully
+ 16 discards merged
+ 17 sectors discarded
+ 18 time spent discarding
+ == ===================================

Kernel 5.5+ appends two more fields for flush requests:

diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index 2322eb748b38..e34cdeeeb9d4 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -4,23 +4,27 @@ Contact: Jerome Marchand <[email protected]>
Description:
The /sys/block/<disk>/stat files displays the I/O
statistics of disk <disk>. They contain 11 fields:
- 1 - reads completed successfully
- 2 - reads merged
- 3 - sectors read
- 4 - time spent reading (ms)
- 5 - writes completed
- 6 - writes merged
- 7 - sectors written
- 8 - time spent writing (ms)
- 9 - I/Os currently in progress
- 10 - time spent doing I/Os (ms)
- 11 - weighted time spent doing I/Os (ms)
- 12 - discards completed
- 13 - discards merged
- 14 - sectors discarded
- 15 - time spent discarding (ms)
- 16 - flush requests completed
- 17 - time spent flushing (ms)
+
+ == ==============================================
+ 1 reads completed successfully
+ 2 reads merged
+ 3 sectors read
+ 4 time spent reading (ms)
+ 5 writes completed
+ 6 writes merged
+ 7 sectors written
+ 8 time spent writing (ms)
+ 9 I/Os currently in progress
+ 10 time spent doing I/Os (ms)
+ 11 weighted time spent doing I/Os (ms)
+ 12 discards completed
+ 13 discards merged
+ 14 sectors discarded
+ 15 time spent discarding (ms)
+ 16 flush requests completed
+ 17 time spent flushing (ms)
+ == ==============================================
+
For more details refer Documentation/admin-guide/iostats.rst


diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 17f2bc7dd261..aa0fb500e3c9 100644
--- a/Documentation/ABI/testing/sysfs-block-device
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -8,11 +8,13 @@ Description:

It has the following valid values:

+ == ========================================================
0 OFF - the LED is not activated on activity
1 BLINK_ON - the LED blinks on every 10ms when activity is
detected.
2 BLINK_OFF - the LED is on when idle, and blinks off
every 10ms when activity is detected.
+ == ========================================================

Note that the user must turn sw_activity OFF it they wish to
control the activity LED via the em_message file.
diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi
index e7898cfe5fb1..c78603497b97 100644
--- a/Documentation/ABI/testing/sysfs-bus-acpi
+++ b/Documentation/ABI/testing/sysfs-bus-acpi
@@ -67,14 +67,16 @@ Description:
The return value is a decimal integer representing the device's
status bitmap:

- Bit [0] – Set if the device is present.
- Bit [1] – Set if the device is enabled and decoding its
- resources.
- Bit [2] – Set if the device should be shown in the UI.
- Bit [3] – Set if the device is functioning properly (cleared if
- device failed its diagnostics).
- Bit [4] – Set if the battery is present.
- Bits [31:5] – Reserved (must be cleared)
+ =========== ==================================================
+ Bit [0] Set if the device is present.
+ Bit [1] Set if the device is enabled and decoding its
+ resources.
+ Bit [2] Set if the device should be shown in the UI.
+ Bit [3] Set if the device is functioning properly (cleared
+ if device failed its diagnostics).
+ Bit [4] Set if the battery is present.
+ Bits [31:5] Reserved (must be cleared)
+ =========== ==================================================

If bit [0] is clear, then bit 1 must also be clear (a device
that is not present cannot be enabled).
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
index 5bb793ec926c..df7ccc1b2fba 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
@@ -10,7 +10,8 @@ Description:
name/value pairs.

Userspace must be prepared for the possibility that attributes
- define overlapping bit ranges. For example:
+ define overlapping bit ranges. For example::
+
attr1 = 'config:0-23'
attr2 = 'config:0-7'
attr3 = 'config:12-35'
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
index 0b0de8cd0d13..b6c69eb80ca4 100644
--- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
@@ -6,15 +6,18 @@ Description:
Value that exists only for mux devices that can be
written to control the behaviour of the multiplexer on
idle. Possible values:
- -2 - disconnect on idle, i.e. deselect the last used
- channel, which is useful when there is a device
- with an address that conflicts with another
- device on another mux on the same parent bus.
- -1 - leave the mux as-is, which is the most optimal
- setting in terms of I2C operations and is the
- default mode.
- 0..<nchans> - set the mux to a predetermined channel,
- which is useful if there is one channel that is
- used almost always, and you want to reduce the
- latency for normal operations after rare
- transactions on other channels
+
+ =========== ===============================================
+ -2 disconnect on idle, i.e. deselect the last used
+ channel, which is useful when there is a device
+ with an address that conflicts with another
+ device on another mux on the same parent bus.
+ -1 leave the mux as-is, which is the most optimal
+ setting in terms of I2C operations and is the
+ default mode.
+ 0..<nchans> set the mux to a predetermined channel,
+ which is useful if there is one channel that is
+ used almost always, and you want to reduce the
+ latency for normal operations after rare
+ transactions on other channels
+ =========== ===============================================
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index a9d51810a3ba..e3df71987eff 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -65,6 +65,7 @@ Contact: [email protected]
Description:
When the internal sampling clock can only take a specific set of
frequencies, we can specify the available values with:
+
- a small discrete set of values like "0 2 4 6 8"
- a range with minimum, step and maximum frequencies like
"[min step max]"
@@ -1627,17 +1628,21 @@ Description:
Mounting matrix for IIO sensors. This is a rotation matrix which
informs userspace about sensor chip's placement relative to the
main hardware it is mounted on.
+
Main hardware placement is defined according to the local
reference frame related to the physical quantity the sensor
measures.
+
Given that the rotation matrix is defined in a board specific
way (platform data and / or device-tree), the main hardware
reference frame definition is left to the implementor's choice
(see below for a magnetometer example).
+
Applications should apply this rotation matrix to samples so
that when main hardware reference frame is aligned onto local
reference frame, then sensor chip reference frame is also
perfectly aligned with it.
+
Matrix is a 3x3 unitary matrix and typically looks like
[0, 1, 0; 1, 0, 0; 0, 0, -1]. Identity matrix
[1, 0, 0; 0, 1, 0; 0, 0, 1] means sensor chip and main hardware
@@ -1646,8 +1651,10 @@ Description:
For example, a mounting matrix for a magnetometer sensor informs
userspace about sensor chip's ORIENTATION relative to the main
hardware.
+
More specifically, main hardware orientation is defined with
respect to the LOCAL EARTH GEOMAGNETIC REFERENCE FRAME where :
+
* Y is in the ground plane and positive towards magnetic North ;
* X is in the ground plane, perpendicular to the North axis and
positive towards the East ;
@@ -1656,13 +1663,16 @@ Description:
An implementor might consider that for a hand-held device, a
'natural' orientation would be 'front facing camera at the top'.
The main hardware reference frame could then be described as :
+
* Y is in the plane of the screen and is positive towards the
top of the screen ;
* X is in the plane of the screen, perpendicular to Y axis, and
positive towards the right hand side of the screen ;
* Z is perpendicular to the screen plane and positive out of the
screen.
+
Another example for a quadrotor UAV might be :
+
* Y is in the plane of the propellers and positive towards the
front-view camera;
* X is in the plane of the propellers, perpendicular to Y axis,
@@ -1704,6 +1714,7 @@ Description:
This interface is deprecated; please use the Counter subsystem.

A list of possible counting directions which are:
+
- "up" : counter device is increasing.
- "down": counter device is decreasing.

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
index 2071f9bcfaa5..1c2a07f7a75e 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
@@ -5,7 +5,8 @@ Contact: Peter Rosin <[email protected]>
Description:
The DAC is used to find the peak level of an alternating
voltage input signal by a binary search using the output
- of a comparator wired to an interrupt pin. Like so:
+ of a comparator wired to an interrupt pin. Like so::
+
_
| \
input +------>-------|+ \
@@ -19,10 +20,12 @@ Description:
| irq|------<-------'
| |
'-------'
+
The boolean invert attribute (0/1) should be set when the
input signal is centered around the maximum value of the
dac instead of zero. The envelope detector will search
from below in this case and will also invert the result.
+
The edge/level of the interrupt is also switched to its
opposite value.

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
index 6158f831c761..adf24c40126f 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
+++ b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
@@ -4,7 +4,7 @@ KernelVersion: 4.7
Contact: [email protected]
Description:
Writing '1' will perform a FOC (Fast Online Calibration). The
- corresponding calibration offsets can be read from *_calibbias
+ corresponding calibration offsets can be read from `*_calibbias`
entries.

What: /sys/bus/iio/devices/iio:deviceX/location
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
index 0e66ae9b0071..91439d6d60b5 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
@@ -3,14 +3,20 @@ KernelVersion: 4.14
Contact: [email protected]
Description:
For audio purpose only.
+
Used by audio driver to set/get the spi input frequency.
+
This is mandatory if DFSDM is slave on SPI bus, to
provide information on the SPI clock frequency during runtime
Notice that the SPI frequency should be a multiple of sample
frequency to ensure the precision.
- if DFSDM input is SPI master
+
+ if DFSDM input is SPI master:
+
Reading SPI clkout frequency,
error on writing
+
If DFSDM input is SPI Slave:
+
Reading returns value previously set.
Writing value before starting conversions.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32
index ad2cc63e4bf8..73498ff666bd 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32
@@ -17,9 +17,11 @@ KernelVersion: 4.13
Contact: [email protected]
Description:
Configure the device counter quadrature modes:
+
- non-quadrature:
Encoder IN1 input servers as the count input (up
direction).
+
- quadrature:
Encoder IN1 and IN2 inputs are mixed to get direction
and count.
@@ -35,23 +37,26 @@ KernelVersion: 4.13
Contact: [email protected]
Description:
Configure the device encoder/counter active edge:
+
- rising-edge
- falling-edge
- both-edges

In non-quadrature mode, device counts up on active edge.
+
In quadrature mode, encoder counting scenarios are as follows:
- ----------------------------------------------------------------
+
+ +---------+----------+--------------------+--------------------+
| Active | Level on | IN1 signal | IN2 signal |
- | edge | opposite |------------------------------------------
+ | edge | opposite +----------+---------+----------+---------+
| | signal | Rising | Falling | Rising | Falling |
- ----------------------------------------------------------------
- | Rising | High -> | Down | - | Up | - |
- | edge | Low -> | Up | - | Down | - |
- ----------------------------------------------------------------
- | Falling | High -> | - | Up | - | Down |
- | edge | Low -> | - | Down | - | Up |
- ----------------------------------------------------------------
- | Both | High -> | Down | Up | Up | Down |
- | edges | Low -> | Up | Down | Down | Up |
- ----------------------------------------------------------------
+ +---------+----------+----------+---------+----------+---------+
+ | Rising | High -> | Down | - | Up | - |
+ | edge | Low -> | Up | - | Down | - |
+ +---------+----------+----------+---------+----------+---------+
+ | Falling | High -> | - | Up | - | Down |
+ | edge | Low -> | - | Down | - | Up |
+ +---------+----------+----------+---------+----------+---------+
+ | Both | High -> | Down | Up | Up | Down |
+ | edges | Low -> | Up | Down | Down | Up |
+ +---------+----------+----------+---------+----------+---------+
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
index 6275e9f56e6c..13f099ef6a95 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
+++ b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
@@ -5,11 +5,16 @@ Contact: [email protected]
Description:
Current configuration and available configurations
for the bias current.
- normal - Normal measurement configurations (default)
- positivebias - Positive bias configuration
- negativebias - Negative bias configuration
- disabled - Only available on HMC5983. Disables magnetic
+
+ ============ ============================================
+ normal Normal measurement configurations (default)
+ positivebias Positive bias configuration
+ negativebias Negative bias configuration
+ disabled Only available on HMC5983. Disables magnetic
sensor and enables temperature sensor.
- Note: The effect of this configuration may vary
- according to the device. For exact documentation
- check the device's datasheet.
+ ============ ============================================
+
+ Note:
+ The effect of this configuration may vary
+ according to the device. For exact documentation
+ check the device's datasheet.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
index 3b3509a3ef2f..e5ef6d8e5da1 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
+++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
@@ -5,9 +5,12 @@ Description:
Open-circuit fault. The detection of open-circuit faults,
such as those caused by broken thermocouple wires.
Reading returns either '1' or '0'.
- '1' = An open circuit such as broken thermocouple wires
- has been detected.
- '0' = No open circuit or broken thermocouple wires are detected
+
+ === =======================================================
+ '1' An open circuit such as broken thermocouple wires
+ has been detected.
+ '0' No open circuit or broken thermocouple wires are detected
+ === =======================================================

What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv
KernelVersion: 5.1
@@ -18,7 +21,11 @@ Description:
cables by integrated MOSFETs at the T+ and T- inputs, and the
BIAS output. These MOSFETs turn off when the input voltage is
negative or greater than VDD.
+
Reading returns either '1' or '0'.
- '1' = The input voltage is negative or greater than VDD.
- '0' = The input voltage is positive and less than VDD (normal
- state).
+
+ === =======================================================
+ '1' The input voltage is negative or greater than VDD.
+ '0' The input voltage is positive and less than VDD (normal
+ state).
+ === =======================================================
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
index b7259234ad70..a10a4de3e5fe 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
@@ -3,67 +3,85 @@ KernelVersion: 4.11
Contact: [email protected]
Description:
Reading returns the list possible master modes which are:
- - "reset" : The UG bit from the TIMx_EGR register is
+
+
+ - "reset"
+ The UG bit from the TIMx_EGR register is
used as trigger output (TRGO).
- - "enable" : The Counter Enable signal CNT_EN is used
+ - "enable"
+ The Counter Enable signal CNT_EN is used
as trigger output.
- - "update" : The update event is selected as trigger output.
+ - "update"
+ The update event is selected as trigger output.
For instance a master timer can then be used
as a prescaler for a slave timer.
- - "compare_pulse" : The trigger output send a positive pulse
- when the CC1IF flag is to be set.
- - "OC1REF" : OC1REF signal is used as trigger output.
- - "OC2REF" : OC2REF signal is used as trigger output.
- - "OC3REF" : OC3REF signal is used as trigger output.
- - "OC4REF" : OC4REF signal is used as trigger output.
+ - "compare_pulse"
+ The trigger output send a positive pulse
+ when the CC1IF flag is to be set.
+ - "OC1REF"
+ OC1REF signal is used as trigger output.
+ - "OC2REF"
+ OC2REF signal is used as trigger output.
+ - "OC3REF"
+ OC3REF signal is used as trigger output.
+ - "OC4REF"
+ OC4REF signal is used as trigger output.
+
Additional modes (on TRGO2 only):
- - "OC5REF" : OC5REF signal is used as trigger output.
- - "OC6REF" : OC6REF signal is used as trigger output.
+
+ - "OC5REF"
+ OC5REF signal is used as trigger output.
+ - "OC6REF"
+ OC6REF signal is used as trigger output.
- "compare_pulse_OC4REF":
- OC4REF rising or falling edges generate pulses.
+ OC4REF rising or falling edges generate pulses.
- "compare_pulse_OC6REF":
- OC6REF rising or falling edges generate pulses.
+ OC6REF rising or falling edges generate pulses.
- "compare_pulse_OC4REF_r_or_OC6REF_r":
- OC4REF or OC6REF rising edges generate pulses.
+ OC4REF or OC6REF rising edges generate pulses.
- "compare_pulse_OC4REF_r_or_OC6REF_f":
- OC4REF rising or OC6REF falling edges generate pulses.
+ OC4REF rising or OC6REF falling edges generate
+ pulses.
- "compare_pulse_OC5REF_r_or_OC6REF_r":
- OC5REF or OC6REF rising edges generate pulses.
+ OC5REF or OC6REF rising edges generate pulses.
- "compare_pulse_OC5REF_r_or_OC6REF_f":
- OC5REF rising or OC6REF falling edges generate pulses.
+ OC5REF rising or OC6REF falling edges generate
+ pulses.

- +-----------+ +-------------+ +---------+
- | Prescaler +-> | Counter | +-> | Master | TRGO(2)
- +-----------+ +--+--------+-+ |-> | Control +-->
- | | || +---------+
- +--v--------+-+ OCxREF || +---------+
- | Chx compare +----------> | Output | ChX
- +-----------+-+ | | Control +-->
- . | | +---------+
- . | | .
- +-----------v-+ OC6REF | .
- | Ch6 compare +---------+>
- +-------------+
+ ::

- Example with: "compare_pulse_OC4REF_r_or_OC6REF_r":
+ +-----------+ +-------------+ +---------+
+ | Prescaler +-> | Counter | +-> | Master | TRGO(2)
+ +-----------+ +--+--------+-+ |-> | Control +-->
+ | | || +---------+
+ +--v--------+-+ OCxREF || +---------+
+ | Chx compare +----------> | Output | ChX
+ +-----------+-+ | | Control +-->
+ . | | +---------+
+ . | | .
+ +-----------v-+ OC6REF | .
+ | Ch6 compare +---------+>
+ +-------------+

- X
- X X
- X . . X
- X . . X
- X . . X
- count X . . . . X
- . . . .
- . . . .
- +---------------+
- OC4REF | . . |
- +-+ . . +-+
- . +---+ .
- OC6REF . | | .
- +-------+ +-------+
- +-+ +-+
- TRGO2 | | | |
- +-+ +---+ +---------+
+ Example with: "compare_pulse_OC4REF_r_or_OC6REF_r"::
+
+ X
+ X X
+ X . . X
+ X . . X
+ X . . X
+ count X . . . . X
+ . . . .
+ . . . .
+ +---------------+
+ OC4REF | . . |
+ +-+ . . +-+
+ . +---+ .
+ OC6REF . | | .
+ +-------+ +-------+
+ +-+ +-+
+ TRGO2 | | | |
+ +-+ +---+ +---------+

What: /sys/bus/iio/devices/triggerX/master_mode
KernelVersion: 4.11
@@ -91,6 +109,30 @@ Description:
When counting down the counter start from preset value
and fire event when reach 0.

+What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
+KernelVersion: 4.12
+Contact: [email protected]
+Description:
+ Reading returns the list possible quadrature modes.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
+KernelVersion: 4.12
+Contact: [email protected]
+Description:
+ Configure the device counter quadrature modes:
+
+ channel_A:
+ Encoder A input servers as the count input and B as
+ the UP/DOWN direction control input.
+
+ channel_B:
+ Encoder B input serves as the count input and A as
+ the UP/DOWN direction control input.
+
+ quadrature:
+ Encoder A and B inputs are mixed to get direction
+ and count with a scale of 0.25.
+
What: /sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available
KernelVersion: 4.12
Contact: [email protected]
@@ -104,6 +146,7 @@ Description:
Configure the device counter enable modes, in all case
counting direction is set by in_count0_count_direction
attribute and the counter is clocked by the internal clock.
+
always:
Counter is always ON.

diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
index 7fd2601c2831..a74252e580a5 100644
--- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
@@ -9,11 +9,13 @@ Date: June 2015
KernelVersion: 4.3
Contact: Alexander Shishkin <[email protected]>
Description: (RW) Configure MSC operating mode:
+
- "single", for contiguous buffer mode (high-order alloc);
- "multi", for multiblock mode;
- "ExI", for DCI handler mode;
- "debug", for debug mode;
- any of the currently loaded buffer sinks.
+
If operating mode changes, existing buffer is deallocated,
provided there are no active users and tracing is not enabled,
otherwise the write will fail.
@@ -23,10 +25,12 @@ Date: June 2015
KernelVersion: 4.3
Contact: Alexander Shishkin <[email protected]>
Description: (RW) Configure MSC buffer size for "single" or "multi" modes.
+
In single mode, this is a single number of pages, has to be
power of 2. In multiblock mode, this is a comma-separated list
of numbers of pages for each window to be allocated. Number of
windows is not limited.
+
Writing to this file deallocates existing buffer (provided
there are no active users and tracing is not enabled) and then
allocates a new one.
diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit
index e4f76e7eab93..63ef0b9ecce7 100644
--- a/Documentation/ABI/testing/sysfs-bus-nfit
+++ b/Documentation/ABI/testing/sysfs-bus-nfit
@@ -1,4 +1,4 @@
-For all of the nmem device attributes under nfit/*, see the 'NVDIMM Firmware
+For all of the nmem device attributes under ``nfit/*``, see the 'NVDIMM Firmware
Interface Table (NFIT)' section in the ACPI specification
(http://www.uefi.org/specifications) for more details.

diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
index 3c9a8c4a25eb..860db53037a5 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
@@ -1,6 +1,6 @@
-==========================
PCIe Device AER statistics
-==========================
+--------------------------
+
These attributes show up under all the devices that are AER capable. These
statistical counters indicate the errors "as seen/reported by the device".
Note that this may mean that if an endpoint is causing problems, the AER
@@ -17,19 +17,18 @@ Description: List of correctable errors seen and reported by this
PCI device using ERR_COR. Note that since multiple errors may
be reported using a single ERR_COR message, thus
TOTAL_ERR_COR at the end of the file may not match the actual
- total of all the errors in the file. Sample output:
--------------------------------------------------------------------------
-localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable
-Receiver Error 2
-Bad TLP 0
-Bad DLLP 0
-RELAY_NUM Rollover 0
-Replay Timer Timeout 0
-Advisory Non-Fatal 0
-Corrected Internal Error 0
-Header Log Overflow 0
-TOTAL_ERR_COR 2
--------------------------------------------------------------------------
+ total of all the errors in the file. Sample output::
+
+ localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable
+ Receiver Error 2
+ Bad TLP 0
+ Bad DLLP 0
+ RELAY_NUM Rollover 0
+ Replay Timer Timeout 0
+ Advisory Non-Fatal 0
+ Corrected Internal Error 0
+ Header Log Overflow 0
+ TOTAL_ERR_COR 2

What: /sys/bus/pci/devices/<dev>/aer_dev_fatal
Date: July 2018
@@ -39,28 +38,27 @@ Description: List of uncorrectable fatal errors seen and reported by this
PCI device using ERR_FATAL. Note that since multiple errors may
be reported using a single ERR_FATAL message, thus
TOTAL_ERR_FATAL at the end of the file may not match the actual
- total of all the errors in the file. Sample output:
--------------------------------------------------------------------------
-localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal
-Undefined 0
-Data Link Protocol 0
-Surprise Down Error 0
-Poisoned TLP 0
-Flow Control Protocol 0
-Completion Timeout 0
-Completer Abort 0
-Unexpected Completion 0
-Receiver Overflow 0
-Malformed TLP 0
-ECRC 0
-Unsupported Request 0
-ACS Violation 0
-Uncorrectable Internal Error 0
-MC Blocked TLP 0
-AtomicOp Egress Blocked 0
-TLP Prefix Blocked Error 0
-TOTAL_ERR_FATAL 0
--------------------------------------------------------------------------
+ total of all the errors in the file. Sample output::
+
+ localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal
+ Undefined 0
+ Data Link Protocol 0
+ Surprise Down Error 0
+ Poisoned TLP 0
+ Flow Control Protocol 0
+ Completion Timeout 0
+ Completer Abort 0
+ Unexpected Completion 0
+ Receiver Overflow 0
+ Malformed TLP 0
+ ECRC 0
+ Unsupported Request 0
+ ACS Violation 0
+ Uncorrectable Internal Error 0
+ MC Blocked TLP 0
+ AtomicOp Egress Blocked 0
+ TLP Prefix Blocked Error 0
+ TOTAL_ERR_FATAL 0

What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal
Date: July 2018
@@ -70,32 +68,31 @@ Description: List of uncorrectable nonfatal errors seen and reported by this
PCI device using ERR_NONFATAL. Note that since multiple errors
may be reported using a single ERR_FATAL message, thus
TOTAL_ERR_NONFATAL at the end of the file may not match the
- actual total of all the errors in the file. Sample output:
--------------------------------------------------------------------------
-localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal
-Undefined 0
-Data Link Protocol 0
-Surprise Down Error 0
-Poisoned TLP 0
-Flow Control Protocol 0
-Completion Timeout 0
-Completer Abort 0
-Unexpected Completion 0
-Receiver Overflow 0
-Malformed TLP 0
-ECRC 0
-Unsupported Request 0
-ACS Violation 0
-Uncorrectable Internal Error 0
-MC Blocked TLP 0
-AtomicOp Egress Blocked 0
-TLP Prefix Blocked Error 0
-TOTAL_ERR_NONFATAL 0
--------------------------------------------------------------------------
+ actual total of all the errors in the file. Sample output::
+
+ localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal
+ Undefined 0
+ Data Link Protocol 0
+ Surprise Down Error 0
+ Poisoned TLP 0
+ Flow Control Protocol 0
+ Completion Timeout 0
+ Completer Abort 0
+ Unexpected Completion 0
+ Receiver Overflow 0
+ Malformed TLP 0
+ ECRC 0
+ Unsupported Request 0
+ ACS Violation 0
+ Uncorrectable Internal Error 0
+ MC Blocked TLP 0
+ AtomicOp Egress Blocked 0
+ TLP Prefix Blocked Error 0
+ TOTAL_ERR_NONFATAL 0

-============================
PCIe Rootport AER statistics
-============================
+----------------------------
+
These attributes show up under only the rootports (or root complex event
collectors) that are AER capable. These indicate the number of error messages as
"reported to" the rootport. Please note that the rootports also transmit
diff --git a/Documentation/ABI/testing/sysfs-bus-rapidio b/Documentation/ABI/testing/sysfs-bus-rapidio
index 13208b27dd87..634ea207a50a 100644
--- a/Documentation/ABI/testing/sysfs-bus-rapidio
+++ b/Documentation/ABI/testing/sysfs-bus-rapidio
@@ -4,24 +4,27 @@ Description:
an individual subdirectory with the following name format of
device_name "nn:d:iiii", where:

- nn - two-digit hexadecimal ID of RapidIO network where the
+ ==== ========================================================
+ nn two-digit hexadecimal ID of RapidIO network where the
device resides
- d - device type: 'e' - for endpoint or 's' - for switch
- iiii - four-digit device destID for endpoints, or switchID for
+ d device type: 'e' - for endpoint or 's' - for switch
+ iiii four-digit device destID for endpoints, or switchID for
switches
+ ==== ========================================================

For example, below is a list of device directories that
represents a typical RapidIO network with one switch, one host,
and two agent endpoints, as it is seen by the enumerating host
- (with destID = 1):
+ (with destID = 1)::

- /sys/bus/rapidio/devices/00:e:0000
- /sys/bus/rapidio/devices/00:e:0002
- /sys/bus/rapidio/devices/00:s:0001
+ /sys/bus/rapidio/devices/00:e:0000
+ /sys/bus/rapidio/devices/00:e:0002
+ /sys/bus/rapidio/devices/00:s:0001

- NOTE: An enumerating or discovering endpoint does not create a
- sysfs entry for itself, this is why an endpoint with destID=1 is
- not shown in the list.
+ NOTE:
+ An enumerating or discovering endpoint does not create a
+ sysfs entry for itself, this is why an endpoint with destID=1
+ is not shown in the list.

Attributes Common for All RapidIO Devices
-----------------------------------------
diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt
index dd565c378b40..171127294674 100644
--- a/Documentation/ABI/testing/sysfs-bus-thunderbolt
+++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt
@@ -37,16 +37,18 @@ Contact: [email protected]
Description: This attribute holds current Thunderbolt security level
set by the system BIOS. Possible values are:

- none: All devices are automatically authorized
- user: Devices are only authorized based on writing
- appropriate value to the authorized attribute
- secure: Require devices that support secure connect at
- minimum. User needs to authorize each device.
- dponly: Automatically tunnel Display port (and USB). No
- PCIe tunnels are created.
- usbonly: Automatically tunnel USB controller of the
+ ======= ==================================================
+ none All devices are automatically authorized
+ user Devices are only authorized based on writing
+ appropriate value to the authorized attribute
+ secure Require devices that support secure connect at
+ minimum. User needs to authorize each device.
+ dponly Automatically tunnel Display port (and USB). No
+ PCIe tunnels are created.
+ usbonly Automatically tunnel USB controller of the
connected Thunderbolt dock (and Display Port). All
PCIe links downstream of the dock are removed.
+ ======= ==================================================

What: /sys/bus/thunderbolt/devices/.../authorized
Date: Sep 2017
@@ -61,17 +63,23 @@ Description: This attribute is used to authorize Thunderbolt devices
yet authorized.

Possible values are supported:
- 1: The device will be authorized and connected
+
+ == ===========================================
+ 1 The device will be authorized and connected
+ == ===========================================

When key attribute contains 32 byte hex string the possible
values are:
- 1: The 32 byte hex string is added to the device NVM and
- the device is authorized.
- 2: Send a challenge based on the 32 byte hex string. If the
- challenge response from device is valid, the device is
- authorized. In case of failure errno will be ENOKEY if
- the device did not contain a key at all, and
- EKEYREJECTED if the challenge response did not match.
+
+ == ========================================================
+ 1 The 32 byte hex string is added to the device NVM and
+ the device is authorized.
+ 2 Send a challenge based on the 32 byte hex string. If the
+ challenge response from device is valid, the device is
+ authorized. In case of failure errno will be ENOKEY if
+ the device did not contain a key at all, and
+ EKEYREJECTED if the challenge response did not match.
+ == ========================================================

What: /sys/bus/thunderbolt/devices/.../boot
Date: Jun 2018
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index 614d216dff1d..e449b8374f6a 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -72,24 +72,27 @@ Description:
table at compile time. The format for the device ID is:
idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct
The vendor ID and device ID fields are required, the
- rest is optional. The Ref* tuple can be used to tell the
+ rest is optional. The `Ref*` tuple can be used to tell the
driver to use the same driver_data for the new device as
it is used for the reference device.
Upon successfully adding an ID, the driver will probe
- for the device and attempt to bind to it. For example:
- # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
+ for the device and attempt to bind to it. For example::
+
+ # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id

Here add a new device (0458:7045) using driver_data from
- an already supported device (0458:704c):
- # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
+ an already supported device (0458:704c)::
+
+ # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id

Reading from this file will list all dynamically added
device IDs in the same format, with one entry per
- line. For example:
- # cat /sys/bus/usb/drivers/foo/new_id
- 8086 10f5
- dead beef 06
- f00d cafe
+ line. For example::
+
+ # cat /sys/bus/usb/drivers/foo/new_id
+ 8086 10f5
+ dead beef 06
+ f00d cafe

The list will be truncated at PAGE_SIZE bytes due to
sysfs restrictions.
@@ -209,6 +212,7 @@ Description:
advance, and behaves well according to the specification.
This attribute is a bit-field that controls the behavior of
a specific port:
+
- Bit 0 of this field selects the "old" enumeration scheme,
as it is considerably faster (it only causes one USB reset
instead of 2).
@@ -233,10 +237,10 @@ Description:
poll() for monitoring changes to this value in user space.

Any time this value changes the corresponding hub device will send a
- udev event with the following attributes:
+ udev event with the following attributes::

- OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX
- OVER_CURRENT_COUNT=[current value of this sysfs attribute]
+ OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX
+ OVER_CURRENT_COUNT=[current value of this sysfs attribute]

What: /sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit
Date: November 2015
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
index 9ade80f81f96..2f86e4223bfc 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
+++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
@@ -12,8 +12,11 @@ KernelVersion: 2.6.26
Contact: Harrison Metzger <[email protected]>
Description: Controls the devices display mode.
For a 6 character display the values are
+
MSB 0x06; LSB 0x3F, and
+
for an 8 character display the values are
+
MSB 0x08; LSB 0xFF.

What: /sys/bus/usb/.../textmode
@@ -37,7 +40,7 @@ KernelVersion: 2.6.26
Contact: Harrison Metzger <[email protected]>
Description: Controls the decimal places on the device.
To set the nth decimal place, give this field
- the value of 10 ** n. Assume this field has
+ the value of ``10 ** n``. Assume this field has
the value k and has 1 or more decimal places set,
to set the mth place (where m is not already set),
- change this fields value to k + 10 ** m.
+ change this fields value to ``k + 10 ** m``.
diff --git a/Documentation/ABI/testing/sysfs-bus-vfio-mdev b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
index 452dbe39270e..59fc804265db 100644
--- a/Documentation/ABI/testing/sysfs-bus-vfio-mdev
+++ b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
@@ -28,8 +28,9 @@ Description:
Writing UUID to this file will create mediated device of
type <type-id> for parent device <device>. This is a
write-only file.
- For example:
- # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \
+ For example::
+
+ # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \
/sys/devices/foo/mdev_supported_types/foo-1/create

What: /sys/.../mdev_supported_types/<type-id>/devices/
@@ -107,5 +108,6 @@ Description:
Writing '1' to this file destroys the mediated device. The
vendor driver can fail the remove() callback if that device
is active and the vendor driver doesn't support hot unplug.
- Example:
- # echo 1 > /sys/bus/mdev/devices/<UUID>/remove
+ Example::
+
+ # echo 1 > /sys/bus/mdev/devices/<UUID>/remove
diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
index 7970e3713e70..a6f51a104c44 100644
--- a/Documentation/ABI/testing/sysfs-class-cxl
+++ b/Documentation/ABI/testing/sysfs-class-cxl
@@ -72,11 +72,16 @@ Description: read/write
when performing the START_WORK ioctl. Only applicable when
running under hashed page table mmu.
Possible values:
- none: No prefaulting (default)
- work_element_descriptor: Treat the work element
- descriptor as an effective address and
- prefault what it points to.
- all: all segments process calling START_WORK maps.
+
+ ======================= ======================================
+ none No prefaulting (default)
+ work_element_descriptor Treat the work element
+ descriptor as an effective address and
+ prefault what it points to.
+ all all segments process calling
+ START_WORK maps.
+ ======================= ======================================
+
Users: https://github.com/ibm-capi/libcxl

What: /sys/class/cxl/<afu>/reset
diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index 5f67f7ab277b..65e040978f73 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -50,7 +50,7 @@ Description:
You can change triggers in a similar manner to the way an IO
scheduler is chosen. Trigger specific parameters can appear in
/sys/class/leds/<led> once a given trigger is selected. For
- their documentation see sysfs-class-led-trigger-*.
+ their documentation see `sysfs-class-led-trigger-*`.

What: /sys/class/leds/<led>/inverted
Date: January 2011
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
index f520ece9b64c..69befe947d7e 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
@@ -6,127 +6,132 @@ Description:
The LEDs board supports only predefined patterns by firmware
for specific LEDs.

- Breathing mode for Screen frame light tube:
- "0 4000 1 4000"
+ Breathing mode for Screen frame light tube::

- ^
- |
- Max-| ---
- | / \
- | / \
- | / \ /
- | / \ /
- Min-|- ---
- |
- 0------4------8--> time (sec)
+ "0 4000 1 4000"

- Cascade mode for Pipe LED:
- "1 800 2 800 4 800 8 800 16 800"
+ ^
+ |
+ Max-| ---
+ | / \
+ | / \
+ | / \ /
+ | / \ /
+ Min-|- ---
+ |
+ 0------4------8--> time (sec)

- ^
- |
- 0 On -|----+ +----+ +---
- | | | | |
- Off-| +-------------------+ +-------------------+
- |
- 1 On -| +----+ +----+
- | | | | |
- Off |----+ +-------------------+ +------------------
- |
- 2 On -| +----+ +----+
- | | | | |
- Off-|---------+ +-------------------+ +-------------
- |
- 3 On -| +----+ +----+
- | | | | |
- Off-|--------------+ +-------------------+ +--------
- |
- 4 On -| +----+ +----+
- | | | | |
- Off-|-------------------+ +-------------------+ +---
- |
- 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+ Cascade mode for Pipe LED::

- Inverted cascade mode for Pipe LED:
- "30 800 29 800 27 800 23 800 15 800"
+ "1 800 2 800 4 800 8 800 16 800"

- ^
- |
- 0 On -| +-------------------+ +-------------------+
- | | | | |
- Off-|----+ +----+ +---
- |
- 1 On -|----+ +-------------------+ +------------------
- | | | | |
- Off | +----+ +----+
- |
- 2 On -|---------+ +-------------------+ +-------------
- | | | | |
- Off-| +----+ +----+
- |
- 3 On -|--------------+ +-------------------+ +--------
- | | | | |
- Off-| +----+ +----+
- |
- 4 On -|-------------------+ +-------------------+ +---
- | | | | |
- Off-| +----+ +----+
- |
- 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+ ^
+ |
+ 0 On -|----+ +----+ +---
+ | | | | |
+ Off-| +-------------------+ +-------------------+
+ |
+ 1 On -| +----+ +----+
+ | | | | |
+ Off |----+ +-------------------+ +------------------
+ |
+ 2 On -| +----+ +----+
+ | | | | |
+ Off-|---------+ +-------------------+ +-------------
+ |
+ 3 On -| +----+ +----+
+ | | | | |
+ Off-|--------------+ +-------------------+ +--------
+ |
+ 4 On -| +----+ +----+
+ | | | | |
+ Off-|-------------------+ +-------------------+ +---
+ |
+ 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)

- Bounce mode for Pipe LED:
- "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
+ Inverted cascade mode for Pipe LED::

- ^
- |
- 0 On -|----+ +--------
- | | |
- Off-| +---------------------------------------+
- |
- 1 On -| +----+ +----+
- | | | | |
- Off |----+ +-----------------------------+ +--------
- |
- 2 On -| +----+ +----+
- | | | | |
- Off-|---------+ +-------------------+ +-------------
- |
- 3 On -| +----+ +----+
- | | | | |
- Off-|--------------+ +---------+ +------------------
- |
- 4 On -| +---------+
- | | |
- Off-|-------------------+ +-----------------------
- |
- 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+ "30 800 29 800 27 800 23 800 15 800"

- Inverted bounce mode for Pipe LED:
- "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
+ ^
+ |
+ 0 On -| +-------------------+ +-------------------+
+ | | | | |
+ Off-|----+ +----+ +---
+ |
+ 1 On -|----+ +-------------------+ +------------------
+ | | | | |
+ Off | +----+ +----+
+ |
+ 2 On -|---------+ +-------------------+ +-------------
+ | | | | |
+ Off-| +----+ +----+
+ |
+ 3 On -|--------------+ +-------------------+ +--------
+ | | | | |
+ Off-| +----+ +----+
+ |
+ 4 On -|-------------------+ +-------------------+ +---
+ | | | | |
+ Off-| +----+ +----+
+ |
+ 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)

- ^
- |
- 0 On -| +---------------------------------------+
- | | |
- Off-|----+ +--------
- |
- 1 On -|----+ +-----------------------------+ +--------
- | | | | |
- Off | +----+ +----+
- |
- 2 On -|---------+ +-------------------+ +-------------
- | | | | |
- Off-| +----+ +----+
- |
- 3 On -|--------------+ +---------+ +------------------
- | | | | |
- Off-| +----+ +----+
- |
- 4 On -|-------------------+ +-----------------------
- | | |
- Off-| +---------+
- |
- 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+ Bounce mode for Pipe LED::
+
+ "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
+
+ ^
+ |
+ 0 On -|----+ +--------
+ | | |
+ Off-| +---------------------------------------+
+ |
+ 1 On -| +----+ +----+
+ | | | | |
+ Off |----+ +-----------------------------+ +--------
+ |
+ 2 On -| +----+ +----+
+ | | | | |
+ Off-|---------+ +-------------------+ +-------------
+ |
+ 3 On -| +----+ +----+
+ | | | | |
+ Off-|--------------+ +---------+ +------------------
+ |
+ 4 On -| +---------+
+ | | |
+ Off-|-------------------+ +-----------------------
+ |
+ 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+
+ Inverted bounce mode for Pipe LED::
+
+ "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
+
+ ^
+ |
+ 0 On -| +---------------------------------------+
+ | | |
+ Off-|----+ +--------
+ |
+ 1 On -|----+ +-----------------------------+ +--------
+ | | | | |
+ Off | +----+ +----+
+ |
+ 2 On -|---------+ +-------------------+ +-------------
+ | | | | |
+ Off-| +----+ +----+
+ |
+ 3 On -|--------------+ +---------+ +------------------
+ | | | | |
+ Off-| +----+ +----+
+ |
+ 4 On -|-------------------+ +-----------------------
+ | | |
+ Off-| +---------+
+ |
+ 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)

What: /sys/class/leds/<led>/repeat
Date: September 2019
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
index 45b1e605d355..215482379580 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
@@ -12,8 +12,8 @@ Description:
format, we should set brightness as 0 for rise stage, fall
stage and low stage.

- Min stage duration: 125 ms
- Max stage duration: 31875 ms
+ - Min stage duration: 125 ms
+ - Max stage duration: 31875 ms

Since the stage duration step is 125 ms, the duration should be
a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms.
diff --git a/Documentation/ABI/testing/sysfs-class-mic b/Documentation/ABI/testing/sysfs-class-mic
index 6ef682603179..bd0e780c3760 100644
--- a/Documentation/ABI/testing/sysfs-class-mic
+++ b/Documentation/ABI/testing/sysfs-class-mic
@@ -41,24 +41,33 @@ Description:
When read, this entry provides the current state of an Intel
MIC device in the context of the card OS. Possible values that
will be read are:
- "ready" - The MIC device is ready to boot the card OS. On
- reading this entry after an OSPM resume, a "boot" has to be
- written to this entry if the card was previously shutdown
- during OSPM suspend.
- "booting" - The MIC device has initiated booting a card OS.
- "online" - The MIC device has completed boot and is online
- "shutting_down" - The card OS is shutting down.
- "resetting" - A reset has been initiated for the MIC device
- "reset_failed" - The MIC device has failed to reset.
+
+
+ =============== ===============================================
+ "ready" The MIC device is ready to boot the card OS.
+ On reading this entry after an OSPM resume,
+ a "boot" has to be written to this entry if
+ the card was previously shutdown during OSPM
+ suspend.
+ "booting" The MIC device has initiated booting a card OS.
+ "online" The MIC device has completed boot and is online
+ "shutting_down" The card OS is shutting down.
+ "resetting" A reset has been initiated for the MIC device
+ "reset_failed" The MIC device has failed to reset.
+ =============== ===============================================

When written, this sysfs entry triggers different state change
operations depending upon the current state of the card OS.
Acceptable values are:
- "boot" - Boot the card OS image specified by the combination
- of firmware, ramdisk, cmdline and bootmode
- sysfs entries.
- "reset" - Initiates device reset.
- "shutdown" - Initiates card OS shutdown.
+
+
+ ========== ===================================================
+ "boot" Boot the card OS image specified by the combination
+ of firmware, ramdisk, cmdline and bootmode
+ sysfs entries.
+ "reset" Initiates device reset.
+ "shutdown" Initiates card OS shutdown.
+ ========== ===================================================

What: /sys/class/mic/mic(x)/shutdown_status
Date: October 2013
@@ -69,12 +78,15 @@ Description:
OS can shutdown because of various reasons. When read, this
entry provides the status on why the card OS was shutdown.
Possible values are:
- "nop" - shutdown status is not applicable, when the card OS is
- "online"
- "crashed" - Shutdown because of a HW or SW crash.
- "halted" - Shutdown because of a halt command.
- "poweroff" - Shutdown because of a poweroff command.
- "restart" - Shutdown because of a restart command.
+
+ ========== ===================================================
+ "nop" shutdown status is not applicable, when the card OS
+ is "online"
+ "crashed" Shutdown because of a HW or SW crash.
+ "halted" Shutdown because of a halt command.
+ "poweroff" Shutdown because of a poweroff command.
+ "restart" Shutdown because of a restart command.
+ ========== ===================================================

What: /sys/class/mic/mic(x)/cmdline
Date: October 2013
diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
index ae1276efa45a..bf33f4fda58f 100644
--- a/Documentation/ABI/testing/sysfs-class-ocxl
+++ b/Documentation/ABI/testing/sysfs-class-ocxl
@@ -11,8 +11,11 @@ Contact: [email protected]
Description: read only
Number of contexts for the AFU, in the format <n>/<max>
where:
+
+ ==== ===============================================
n: number of currently active contexts, for debug
max: maximum number of contexts supported by the AFU
+ ==== ===============================================

What: /sys/class/ocxl/<afu name>/pp_mmio_size
Date: January 2018
diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index dbccb2fcd7ce..d4319a04c302 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -1,4 +1,4 @@
-===== General Properties =====
+**General Properties**

What: /sys/class/power_supply/<supply_name>/manufacturer
Date: May 2007
@@ -72,6 +72,7 @@ Description:
critically low).

Access: Read, Write
+
Valid values: 0 - 100 (percent)

What: /sys/class/power_supply/<supply_name>/capacity_error_margin
@@ -96,7 +97,9 @@ Description:
Coarse representation of battery capacity.

Access: Read
- Valid values: "Unknown", "Critical", "Low", "Normal", "High",
+
+ Valid values:
+ "Unknown", "Critical", "Low", "Normal", "High",
"Full"

What: /sys/class/power_supply/<supply_name>/current_avg
@@ -139,6 +142,7 @@ Description:
throttling for thermal cooling or improving battery health.

Access: Read, Write
+
Valid values: Represented in microamps

What: /sys/class/power_supply/<supply_name>/charge_control_limit_max
@@ -148,6 +152,7 @@ Description:
Maximum legal value for the charge_control_limit property.

Access: Read
+
Valid values: Represented in microamps

What: /sys/class/power_supply/<supply_name>/charge_control_start_threshold
@@ -168,6 +173,7 @@ Description:
stop.

Access: Read, Write
+
Valid values: 0 - 100 (percent)

What: /sys/class/power_supply/<supply_name>/charge_type
@@ -183,7 +189,9 @@ Description:
different algorithm.

Access: Read, Write
- Valid values: "Unknown", "N/A", "Trickle", "Fast", "Standard",
+
+ Valid values:
+ "Unknown", "N/A", "Trickle", "Fast", "Standard",
"Adaptive", "Custom"

What: /sys/class/power_supply/<supply_name>/charge_term_current
@@ -194,6 +202,7 @@ Description:
when the battery is considered full and charging should end.

Access: Read
+
Valid values: Represented in microamps

What: /sys/class/power_supply/<supply_name>/health
@@ -204,7 +213,9 @@ Description:
functionality.

Access: Read
- Valid values: "Unknown", "Good", "Overheat", "Dead",
+
+ Valid values:
+ "Unknown", "Good", "Overheat", "Dead",
"Over voltage", "Unspecified failure", "Cold",
"Watchdog timer expire", "Safety timer expire",
"Over current", "Calibration required", "Warm",
@@ -218,6 +229,7 @@ Description:
for a battery charge cycle.

Access: Read
+
Valid values: Represented in microamps

What: /sys/class/power_supply/<supply_name>/present
@@ -227,9 +239,13 @@ Description:
Reports whether a battery is present or not in the system.

Access: Read
+
Valid values:
+
+ == =======
0: Absent
1: Present
+ == =======

What: /sys/class/power_supply/<supply_name>/status
Date: May 2007
@@ -240,7 +256,9 @@ Description:
used to enable/disable charging to the battery.

Access: Read, Write
- Valid values: "Unknown", "Charging", "Discharging",
+
+ Valid values:
+ "Unknown", "Charging", "Discharging",
"Not charging", "Full"

What: /sys/class/power_supply/<supply_name>/technology
@@ -250,7 +268,9 @@ Description:
Describes the battery technology supported by the supply.

Access: Read
- Valid values: "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
+
+ Valid values:
+ "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
"NiCd", "LiMn"

What: /sys/class/power_supply/<supply_name>/temp
@@ -260,6 +280,7 @@ Description:
Reports the current TBAT battery temperature reading.

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_alert_max
@@ -274,6 +295,7 @@ Description:
critically high, and charging has stopped).

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_alert_min
@@ -289,6 +311,7 @@ Description:
remedy the situation).

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_max
@@ -299,6 +322,7 @@ Description:
charging.

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_min
@@ -309,6 +333,7 @@ Description:
charging.

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/voltage_avg,
@@ -320,6 +345,7 @@ Description:
which they average readings to smooth out the reported value.

Access: Read
+
Valid values: Represented in microvolts

What: /sys/class/power_supply/<supply_name>/voltage_max,
@@ -330,6 +356,7 @@ Description:
during charging.

Access: Read
+
Valid values: Represented in microvolts

What: /sys/class/power_supply/<supply_name>/voltage_min,
@@ -340,6 +367,7 @@ Description:
during discharging.

Access: Read
+
Valid values: Represented in microvolts

What: /sys/class/power_supply/<supply_name>/voltage_now,
@@ -350,9 +378,10 @@ Description:
This value is not averaged/smoothed.

Access: Read
+
Valid values: Represented in microvolts

-===== USB Properties =====
+**USB Properties**

What: /sys/class/power_supply/<supply_name>/current_avg
Date: May 2007
@@ -363,6 +392,7 @@ Description:
average readings to smooth out the reported value.

Access: Read
+
Valid values: Represented in microamps


@@ -373,6 +403,7 @@ Description:
Reports the maximum IBUS current the supply can support.

Access: Read
+
Valid values: Represented in microamps

What: /sys/class/power_supply/<supply_name>/current_now
@@ -385,6 +416,7 @@ Description:
within the reported min/max range.

Access: Read, Write
+
Valid values: Represented in microamps

What: /sys/class/power_supply/<supply_name>/input_current_limit
@@ -399,6 +431,7 @@ Description:
solved using power limit use input_current_limit.

Access: Read, Write
+
Valid values: Represented in microamps

What: /sys/class/power_supply/<supply_name>/input_voltage_limit
@@ -441,10 +474,14 @@ Description:
USB supply so voltage and current can be controlled).

Access: Read, Write
+
Valid values:
+
+ == ==================================================
0: Offline
1: Online Fixed - Fixed Voltage Supply
2: Online Programmable - Programmable Voltage Supply
+ == ==================================================

What: /sys/class/power_supply/<supply_name>/temp
Date: May 2007
@@ -455,6 +492,7 @@ Description:
TJUNC temperature of an IC)

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_alert_max
@@ -470,6 +508,7 @@ Description:
remedy the situation).

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_alert_min
@@ -485,6 +524,7 @@ Description:
accordingly to remedy the situation).

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_max
@@ -494,6 +534,7 @@ Description:
Reports the maximum allowed supply temperature for operation.

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/temp_min
@@ -503,6 +544,7 @@ Description:
Reports the mainimum allowed supply temperature for operation.

Access: Read
+
Valid values: Represented in 1/10 Degrees Celsius

What: /sys/class/power_supply/<supply_name>/usb_type
@@ -514,7 +556,9 @@ Description:
is attached.

Access: Read-Only
- Valid values: "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
+
+ Valid values:
+ "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
"PD_DRP", "PD_PPS", "BrickID"

What: /sys/class/power_supply/<supply_name>/voltage_max
@@ -524,6 +568,7 @@ Description:
Reports the maximum VBUS voltage the supply can support.

Access: Read
+
Valid values: Represented in microvolts

What: /sys/class/power_supply/<supply_name>/voltage_min
@@ -533,6 +578,7 @@ Description:
Reports the minimum VBUS voltage the supply can support.

Access: Read
+
Valid values: Represented in microvolts

What: /sys/class/power_supply/<supply_name>/voltage_now
@@ -545,9 +591,10 @@ Description:
within the reported min/max range.

Access: Read, Write
+
Valid values: Represented in microvolts

-===== Device Specific Properties =====
+**Device Specific Properties**

What: /sys/class/power/ds2760-battery.*/charge_now
Date: May 2010
@@ -581,6 +628,7 @@ Description:
will drop to 0 A) and will trigger interrupt.

Valid values:
+
- 5, 6 or 7 (hours),
- 0: disabled.

@@ -595,6 +643,7 @@ Description:
will drop to 0 A) and will trigger interrupt.

Valid values:
+
- 4 - 16 (hours), step by 2 (rounded down)
- 0: disabled.

@@ -609,6 +658,7 @@ Description:
interrupt and start top-off charging mode.

Valid values:
+
- 100000 - 200000 (microamps), step by 25000 (rounded down)
- 200000 - 350000 (microamps), step by 50000 (rounded down)
- 0: disabled.
@@ -624,6 +674,7 @@ Description:
will drop to 0 A) and will trigger interrupt.

Valid values:
+
- 0 - 70 (minutes), step by 10 (rounded down)

What: /sys/class/power_supply/bq24257-charger/ovp_voltage
@@ -637,6 +688,7 @@ Description:
device datasheet for details.

Valid values:
+
- 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000,
10500000 (all uV)

@@ -652,6 +704,7 @@ Description:
lower than the set value. See device datasheet for details.

Valid values:
+
- 4200000, 4280000, 4360000, 4440000, 4520000, 4600000, 4680000,
4760000 (all uV)

@@ -666,6 +719,7 @@ Description:
the charger operates normally. See device datasheet for details.

Valid values:
+
- 1: enabled
- 0: disabled

@@ -681,6 +735,7 @@ Description:
from the system. See device datasheet for details.

Valid values:
+
- 1: enabled
- 0: disabled

diff --git a/Documentation/ABI/testing/sysfs-class-power-twl4030 b/Documentation/ABI/testing/sysfs-class-power-twl4030
index b4fd32d210c5..7ac36dba87bc 100644
--- a/Documentation/ABI/testing/sysfs-class-power-twl4030
+++ b/Documentation/ABI/testing/sysfs-class-power-twl4030
@@ -4,18 +4,20 @@ Description:
Writing to this can disable charging.

Possible values are:
- "auto" - draw power as appropriate for detected
- power source and battery status.
- "off" - do not draw any power.
- "continuous"
- - activate mode described as "linear" in
- TWL data sheets. This uses whatever
- current is available and doesn't switch off
- when voltage drops.

- This is useful for unstable power sources
- such as bicycle dynamo, but care should
- be taken that battery is not over-charged.
+ ============= ===========================================
+ "auto" draw power as appropriate for detected
+ power source and battery status.
+ "off" do not draw any power.
+ "continuous" activate mode described as "linear" in
+ TWL data sheets. This uses whatever
+ current is available and doesn't switch off
+ when voltage drops.
+
+ This is useful for unstable power sources
+ such as bicycle dynamo, but care should
+ be taken that battery is not over-charged.
+ ============= ===========================================

What: /sys/class/power_supply/twl4030_ac/mode
Description:
@@ -23,6 +25,9 @@ Description:
Writing to this can disable charging.

Possible values are:
- "auto" - draw power as appropriate for detected
- power source and battery status.
- "off" - do not draw any power.
+
+ ====== ===========================================
+ "auto" draw power as appropriate for detected
+ power source and battery status.
+ "off" do not draw any power.
+ ====== ===========================================
diff --git a/Documentation/ABI/testing/sysfs-class-rc b/Documentation/ABI/testing/sysfs-class-rc
index 6c0d6c8cb911..9c8ff7910858 100644
--- a/Documentation/ABI/testing/sysfs-class-rc
+++ b/Documentation/ABI/testing/sysfs-class-rc
@@ -21,15 +21,22 @@ KernelVersion: 2.6.36
Contact: Mauro Carvalho Chehab <[email protected]>
Description:
Reading this file returns a list of available protocols,
- something like:
+ something like::
+
"rc5 [rc6] nec jvc [sony]"
+
Enabled protocols are shown in [] brackets.
+
Writing "+proto" will add a protocol to the list of enabled
protocols.
+
Writing "-proto" will remove a protocol from the list of enabled
protocols.
+
Writing "proto" will enable only "proto".
+
Writing "none" will disable all protocols.
+
Write fails with EINVAL if an invalid protocol combination or
unknown protocol name is used.

@@ -39,11 +46,13 @@ KernelVersion: 3.15
Contact: Mauro Carvalho Chehab <[email protected]>
Description:
Sets the scancode filter expected value.
+
Use in combination with /sys/class/rc/rcN/filter_mask to set the
expected value of the bits set in the filter mask.
If the hardware supports it then scancodes which do not match
the filter will be ignored. Otherwise the write will fail with
an error.
+
This value may be reset to 0 if the current protocol is altered.

What: /sys/class/rc/rcN/filter_mask
@@ -56,9 +65,11 @@ Description:
of the scancode which should be compared against the expected
value. A value of 0 disables the filter to allow all valid
scancodes to be processed.
+
If the hardware supports it then scancodes which do not match
the filter will be ignored. Otherwise the write will fail with
an error.
+
This value may be reset to 0 if the current protocol is altered.

What: /sys/class/rc/rcN/wakeup_protocols
@@ -67,15 +78,22 @@ KernelVersion: 4.11
Contact: Mauro Carvalho Chehab <[email protected]>
Description:
Reading this file returns a list of available protocols to use
- for the wakeup filter, something like:
+ for the wakeup filter, something like::
+
"rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce"
+
Note that protocol variants are listed, so "nec", "sony",
"rc-5", "rc-6" have their different bit length encodings
listed if available.
+
The enabled wakeup protocol is shown in [] brackets.
+
Only one protocol can be selected at a time.
+
Writing "proto" will use "proto" for wakeup events.
+
Writing "none" will disable wakeup.
+
Write fails with EINVAL if an invalid protocol combination or
unknown protocol name is used, or if wakeup is not supported by
the hardware.
@@ -86,13 +104,17 @@ KernelVersion: 3.15
Contact: Mauro Carvalho Chehab <[email protected]>
Description:
Sets the scancode wakeup filter expected value.
+
Use in combination with /sys/class/rc/rcN/wakeup_filter_mask to
set the expected value of the bits set in the wakeup filter mask
to trigger a system wake event.
+
If the hardware supports it and wakeup_filter_mask is not 0 then
scancodes which match the filter will wake the system from e.g.
suspend to RAM or power off.
+
Otherwise the write will fail with an error.
+
This value may be reset to 0 if the wakeup protocol is altered.

What: /sys/class/rc/rcN/wakeup_filter_mask
@@ -101,11 +123,15 @@ KernelVersion: 3.15
Contact: Mauro Carvalho Chehab <[email protected]>
Description:
Sets the scancode wakeup filter mask of bits to compare.
+
Use in combination with /sys/class/rc/rcN/wakeup_filter to set
the bits of the scancode which should be compared against the
expected value to trigger a system wake event.
+
If the hardware supports it and wakeup_filter_mask is not 0 then
scancodes which match the filter will wake the system from e.g.
suspend to RAM or power off.
+
Otherwise the write will fail with an error.
+
This value may be reset to 0 if the wakeup protocol is altered.
diff --git a/Documentation/ABI/testing/sysfs-class-scsi_host b/Documentation/ABI/testing/sysfs-class-scsi_host
index bafc59fd7b69..7c98d8f43c45 100644
--- a/Documentation/ABI/testing/sysfs-class-scsi_host
+++ b/Documentation/ABI/testing/sysfs-class-scsi_host
@@ -56,8 +56,9 @@ Description:
management) on top, which makes it match the Windows IRST (Intel
Rapid Storage Technology) driver settings. This setting is also
close to min_power, except that:
+
a) It does not use host-initiated slumber mode, but it does
- allow device-initiated slumber
+ allow device-initiated slumber
b) It does not enable low power device sleep mode (DevSlp).

What: /sys/class/scsi_host/hostX/em_message
@@ -70,8 +71,8 @@ Description:
protocol, writes and reads correspond to the LED message format
as defined in the AHCI spec.

- The user must turn sw_activity (under /sys/block/*/device/) OFF
- it they wish to control the activity LED via the em_message
+ The user must turn sw_activity (under `/sys/block/*/device/`)
+ OFF it they wish to control the activity LED via the em_message
file.

em_message_type: (RO) Displays the current enclosure management
diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec
index b834671522d6..b7794e02ad20 100644
--- a/Documentation/ABI/testing/sysfs-class-typec
+++ b/Documentation/ABI/testing/sysfs-class-typec
@@ -40,10 +40,13 @@ Description:
attribute will not return until the operation has finished.

Valid values:
- - source (The port will behave as source only DFP port)
- - sink (The port will behave as sink only UFP port)
- - dual (The port will behave as dual-role-data and
+
+ ====== ==============================================
+ source (The port will behave as source only DFP port)
+ sink (The port will behave as sink only UFP port)
+ dual (The port will behave as dual-role-data and
dual-role-power port)
+ ====== ==============================================

What: /sys/class/typec/<port>/vconn_source
Date: April 2017
@@ -59,6 +62,7 @@ Description:
generates uevent KOBJ_CHANGE.

Valid values:
+
- "no" when the port is not the VCONN Source
- "yes" when the port is the VCONN Source

@@ -72,6 +76,7 @@ Description:
power operation mode should show "usb_power_delivery".

Valid values:
+
- default
- 1.5A
- 3.0A
@@ -191,6 +196,7 @@ Date: April 2017
Contact: Heikki Krogerus <[email protected]>
Description:
Shows type of the plug on the cable:
+
- type-a - Standard A
- type-b - Standard B
- type-c
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
index 7e43cdce9a52..f7b360a61b21 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
+++ b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
@@ -7,6 +7,7 @@ Description:
(RO) Hexadecimal bitmask of the TAD attributes are reported by
the platform firmware (see ACPI 6.2, section 9.18.2):

+ ======= ======================================================
BIT(0): AC wakeup implemented if set
BIT(1): DC wakeup implemented if set
BIT(2): Get/set real time features implemented if set
@@ -16,6 +17,7 @@ Description:
BIT(6): The AC timer wakes up from S5 if set
BIT(7): The DC timer wakes up from S4 if set
BIT(8): The DC timer wakes up from S5 if set
+ ======= ======================================================

The other bits are reserved.

@@ -62,9 +64,11 @@ Description:
timer status with the following meaning of bits (see ACPI 6.2,
Section 9.18.5):

+ ======= ======================================================
Bit(0): The timer has expired if set.
Bit(1): The timer has woken up the system from a sleep state
(S3 or S4/S5 if supported) if set.
+ ======= ======================================================

The other bits are reserved.

diff --git a/Documentation/ABI/testing/sysfs-devices-platform-docg3 b/Documentation/ABI/testing/sysfs-devices-platform-docg3
index 8aa36716882f..378c42694bfb 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-docg3
+++ b/Documentation/ABI/testing/sysfs-devices-platform-docg3
@@ -9,8 +9,10 @@ Description:
The protection has information embedded whether it blocks reads,
writes or both.
The result is:
- 0 -> the DPS is not keylocked
- 1 -> the DPS is keylocked
+
+ - 0 -> the DPS is not keylocked
+ - 1 -> the DPS is keylocked
+
Users: None identified so far.

What: /sys/devices/platform/docg3/f[0-3]_dps[01]_protection_key
@@ -27,8 +29,12 @@ Description:
Entering the correct value toggle the lock, and can be observed
through f[0-3]_dps[01]_is_keylocked.
Possible values are:
+
- 8 bytes
+
Typical values are:
+
- "00000000"
- "12345678"
+
Users: None identified so far.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
index 2107082426da..e45ac2e865d5 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
+++ b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
@@ -17,10 +17,10 @@ Description:
to overlay planes.

Selects the composition mode for the overlay. Possible values
- are
+ are:

- 0 - Alpha Blending
- 1 - ROP3
+ - 0 - Alpha Blending
+ - 1 - ROP3

What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_position
Date: May 2012
@@ -30,7 +30,7 @@ Description:
to overlay planes.

Stores the x,y overlay position on the display in pixels. The
- position format is `[0-9]+,[0-9]+'.
+ position format is `[0-9]+,[0-9]+`.

What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_rop3
Date: May 2012
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index b555df825447..274c337ec6a9 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -151,23 +151,28 @@ Description:
The processor idle states which are available for use have the
following attributes:

- name: (RO) Name of the idle state (string).
+ ======== ==== =================================================
+ name: (RO) Name of the idle state (string).

latency: (RO) The latency to exit out of this idle state (in
- microseconds).
+ microseconds).

- power: (RO) The power consumed while in this idle state (in
- milliwatts).
+ power: (RO) The power consumed while in this idle state (in
+ milliwatts).

- time: (RO) The total time spent in this idle state (in microseconds).
+ time: (RO) The total time spent in this idle state
+ (in microseconds).

- usage: (RO) Number of times this state was entered (a count).
+ usage: (RO) Number of times this state was entered (a count).

- above: (RO) Number of times this state was entered, but the
- observed CPU idle duration was too short for it (a count).
+ above: (RO) Number of times this state was entered, but the
+ observed CPU idle duration was too short for it
+ (a count).

- below: (RO) Number of times this state was entered, but the
- observed CPU idle duration was too long for it (a count).
+ below: (RO) Number of times this state was entered, but the
+ observed CPU idle duration was too long for it
+ (a count).
+ ======== ==== =================================================

What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/desc
Date: February 2008
@@ -290,6 +295,7 @@ Description: Processor frequency boosting control
This switch controls the boost setting for the whole system.
Boosting allows the CPU and the firmware to run at a frequency
beyound it's nominal limit.
+
More details can be found in
Documentation/admin-guide/pm/cpufreq.rst

@@ -337,43 +343,57 @@ Contact: Sudeep Holla <[email protected]>
Description: Parameters for the CPU cache attributes

allocation_policy:
- - WriteAllocate: allocate a memory location to a cache line
- on a cache miss because of a write
- - ReadAllocate: allocate a memory location to a cache line
+ - WriteAllocate:
+ allocate a memory location to a cache line
+ on a cache miss because of a write
+ - ReadAllocate:
+ allocate a memory location to a cache line
on a cache miss because of a read
- - ReadWriteAllocate: both writeallocate and readallocate
+ - ReadWriteAllocate:
+ both writeallocate and readallocate

- attributes: LEGACY used only on IA64 and is same as write_policy
+ attributes:
+ LEGACY used only on IA64 and is same as write_policy

- coherency_line_size: the minimum amount of data in bytes that gets
+ coherency_line_size:
+ the minimum amount of data in bytes that gets
transferred from memory to cache

- level: the cache hierarchy in the multi-level cache configuration
+ level:
+ the cache hierarchy in the multi-level cache configuration

- number_of_sets: total number of sets in the cache, a set is a
+ number_of_sets:
+ total number of sets in the cache, a set is a
collection of cache lines with the same cache index

- physical_line_partition: number of physical cache line per cache tag
+ physical_line_partition:
+ number of physical cache line per cache tag

- shared_cpu_list: the list of logical cpus sharing the cache
+ shared_cpu_list:
+ the list of logical cpus sharing the cache

- shared_cpu_map: logical cpu mask containing the list of cpus sharing
+ shared_cpu_map:
+ logical cpu mask containing the list of cpus sharing
the cache

- size: the total cache size in kB
+ size:
+ the total cache size in kB

type:
- Instruction: cache that only holds instructions
- Data: cache that only caches data
- Unified: cache that holds both data and instructions

- ways_of_associativity: degree of freedom in placing a particular block
- of memory in the cache
+ ways_of_associativity:
+ degree of freedom in placing a particular block
+ of memory in the cache

write_policy:
- - WriteThrough: data is written to both the cache line
+ - WriteThrough:
+ data is written to both the cache line
and to the block in the lower-level memory
- - WriteBack: data is written only to the cache line and
+ - WriteBack:
+ data is written only to the cache line and
the modified cache line is written to main
memory only when it is replaced

@@ -414,30 +434,30 @@ Description: POWERNV CPUFreq driver's frequency throttle stats directory and
throttle attributes exported in the 'throttle_stats' directory:

- turbo_stat : This file gives the total number of times the max
- frequency is throttled to lower frequency in turbo (at and above
- nominal frequency) range of frequencies.
+ frequency is throttled to lower frequency in turbo (at and above
+ nominal frequency) range of frequencies.

- sub_turbo_stat : This file gives the total number of times the
- max frequency is throttled to lower frequency in sub-turbo(below
- nominal frequency) range of frequencies.
+ max frequency is throttled to lower frequency in sub-turbo(below
+ nominal frequency) range of frequencies.

- unthrottle : This file gives the total number of times the max
- frequency is unthrottled after being throttled.
+ frequency is unthrottled after being throttled.

- powercap : This file gives the total number of times the max
- frequency is throttled due to 'Power Capping'.
+ frequency is throttled due to 'Power Capping'.

- overtemp : This file gives the total number of times the max
- frequency is throttled due to 'CPU Over Temperature'.
+ frequency is throttled due to 'CPU Over Temperature'.

- supply_fault : This file gives the total number of times the
- max frequency is throttled due to 'Power Supply Failure'.
+ max frequency is throttled due to 'Power Supply Failure'.

- overcurrent : This file gives the total number of times the
- max frequency is throttled due to 'Overcurrent'.
+ max frequency is throttled due to 'Overcurrent'.

- occ_reset : This file gives the total number of times the max
- frequency is throttled due to 'OCC Reset'.
+ frequency is throttled due to 'OCC Reset'.

The sysfs attributes representing different throttle reasons like
powercap, overtemp, supply_fault, overcurrent and occ_reset map to
@@ -469,8 +489,9 @@ What: /sys/devices/system/cpu/cpuX/regs/
Date: June 2016
Contact: Linux ARM Kernel Mailing list <[email protected]>
Description: AArch64 CPU registers
+
'identification' directory exposes the CPU ID registers for
- identifying model and revision of the CPU.
+ identifying model and revision of the CPU.

What: /sys/devices/system/cpu/cpu#/cpu_capacity
Date: December 2016
@@ -497,9 +518,11 @@ Description: Information about CPU vulnerabilities
vulnerabilities. The output of those files reflects the
state of the CPUs in the system. Possible output values:

+ ================ ==============================================
"Not affected" CPU is not affected by the vulnerability
"Vulnerable" CPU is affected and no mitigation in effect
"Mitigation: $M" CPU is affected and mitigation $M is in effect
+ ================ ==============================================

See also: Documentation/admin-guide/hw-vuln/index.rst

@@ -515,12 +538,14 @@ Description: Control Symetric Multi Threading (SMT)
control: Read/write interface to control SMT. Possible
values:

+ ================ =========================================
"on" SMT is enabled
"off" SMT is disabled
"forceoff" SMT is force disabled. Cannot be changed.
"notsupported" SMT is not supported by the CPU
"notimplemented" SMT runtime toggling is not
implemented for the architecture
+ ================ =========================================

If control status is "forceoff" or "notsupported" writes
are rejected.
diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
index 470def06ab0a..1a8ee26e92ae 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
+++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
@@ -5,8 +5,10 @@ Contact: Vernon Mauery <[email protected]>
Description: The state file allows a means by which to change in and
out of Premium Real-Time Mode (PRTM), as well as the
ability to query the current state.
- 0 => PRTM off
- 1 => PRTM enabled
+
+ - 0 => PRTM off
+ - 1 => PRTM enabled
+
Users: The ibm-prtm userspace daemon uses this interface.


diff --git a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
index 4d63a7904b94..42214b4ff14a 100644
--- a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
+++ b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
@@ -6,11 +6,13 @@ Description: Read/write the current state of DDR Backup Mode, which controls
if DDR power rails will be kept powered during system suspend.
("on"/"1" = enabled, "off"/"0" = disabled).
Two types of power switches (or control signals) can be used:
+
A. With a momentary power switch (or pulse signal), DDR
Backup Mode is enabled by default when available, as the
PMIC will be configured only during system suspend.
B. With a toggle power switch (or level signal), the
following steps must be followed exactly:
+
1. Configure PMIC for backup mode, to change the role of
the accessory power switch from a power switch to a
wake-up switch,
@@ -20,8 +22,10 @@ Description: Read/write the current state of DDR Backup Mode, which controls
3. Suspend system,
4. Switch accessory power switch on, to resume the
system.
+
DDR Backup Mode must be explicitly enabled by the user,
to invoke step 1.
+
See also Documentation/devicetree/bindings/mfd/bd9571mwv.txt.
Users: User space applications for embedded boards equipped with a
BD9571MWV PMIC.
diff --git a/Documentation/ABI/testing/sysfs-driver-genwqe b/Documentation/ABI/testing/sysfs-driver-genwqe
index 64ac6d567c4b..69d855dc4c47 100644
--- a/Documentation/ABI/testing/sysfs-driver-genwqe
+++ b/Documentation/ABI/testing/sysfs-driver-genwqe
@@ -29,8 +29,12 @@ What: /sys/class/genwqe/genwqe<n>_card/reload_bitstream
Date: May 2014
Contact: [email protected]
Description: Interface to trigger a PCIe card reset to reload the bitstream.
+
+ ::
+
sudo sh -c 'echo 1 > \
/sys/class/genwqe/genwqe0_card/reload_bitstream'
+
If successfully, the card will come back with the bitstream set
on 'next_bitstream'.

@@ -64,8 +68,11 @@ Description: Base clock frequency of the card.
What: /sys/class/genwqe/genwqe<n>_card/device/sriov_numvfs
Date: Oct 2013
Contact: [email protected]
-Description: Enable VFs (1..15):
+Description: Enable VFs (1..15)::
+
sudo sh -c 'echo 15 > \
/sys/bus/pci/devices/0000\:1b\:00.0/sriov_numvfs'
- Disable VFs:
+
+ Disable VFs::
+
Write a 0 into the same sysfs entry.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
index 305dffd229a8..de07be314efc 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
+++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
@@ -12,7 +12,9 @@ KernelVersion: 4.1
Contact: Michal Malý <[email protected]>
Description: Displays a set of alternate modes supported by a wheel. Each
mode is listed as follows:
+
Tag: Mode Name
+
Currently active mode is marked with an asterisk. List also
contains an abstract item "native" which always denotes the
native mode of the wheel. Echoing the mode tag switches the
@@ -24,24 +26,30 @@ Description: Displays a set of alternate modes supported by a wheel. Each
This entry is not created for devices that have only one mode.

Currently supported mode switches:
- Driving Force Pro:
+
+ Driving Force Pro::
+
DF-EX --> DFP

- G25:
+ G25::
+
DF-EX --> DFP --> G25

- G27:
+ G27::
+
DF-EX <*> DFP <-> G25 <-> G27
DF-EX <*--------> G25 <-> G27
DF-EX <*----------------> G27

- G29:
+ G29::
+
DF-EX <*> DFP <-> G25 <-> G27 <-> G29
DF-EX <*--------> G25 <-> G27 <-> G29
DF-EX <*----------------> G27 <-> G29
DF-EX <*------------------------> G29

- DFGT:
+ DFGT::
+
DF-EX <*> DFP <-> DFGT
DF-EX <*--------> DFGT

diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
index 39dfa5cb1cc5..cd7b82a5c27d 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-wiimote
+++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
@@ -39,9 +39,13 @@ Description: While a device is initialized by the wiimote driver, we perform
Other strings for each device-type are available and may be
added if new device-specific detections are added.
Currently supported are:
- gen10: First Wii Remote generation
- gen20: Second Wii Remote Plus generation (builtin MP)
+
+ ============= =======================================
+ gen10: First Wii Remote generation
+ gen20: Second Wii Remote Plus generation
+ (builtin MP)
balanceboard: Wii Balance Board
+ ============= =======================================

What: /sys/bus/hid/drivers/wiimote/<dev>/bboard_calib
Date: May 2013
@@ -54,6 +58,7 @@ Description: This attribute is only provided if the device was detected as a
First, 0kg values for all 4 sensors are written, followed by the
17kg values for all 4 sensors and last the 34kg values for all 4
sensors.
+
Calibration data is already applied by the kernel to all input
values but may be used by user-space to perform other
transformations.
@@ -68,9 +73,11 @@ Description: This attribute is only provided if the device was detected as a
is prefixed with a +/-. Each value is a signed 16bit number.
Data is encoded as decimal numbers and specifies the offsets of
the analog sticks of the pro-controller.
+
Calibration data is already applied by the kernel to all input
values but may be used by user-space to perform other
transformations.
+
Calibration data is detected by the kernel during device setup.
You can write "scan\n" into this file to re-trigger calibration.
You can also write data directly in the form "x1:y1 x2:y2" to
diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
index 34d3a3359cf4..28c9c040de5d 100644
--- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop
+++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
@@ -9,10 +9,12 @@ Description: Some Samsung laptops have different "performance levels"
their fans quiet at all costs. Reading from this file
will show the current performance level. Writing to the
file can change this value.
+
Valid options:
- "silent"
- "normal"
- "overclock"
+ - "silent"
+ - "normal"
+ - "overclock"
+
Note that not all laptops support all of these options.
Specifically, not all support the "overclock" option,
and it's still unknown if this value even changes
@@ -25,8 +27,9 @@ Contact: Corentin Chary <[email protected]>
Description: Max battery charge level can be modified, battery cycle
life can be extended by reducing the max battery charge
level.
- 0 means normal battery mode (100% charge)
- 1 means battery life extender mode (80% charge)
+
+ - 0 means normal battery mode (100% charge)
+ - 1 means battery life extender mode (80% charge)

What: /sys/devices/platform/samsung/usb_charge
Date: December 1, 2011
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
index f34221b52b14..e5a438d84e1f 100644
--- a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
+++ b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
@@ -4,10 +4,12 @@ KernelVersion: 3.15
Contact: Azael Avalos <[email protected]>
Description: This file controls the keyboard backlight operation mode, valid
values are:
+
* 0x1 -> FN-Z
* 0x2 -> AUTO (also called TIMER)
* 0x8 -> ON
* 0x10 -> OFF
+
Note that from kernel 3.16 onwards this file accepts all listed
parameters, kernel 3.15 only accepts the first two (FN-Z and
AUTO).
@@ -41,8 +43,10 @@ KernelVersion: 3.15
Contact: Azael Avalos <[email protected]>
Description: This files controls the status of the touchpad and pointing
stick (if available), valid values are:
+
* 0 -> OFF
* 1 -> ON
+
Users: KToshiba

What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/available_kbd_modes
@@ -51,10 +55,12 @@ KernelVersion: 3.16
Contact: Azael Avalos <[email protected]>
Description: This file shows the supported keyboard backlight modes
the system supports, which can be:
+
* 0x1 -> FN-Z
* 0x2 -> AUTO (also called TIMER)
* 0x8 -> ON
* 0x10 -> OFF
+
Note that not all keyboard types support the listed modes.
See the entry named "available_kbd_modes"
Users: KToshiba
@@ -65,6 +71,7 @@ KernelVersion: 3.16
Contact: Azael Avalos <[email protected]>
Description: This file shows the current keyboard backlight type,
which can be:
+
* 1 -> Type 1, supporting modes FN-Z and AUTO
* 2 -> Type 2, supporting modes TIMER, ON and OFF
Users: KToshiba
@@ -75,10 +82,12 @@ KernelVersion: 4.0
Contact: Azael Avalos <[email protected]>
Description: This file controls the USB Sleep & Charge charging mode, which
can be:
+
* 0 -> Disabled (0x00)
* 1 -> Alternate (0x09)
* 2 -> Auto (0x21)
* 3 -> Typical (0x11)
+
Note that from kernel 4.1 onwards this file accepts all listed
values, kernel 4.0 only supports the first three.
Note that this feature only works when connected to power, if
@@ -93,8 +102,10 @@ Contact: Azael Avalos <[email protected]>
Description: This file controls the USB Sleep Functions under battery, and
set the level at which point they will be disabled, accepted
values can be:
+
* 0 -> Disabled
* 1-100 -> Battery level to disable sleep functions
+
Currently it prints two values, the first one indicates if the
feature is enabled or disabled, while the second one shows the
current battery level set.
@@ -107,8 +118,10 @@ Date: January 23, 2015
KernelVersion: 4.0
Contact: Azael Avalos <[email protected]>
Description: This file controls the USB Rapid Charge state, which can be:
+
* 0 -> Disabled
* 1 -> Enabled
+
Note that toggling this value requires a reboot for changes to
take effect.
Users: KToshiba
@@ -118,8 +131,10 @@ Date: January 23, 2015
KernelVersion: 4.0
Contact: Azael Avalos <[email protected]>
Description: This file controls the Sleep & Music state, which values can be:
+
* 0 -> Disabled
* 1 -> Enabled
+
Note that this feature only works when connected to power, if
you want to use it under battery, see the entry named
"sleep_functions_on_battery"
@@ -138,6 +153,7 @@ KernelVersion: 4.0
Contact: Azael Avalos <[email protected]>
Description: This file controls the state of the internal fan, valid
values are:
+
* 0 -> OFF
* 1 -> ON

@@ -147,8 +163,10 @@ KernelVersion: 4.0
Contact: Azael Avalos <[email protected]>
Description: This file controls the Special Functions (hotkeys) operation
mode, valid values are:
+
* 0 -> Normal Operation
* 1 -> Special Functions
+
In the "Normal Operation" mode, the F{1-12} keys are as usual
and the hotkeys are accessed via FN-F{1-12}.
In the "Special Functions" mode, the F{1-12} keys trigger the
@@ -163,8 +181,10 @@ KernelVersion: 4.0
Contact: Azael Avalos <[email protected]>
Description: This file controls whether the laptop should turn ON whenever
the LID is opened, valid values are:
+
* 0 -> Disabled
* 1 -> Enabled
+
Note that toggling this value requires a reboot for changes to
take effect.
Users: KToshiba
@@ -174,8 +194,10 @@ Date: February 12, 2015
KernelVersion: 4.0
Contact: Azael Avalos <[email protected]>
Description: This file controls the USB 3 functionality, valid values are:
+
* 0 -> Disabled (Acts as a regular USB 2)
* 1 -> Enabled (Full USB 3 functionality)
+
Note that toggling this value requires a reboot for changes to
take effect.
Users: KToshiba
@@ -188,10 +210,14 @@ Description: This file controls the Cooling Method feature.
Reading this file prints two values, the first is the actual cooling method
and the second is the maximum cooling method supported.
When the maximum cooling method is ONE, valid values are:
+
* 0 -> Maximum Performance
* 1 -> Battery Optimized
+
When the maximum cooling method is TWO, valid values are:
+
* 0 -> Maximum Performance
* 1 -> Performance
* 2 -> Battery Optimized
+
Users: KToshiba
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_haps b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
index a662370b4dbf..c938690ce10d 100644
--- a/Documentation/ABI/testing/sysfs-driver-toshiba_haps
+++ b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
@@ -4,10 +4,12 @@ KernelVersion: 3.17
Contact: Azael Avalos <[email protected]>
Description: This file controls the built-in accelerometer protection level,
valid values are:
+
* 0 -> Disabled
* 1 -> Low
* 2 -> Medium
* 3 -> High
+
The default potection value is set to 2 (Medium).
Users: KToshiba

diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom
index afc48fc163b5..16acaa5712ec 100644
--- a/Documentation/ABI/testing/sysfs-driver-wacom
+++ b/Documentation/ABI/testing/sysfs-driver-wacom
@@ -79,7 +79,9 @@ Description:
When the Wacom Intuos 4 is connected over Bluetooth, the
image has to contain 256 bytes (64x32 px 1 bit colour).
The format is also scrambled, like in the USB mode, and it can
- be summarized by converting 76543210 into GECA6420.
+ be summarized by converting::
+
+ 76543210 into GECA6420.
HGFEDCBA HFDB7531

What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/unpair_remote
diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi
index 613f42a9d5cd..e4afc2538210 100644
--- a/Documentation/ABI/testing/sysfs-firmware-acpi
+++ b/Documentation/ABI/testing/sysfs-firmware-acpi
@@ -12,11 +12,14 @@ Description:
image: The image bitmap. Currently a 32-bit BMP.
status: 1 if the image is valid, 0 if firmware invalidated it.
type: 0 indicates image is in BMP format.
+
+ ======== ===================================================
version: The version of the BGRT. Currently 1.
xoffset: The number of pixels between the left of the screen
and the left edge of the image.
yoffset: The number of pixels between the top of the screen
and the top edge of the image.
+ ======== ===================================================

What: /sys/firmware/acpi/hotplug/
Date: February 2013
@@ -33,12 +36,14 @@ Description:
The following setting is available to user space for each
hotplug profile:

+ ======== =======================================================
enabled: If set, the ACPI core will handle notifications of
- hotplug events associated with the given class of
- devices and will allow those devices to be ejected with
- the help of the _EJ0 control method. Unsetting it
- effectively disables hotplug for the correspoinding
- class of devices.
+ hotplug events associated with the given class of
+ devices and will allow those devices to be ejected with
+ the help of the _EJ0 control method. Unsetting it
+ effectively disables hotplug for the correspoinding
+ class of devices.
+ ======== =======================================================

The value of the above attribute is an integer number: 1 (set)
or 0 (unset). Attempts to write any other values to it will
@@ -71,86 +76,90 @@ Description:
To figure out where all the SCI's are coming from,
/sys/firmware/acpi/interrupts contains a file listing
every possible source, and the count of how many
- times it has triggered.
-
- $ cd /sys/firmware/acpi/interrupts
- $ grep . *
- error: 0
- ff_gbl_lock: 0 enable
- ff_pmtimer: 0 invalid
- ff_pwr_btn: 0 enable
- ff_rt_clk: 2 disable
- ff_slp_btn: 0 invalid
- gpe00: 0 invalid
- gpe01: 0 enable
- gpe02: 108 enable
- gpe03: 0 invalid
- gpe04: 0 invalid
- gpe05: 0 invalid
- gpe06: 0 enable
- gpe07: 0 enable
- gpe08: 0 invalid
- gpe09: 0 invalid
- gpe0A: 0 invalid
- gpe0B: 0 invalid
- gpe0C: 0 invalid
- gpe0D: 0 invalid
- gpe0E: 0 invalid
- gpe0F: 0 invalid
- gpe10: 0 invalid
- gpe11: 0 invalid
- gpe12: 0 invalid
- gpe13: 0 invalid
- gpe14: 0 invalid
- gpe15: 0 invalid
- gpe16: 0 invalid
- gpe17: 1084 enable
- gpe18: 0 enable
- gpe19: 0 invalid
- gpe1A: 0 invalid
- gpe1B: 0 invalid
- gpe1C: 0 invalid
- gpe1D: 0 invalid
- gpe1E: 0 invalid
- gpe1F: 0 invalid
- gpe_all: 1192
- sci: 1194
- sci_not: 0
-
- sci - The number of times the ACPI SCI
- has been called and claimed an interrupt.
-
- sci_not - The number of times the ACPI SCI
- has been called and NOT claimed an interrupt.
-
- gpe_all - count of SCI caused by GPEs.
-
- gpeXX - count for individual GPE source
-
- ff_gbl_lock - Global Lock
-
- ff_pmtimer - PM Timer
-
- ff_pwr_btn - Power Button
-
- ff_rt_clk - Real Time Clock
-
- ff_slp_btn - Sleep Button
-
- error - an interrupt that can't be accounted for above.
-
- invalid: it's either a GPE or a Fixed Event that
- doesn't have an event handler.
-
- disable: the GPE/Fixed Event is valid but disabled.
-
- enable: the GPE/Fixed Event is valid and enabled.
-
- Root has permission to clear any of these counters. Eg.
- # echo 0 > gpe11
-
- All counters can be cleared by clearing the total "sci":
- # echo 0 > sci
+ times it has triggered::
+
+ $ cd /sys/firmware/acpi/interrupts
+ $ grep . *
+ error: 0
+ ff_gbl_lock: 0 enable
+ ff_pmtimer: 0 invalid
+ ff_pwr_btn: 0 enable
+ ff_rt_clk: 2 disable
+ ff_slp_btn: 0 invalid
+ gpe00: 0 invalid
+ gpe01: 0 enable
+ gpe02: 108 enable
+ gpe03: 0 invalid
+ gpe04: 0 invalid
+ gpe05: 0 invalid
+ gpe06: 0 enable
+ gpe07: 0 enable
+ gpe08: 0 invalid
+ gpe09: 0 invalid
+ gpe0A: 0 invalid
+ gpe0B: 0 invalid
+ gpe0C: 0 invalid
+ gpe0D: 0 invalid
+ gpe0E: 0 invalid
+ gpe0F: 0 invalid
+ gpe10: 0 invalid
+ gpe11: 0 invalid
+ gpe12: 0 invalid
+ gpe13: 0 invalid
+ gpe14: 0 invalid
+ gpe15: 0 invalid
+ gpe16: 0 invalid
+ gpe17: 1084 enable
+ gpe18: 0 enable
+ gpe19: 0 invalid
+ gpe1A: 0 invalid
+ gpe1B: 0 invalid
+ gpe1C: 0 invalid
+ gpe1D: 0 invalid
+ gpe1E: 0 invalid
+ gpe1F: 0 invalid
+ gpe_all: 1192
+ sci: 1194
+ sci_not: 0
+
+ =========== ==================================================
+ sci The number of times the ACPI SCI
+ has been called and claimed an interrupt.
+
+ sci_not The number of times the ACPI SCI
+ has been called and NOT claimed an interrupt.
+
+ gpe_all count of SCI caused by GPEs.
+
+ gpeXX count for individual GPE source
+
+ ff_gbl_lock Global Lock
+
+ ff_pmtimer PM Timer
+
+ ff_pwr_btn Power Button
+
+ ff_rt_clk Real Time Clock
+
+ ff_slp_btn Sleep Button
+
+ error an interrupt that can't be accounted for above.
+
+ invalid it's either a GPE or a Fixed Event that
+ doesn't have an event handler.
+
+ disable the GPE/Fixed Event is valid but disabled.
+
+ enable the GPE/Fixed Event is valid and enabled.
+ =========== ==================================================
+
+ Root has permission to clear any of these counters. Eg.::
+
+ # echo 0 > gpe11
+
+ All counters can be cleared by clearing the total "sci"::
+
+ # echo 0 > sci

None of these counters has an effect on the function
of the system, they are simply statistics.
@@ -165,32 +174,34 @@ Description:

Let's take power button fixed event for example, please kill acpid
and other user space applications so that the machine won't shutdown
- when pressing the power button.
- # cat ff_pwr_btn
- 0 enabled
- # press the power button for 3 times;
- # cat ff_pwr_btn
- 3 enabled
- # echo disable > ff_pwr_btn
- # cat ff_pwr_btn
- 3 disabled
- # press the power button for 3 times;
- # cat ff_pwr_btn
- 3 disabled
- # echo enable > ff_pwr_btn
- # cat ff_pwr_btn
- 4 enabled
- /*
- * this is because the status bit is set even if the enable bit is cleared,
- * and it triggers an ACPI fixed event when the enable bit is set again
- */
- # press the power button for 3 times;
- # cat ff_pwr_btn
- 7 enabled
- # echo disable > ff_pwr_btn
- # press the power button for 3 times;
- # echo clear > ff_pwr_btn /* clear the status bit */
- # echo disable > ff_pwr_btn
- # cat ff_pwr_btn
- 7 enabled
+ when pressing the power button::
+
+ # cat ff_pwr_btn
+ 0 enabled
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 3 enabled
+ # echo disable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 3 disabled
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 3 disabled
+ # echo enable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 4 enabled
+ /*
+ * this is because the status bit is set even if the enable
+ * bit is cleared, and it triggers an ACPI fixed event when
+ * the enable bit is set again
+ */
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 7 enabled
+ # echo disable > ff_pwr_btn
+ # press the power button for 3 times;
+ # echo clear > ff_pwr_btn /* clear the status bit */
+ # echo disable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 7 enabled

diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
index 210ad44b95a5..fe0289c87768 100644
--- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries
+++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
@@ -33,7 +33,7 @@ Description:
doesn't matter), they will be represented in sysfs as
entries "T-0" through "T-(N-1)":

- Example entry directories:
+ Example entry directories::

/sys/firmware/dmi/entries/17-0
/sys/firmware/dmi/entries/17-1
@@ -50,61 +50,65 @@ Description:
Each DMI entry in sysfs has the common header values
exported as attributes:

- handle : The 16bit 'handle' that is assigned to this
+ ======== =================================================
+ handle The 16bit 'handle' that is assigned to this
entry by the firmware. This handle may be
referred to by other entries.
- length : The length of the entry, as presented in the
+ length The length of the entry, as presented in the
entry itself. Note that this is _not the
total count of bytes associated with the
- entry_. This value represents the length of
+ entry. This value represents the length of
the "formatted" portion of the entry. This
"formatted" region is sometimes followed by
the "unformatted" region composed of nul
terminated strings, with termination signalled
by a two nul characters in series.
- raw : The raw bytes of the entry. This includes the
+ raw The raw bytes of the entry. This includes the
"formatted" portion of the entry, the
"unformatted" strings portion of the entry,
and the two terminating nul characters.
- type : The type of the entry. This value is the same
+ type The type of the entry. This value is the same
as found in the directory name. It indicates
how the rest of the entry should be interpreted.
- instance: The instance ordinal of the entry for the
+ instance The instance ordinal of the entry for the
given type. This value is the same as found
in the parent directory name.
- position: The ordinal position (zero-based) of the entry
+ position The ordinal position (zero-based) of the entry
within the entirety of the DMI entry table.
+ ======== =================================================

- === Entry Specialization ===
+ **Entry Specialization**

Some entry types may have other information available in
sysfs. Not all types are specialized.

- --- Type 15 - System Event Log ---
+ **Type 15 - System Event Log**

This entry allows the firmware to export a log of
events the system has taken. This information is
typically backed by nvram, but the implementation
details are abstracted by this table. This entry's data
- is exported in the directory:
+ is exported in the directory::

- /sys/firmware/dmi/entries/15-0/system_event_log
+ /sys/firmware/dmi/entries/15-0/system_event_log

and has the following attributes (documented in the
SMBIOS / DMI specification under "System Event Log (Type 15)":

- area_length
- header_start_offset
- data_start_offset
- access_method
- status
- change_token
- access_method_address
- header_format
- per_log_type_descriptor_length
- type_descriptors_supported_count
+ - area_length
+ - header_start_offset
+ - data_start_offset
+ - access_method
+ - status
+ - change_token
+ - access_method_address
+ - header_format
+ - per_log_type_descriptor_length
+ - type_descriptors_supported_count

As well, the kernel exports the binary attribute:

- raw_event_log : The raw binary bits of the event log
+ ============= ====================================
+ raw_event_log The raw binary bits of the event log
as described by the DMI entry.
+ ============= ====================================
diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi
index 0faa0aaf4b6a..7a558354c1ee 100644
--- a/Documentation/ABI/testing/sysfs-firmware-gsmi
+++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
@@ -20,7 +20,7 @@ Description:

This directory has the same layout (and
underlying implementation as /sys/firmware/efi/vars.
- See Documentation/ABI/*/sysfs-firmware-efi-vars
+ See `Documentation/ABI/*/sysfs-firmware-efi-vars`
for more information on how to interact with
this structure.

diff --git a/Documentation/ABI/testing/sysfs-firmware-memmap b/Documentation/ABI/testing/sysfs-firmware-memmap
index eca0d65087dc..1f6f4d3a32c0 100644
--- a/Documentation/ABI/testing/sysfs-firmware-memmap
+++ b/Documentation/ABI/testing/sysfs-firmware-memmap
@@ -20,7 +20,7 @@ Description:
the raw memory map to userspace.

The structure is as follows: Under /sys/firmware/memmap there
- are subdirectories with the number of the entry as their name:
+ are subdirectories with the number of the entry as their name::

/sys/firmware/memmap/0
/sys/firmware/memmap/1
@@ -34,14 +34,16 @@ Description:

Each directory contains three files:

- start : The start address (as hexadecimal number with the
+ ======== =====================================================
+ start The start address (as hexadecimal number with the
'0x' prefix).
- end : The end address, inclusive (regardless whether the
+ end The end address, inclusive (regardless whether the
firmware provides inclusive or exclusive ranges).
- type : Type of the entry as string. See below for a list of
+ type Type of the entry as string. See below for a list of
valid types.
+ ======== =====================================================

- So, for example:
+ So, for example::

/sys/firmware/memmap/0/start
/sys/firmware/memmap/0/end
@@ -57,9 +59,8 @@ Description:
- reserved

Following shell snippet can be used to display that memory
- map in a human-readable format:
+ map in a human-readable format::

- -------------------- 8< ----------------------------------------
#!/bin/bash
cd /sys/firmware/memmap
for dir in * ; do
@@ -68,4 +69,3 @@ Description:
type=$(cat $dir/type)
printf "%016x-%016x (%s)\n" $start $[ $end +1] "$type"
done
- -------------------- >8 ----------------------------------------
diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4
index 78604db56279..99e3d92f8299 100644
--- a/Documentation/ABI/testing/sysfs-fs-ext4
+++ b/Documentation/ABI/testing/sysfs-fs-ext4
@@ -45,8 +45,8 @@ Description:
parameter will have their blocks allocated out of a
block group specific preallocation pool, so that small
files are packed closely together. Each large file
- will have its blocks allocated out of its own unique
- preallocation pool.
+ will have its blocks allocated out of its own unique
+ preallocation pool.

What: /sys/fs/ext4/<disk>/inode_readahead_blks
Date: March 2008
diff --git a/Documentation/ABI/testing/sysfs-hypervisor-xen b/Documentation/ABI/testing/sysfs-hypervisor-xen
index 53b7b2ea7515..4dbe0c49b393 100644
--- a/Documentation/ABI/testing/sysfs-hypervisor-xen
+++ b/Documentation/ABI/testing/sysfs-hypervisor-xen
@@ -15,14 +15,17 @@ KernelVersion: 4.3
Contact: Boris Ostrovsky <[email protected]>
Description: If running under Xen:
Describes mode that Xen's performance-monitoring unit (PMU)
- uses. Accepted values are
- "off" -- PMU is disabled
- "self" -- The guest can profile itself
- "hv" -- The guest can profile itself and, if it is
+ uses. Accepted values are:
+
+ ====== ============================================
+ "off" PMU is disabled
+ "self" The guest can profile itself
+ "hv" The guest can profile itself and, if it is
privileged (e.g. dom0), the hypervisor
- "all" -- The guest can profile itself, the hypervisor
+ "all" The guest can profile itself, the hypervisor
and all other guests. Only available to
privileged guests.
+ ====== ============================================

What: /sys/hypervisor/pmu/pmu_features
Date: August 2015
diff --git a/Documentation/ABI/testing/sysfs-kernel-boot_params b/Documentation/ABI/testing/sysfs-kernel-boot_params
index eca38ce2852d..7f9bda453c4d 100644
--- a/Documentation/ABI/testing/sysfs-kernel-boot_params
+++ b/Documentation/ABI/testing/sysfs-kernel-boot_params
@@ -23,16 +23,17 @@ Description: The /sys/kernel/boot_params directory contains two
representation of setup_data type. "data" file is the binary
representation of setup_data payload.

- The whole boot_params directory structure is like below:
- /sys/kernel/boot_params
- |__ data
- |__ setup_data
- | |__ 0
- | | |__ data
- | | |__ type
- | |__ 1
- | |__ data
- | |__ type
- |__ version
+ The whole boot_params directory structure is like below::
+
+ /sys/kernel/boot_params
+ |__ data
+ |__ setup_data
+ | |__ 0
+ | | |__ data
+ | | |__ type
+ | |__ 1
+ | |__ data
+ | |__ type
+ |__ version

Users: Kexec
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
index fdaa2162fae1..294387e2c7fb 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
@@ -7,9 +7,11 @@ Description:
of the hugepages supported by the kernel/CPU combination.

Under these directories are a number of files:
- nr_hugepages
- nr_overcommit_hugepages
- free_hugepages
- surplus_hugepages
- resv_hugepages
+
+ - nr_hugepages
+ - nr_overcommit_hugepages
+ - free_hugepages
+ - surplus_hugepages
+ - resv_hugepages
+
See Documentation/admin-guide/mm/hugetlbpage.rst for details.
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
index 8b0e8205a6a2..c78d358dbdbe 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -4,13 +4,16 @@ KernelVersion: 2.6.20
Contact: "Corentin Chary" <[email protected]>
Description:
This file allows display switching. The value
- is composed by 4 bits and defined as follow:
- 4321
- |||`- LCD
- ||`-- CRT
- |`--- TV
- `---- DVI
- Ex: - 0 (0000b) means no display
+ is composed by 4 bits and defined as follow::
+
+ 4321
+ |||`- LCD
+ ||`-- CRT
+ |`--- TV
+ `---- DVI
+
+ Ex:
+ - 0 (0000b) means no display
- 3 (0011b) CRT+LCD.

What: /sys/devices/platform/asus_laptop/gps
@@ -28,8 +31,10 @@ Contact: "Corentin Chary" <[email protected]>
Description:
Some models like the W1N have a LED display that can be
used to display several items of information.
- To control the LED display, use the following :
+ 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/admin-guide/laptops/asus-laptop.rst

diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi
index 1efac0ddb417..04885738cf15 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-wmi
+++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi
@@ -5,6 +5,7 @@ Contact: "Corentin Chary" <[email protected]>
Description:
Change CPU clock configuration (write-only).
There are three available clock configuration:
+
* 0 -> Super Performance Mode
* 1 -> High Performance Mode
* 2 -> Power Saving Mode
diff --git a/Documentation/ABI/testing/sysfs-platform-at91 b/Documentation/ABI/testing/sysfs-platform-at91
index 4cc6a865ae66..b146be74b8e0 100644
--- a/Documentation/ABI/testing/sysfs-platform-at91
+++ b/Documentation/ABI/testing/sysfs-platform-at91
@@ -18,8 +18,10 @@ Description:
In order to use an extended can_id add the
CAN_EFF_FLAG (0x80000000U) to the can_id. Example:

- - standard id 0x7ff:
- echo 0x7ff > /sys/class/net/can0/mb0_id
+ - standard id 0x7ff::

- - extended id 0x1fffffff:
- echo 0x9fffffff > /sys/class/net/can0/mb0_id
+ echo 0x7ff > /sys/class/net/can0/mb0_id
+
+ - extended id 0x1fffffff::
+
+ echo 0x9fffffff > /sys/class/net/can0/mb0_id
diff --git a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
index 5b026c69587a..70dbe0733cf6 100644
--- a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
@@ -4,9 +4,11 @@ KernelVersion: 2.6.26
Contact: "Corentin Chary" <[email protected]>
Description:
This file allows display switching.
+
- 1 = LCD
- 2 = CRT
- 3 = LCD+CRT
+
If you run X11, you should use xrandr instead.

What: /sys/devices/platform/eeepc/camera
@@ -30,16 +32,20 @@ Contact: "Corentin Chary" <[email protected]>
Description:
Change CPU clock configuration.
On the Eee PC 1000H there are three available clock configuration:
+
* 0 -> Super Performance Mode
* 1 -> High Performance Mode
* 2 -> Power Saving Mode
+
On Eee PC 701 there is only 2 available clock configurations.
Available configuration are listed in available_cpufv file.
Reading this file will show the raw hexadecimal value which
- is defined as follow:
- | 8 bit | 8 bit |
- | `---- Current mode
- `------------ Availables modes
+ is defined as follow::
+
+ | 8 bit | 8 bit |
+ | `---- Current mode
+ `------------ Availables modes
+
For example, 0x301 means: mode 1 selected, 3 available modes.

What: /sys/devices/platform/eeepc/available_cpufv
diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
index 1b31be3f996a..fd2ac02bc5bd 100644
--- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
@@ -12,6 +12,7 @@ Contact: "Maxim Mikityanskiy <[email protected]>"
Description:
Change fan mode
There are four available modes:
+
* 0 -> Super Silent Mode
* 1 -> Standard Mode
* 2 -> Dust Cleaning
@@ -32,9 +33,11 @@ KernelVersion: 4.18
Contact: "Oleg Keri <[email protected]>"
Description:
Control fn-lock mode.
+
* 1 -> Switched On
* 0 -> Switched Off

- For example:
- # echo "0" > \
- /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock
+ For example::
+
+ # echo "0" > \
+ /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
index 8af65059d519..e19144fd5d86 100644
--- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
+++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
@@ -7,5 +7,6 @@ Description:
Thunderbolt controllers to turn on or off when no
devices are connected (write-only)
There are two available states:
+
* 0 -> Force power disabled
* 1 -> Force power enabled
diff --git a/Documentation/ABI/testing/sysfs-platform-sst-atom b/Documentation/ABI/testing/sysfs-platform-sst-atom
index 0d07c0395660..d5f6e21f0e42 100644
--- a/Documentation/ABI/testing/sysfs-platform-sst-atom
+++ b/Documentation/ABI/testing/sysfs-platform-sst-atom
@@ -5,13 +5,22 @@ Contact: "Sebastien Guiriec" <[email protected]>
Description:
LPE Firmware version for SST driver on all atom
plaforms (BYT/CHT/Merrifield/BSW).
- If the FW has never been loaded it will display:
+ If the FW has never been loaded it will display::
+
"FW not yet loaded"
- If FW has been loaded it will display:
+
+ If FW has been loaded it will display::
+
"v01.aa.bb.cc"
+
aa: Major version is reflecting SoC version:
+
+ === =============
0d: BYT FW
0b: BSW FW
07: Merrifield FW
+ === =============
+
bb: Minor version
+
cc: Build version
diff --git a/Documentation/ABI/testing/sysfs-platform-usbip-vudc b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
index 81fcfb454913..53622d3ba27c 100644
--- a/Documentation/ABI/testing/sysfs-platform-usbip-vudc
+++ b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
@@ -16,10 +16,13 @@ Contact: Krzysztof Opasiak <[email protected]>
Description:
Current status of the device.
Allowed values:
- 1 - Device is available and can be exported
- 2 - Device is currently exported
- 3 - Fatal error occurred during communication
- with peer
+
+ == ==========================================
+ 1 Device is available and can be exported
+ 2 Device is currently exported
+ 3 Fatal error occurred during communication
+ with peer
+ == ==========================================

What: /sys/devices/platform/usbip-vudc.%d/usbip_sockfd
Date: April 2016
diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp
index a17f817a9309..2363ad810ddb 100644
--- a/Documentation/ABI/testing/sysfs-ptp
+++ b/Documentation/ABI/testing/sysfs-ptp
@@ -69,7 +69,7 @@ Description:
pin offered by the PTP hardware clock. The file name
is the hardware dependent pin name. Reading from this
file produces two numbers, the assigned function (see
- the PTP_PF_ enumeration values in linux/ptp_clock.h)
+ the `PTP_PF_` enumeration values in linux/ptp_clock.h)
and the channel number. The function and channel
assignment may be changed by two writing numbers into
the file.
diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
index aa39f8d7bcdf..d0893dad3f38 100644
--- a/Documentation/ABI/testing/sysfs-uevent
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -19,7 +19,8 @@ Description:
a transaction identifier so it's possible to use the same UUID
value for one or more synthetic uevents in which case we
logically group these uevents together for any userspace
- listeners. The UUID value appears in uevent as
+ listeners. The UUID value appears in uevent as:
+
"SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" environment
variable.

@@ -30,18 +31,19 @@ Description:
It's possible to define zero or more pairs - each pair is then
delimited by a space character ' '. Each pair appears in
synthetic uevent as "SYNTH_ARG_KEY=VALUE". That means the KEY
- name gains "SYNTH_ARG_" prefix to avoid possible collisions
+ name gains `SYNTH_ARG_` prefix to avoid possible collisions
with existing variables.

- Example of valid sequence written to the uevent file:
+ Example of valid sequence written to the uevent file::

add fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed A=1 B=abc

- This generates synthetic uevent including these variables:
+ This generates synthetic uevent including these variables::

ACTION=add
SYNTH_ARG_A=1
SYNTH_ARG_B=abc
SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed
+
Users:
udev, userspace tools generating synthetic uevents
--
2.26.2

2020-10-29 08:39:49

by Mauro Carvalho Chehab

Subject: [PATCH 07/33] scripts: get_abi.pl: output users in ReST format

Right now, the script only outputs Users on search. Print it
also in ReST format.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/get_abi.pl | 8 ++++++++
1 file changed, 8 insertions(+)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index c88cb8ee6bfd..97a1455789f2 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -371,6 +371,14 @@ sub output_rest {
print "- :ref:`$content <$label>`\n\n";
}
}
+
+ if (defined($data{$what}->{users})) {
+ my $users = $data{$what}->{users};
+
+ $users =~ s/\n/\n\t/g;
+ printf "Users:\n\t%s\n\n", $users if ($users ne "");
+ }
+
}
}

--
2.26.2

2020-10-29 08:39:59

by Mauro Carvalho Chehab

Subject: [PATCH 01/33] scripts: get_abi.pl: change script to allow parsing in ReST mode

From: Mauro Carvalho Chehab <[email protected]>

Right now, several ABI files won't parse as ReST, as they
contain severe violations to the spec, with makes the script
to crash.

So, the code has a sanity logic with escapes bad code and
cleans tags that can cause Sphinx to crash.

Add support for disabling this mode.

Right now, as enabling rst-mode causes crash, it is disabled
by default.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/get_abi.pl | 74 ++++++++++++++++++++++++++++++----------------
1 file changed, 48 insertions(+), 26 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index c738cb795514..107672cdacb3 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -12,8 +12,14 @@ my $man;
my $debug;
my $prefix="Documentation/ABI";

+#
+# If true, assumes that the description is formatted with ReST
+#
+my $description_is_rst = 0;
+
GetOptions(
"debug|d+" => \$debug,
+ "rst-source!" => \$description_is_rst,
"dir=s" => \$prefix,
'help|?' => \$help,
man => \$man
@@ -137,14 +143,15 @@ sub parse_abi {
next;
}
if ($tag eq "description") {
- next if ($content =~ m/^\s*$/);
- if ($content =~ m/^(\s*)(.*)/) {
- my $new_content = $2;
- $space = $new_tag . $sep . $1;
- while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $space =~ s/./ /g;
- $data{$what}->{$tag} .= "$new_content\n";
+ # Preserve initial spaces for the first line
+ $content = ' ' x length($new_tag) . $sep . $content;
+ $content =~ s,^(\s*):,$1 ,;
+ if ($content =~ m/^(\s*)(.*)$/) {
+ $space = $1;
+ $content = $2;
}
+ while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+ $data{$what}->{$tag} .= $content;
} else {
$data{$what}->{$tag} = $content;
}
@@ -160,11 +167,15 @@ sub parse_abi {

if ($tag eq "description") {
if (!$data{$what}->{description}) {
- next if (m/^\s*\n/);
+ s/^($space)//;
if (m/^(\s*)(.*)/) {
- $space = $1;
- while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $data{$what}->{$tag} .= "$2\n";
+ my $sp = $1;
+ while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+ my $content = "$sp$2";
+
+ $content =~ s/^($space)//;
+
+ $data{$what}->{$tag} .= "$content";
}
} else {
my $content = $_;
@@ -274,23 +285,27 @@ sub output_rest {
print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File");

my $desc = $data{$what}->{description};
- $desc =~ s/^\s+//;
-
- # Remove title markups from the description, as they won't work
- $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;

if (!($desc =~ /^\s*$/)) {
- if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
- # put everything inside a code block
- $desc =~ s/\n/\n /g;
-
- print "::\n\n";
- print " $desc\n\n";
- } else {
- # Escape any special chars from description
- $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
-
+ if ($description_is_rst) {
print "$desc\n\n";
+ } else {
+ $desc =~ s/^\s+//;
+
+ # Remove title markups from the description, as they won't work
+ $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
+
+ if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
+ # put everything inside a code block
+ $desc =~ s/\n/\n /g;
+
+ print "::\n\n";
+ print " $desc\n\n";
+ } else {
+ # Escape any special chars from description
+ $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
+ print "$desc\n\n";
+ }
}
} else {
print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
@@ -382,7 +397,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book.

=head1 SYNOPSIS

-B<abi_book.pl> [--debug] [--man] [--help] [--dir=<dir>] <COMAND> [<ARGUMENT>]
+B<abi_book.pl> [--debug] [--man] [--help] --[(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]

Where <COMMAND> can be:

@@ -405,6 +420,13 @@ B<validate> - validate the ABI contents
Changes the location of the ABI search. By default, it uses
the Documentation/ABI directory.

+=item B<--rst-source> and B<--no-rst-source>
+
+The input file may be using ReST syntax or not. Those two options allow
+selecting between a rst-compliant source ABI (--rst-source), or a
+plain text that may be violating ReST spec, so it requres some escaping
+logic (--no-rst-source).
+
=item B<--debug>

Put the script in verbose mode, useful for debugging. Can be called multiple
--
2.26.2

2020-10-29 08:40:42

by Mauro Carvalho Chehab

Subject: [PATCH 18/33] docs: ABI: README: specify that files should be ReST compatible

From: Mauro Carvalho Chehab <[email protected]>

As we plan to remove the escaping code from the scripts/get_abi.pl,
specify at the ABI README file that the content of the file should
be ReST compatible.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/ABI/README | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 3121029dce21..8bac9cb09a6d 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -32,7 +32,7 @@ The different levels of stability are:
layout of the files below for details on how to do this.)

obsolete/
- This directory documents interfaces that are still remaining in
+ This directory documents interfaces that are still remaining in
the kernel, but are marked to be removed at some later point in
time. The description of the interface will document the reason
why it is obsolete and when it can be expected to be removed.
@@ -58,6 +58,14 @@ Users: All users of this interface who wish to be notified when
be changed further.


+Note:
+ The fields should be use a simple notation, compatible with ReST markup.
+ Also, the file **should not** have a top-level index, like::
+
+ ===
+ foo
+ ===
+
How things move between levels:

Interfaces in stable may move to obsolete, as long as the proper
--
2.26.2

2020-10-29 08:40:55

by Mauro Carvalho Chehab

Subject: [PATCH 24/33] docs: abi-testing.rst: enable --rst-sources when building docs

From: Mauro Carvalho Chehab <[email protected]>

Now that ABI/testing documents were fixed, add --rst-sources to
the ABI/testing too.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/abi-testing.rst | 1 +
1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst
index 5c886fc50b9e..b205b16a72d0 100644
--- a/Documentation/admin-guide/abi-testing.rst
+++ b/Documentation/admin-guide/abi-testing.rst
@@ -17,3 +17,4 @@ name to the description of these interfaces, so that the kernel
developers can easily notify them if any changes occur.

.. kernel-abi:: $srctree/Documentation/ABI/testing
+ :rst:
--
2.26.2

2020-10-29 08:41:39

by Mauro Carvalho Chehab

Subject: [PATCH 02/33] scripts: get_abi.pl: fix parsing on ReST mode

From: Mauro Carvalho Chehab <[email protected]>

When the source ABI file is using ReST notation, the script
should handle whitespaces and lines with care, as otherwise
the file won't be properly recognized.

Address the bugs that are on such part of the script.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/get_abi.pl | 30 ++++++++++++++----------------
1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 107672cdacb3..0c403af86fd5 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -151,7 +151,8 @@ sub parse_abi {
$content = $2;
}
while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $data{$what}->{$tag} .= $content;
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
$data{$what}->{$tag} = $content;
}
@@ -166,31 +167,28 @@ sub parse_abi {
}

if ($tag eq "description") {
+ my $content = $_;
+ while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
if (!$data{$what}->{description}) {
- s/^($space)//;
- if (m/^(\s*)(.*)/) {
- my $sp = $1;
- while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- my $content = "$sp$2";
-
- $content =~ s/^($space)//;
-
- $data{$what}->{$tag} .= "$content";
+ # Preserve initial spaces for the first line
+ if ($content =~ m/^(\s*)(.*)$/) {
+ $space = $1;
+ $content = $2;
}
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
- my $content = $_;
if (m/^\s*\n/) {
$data{$what}->{$tag} .= $content;
next;
}

- while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
$space = "" if (!($content =~ s/^($space)//));

- # Compress spaces with tabs
- $content =~ s<^ {8}> <\t>;
- $content =~ s<^ {1,7}\t> <\t>;
- $content =~ s< {1,7}\t> <\t>;
+# # Compress spaces with tabs
+# $content =~ s<^ {8}> <\t>;
+# $content =~ s<^ {1,7}\t> <\t>;
+# $content =~ s< {1,7}\t> <\t>;
$data{$what}->{$tag} .= $content;
}
next;
--
2.26.2

2020-10-29 08:42:15

by Greg Kroah-Hartman

Subject: Re: [PATCH 00/33] ABI: add it to the documentation build system

On Wed, Oct 28, 2020 at 03:22:58PM +0100, Mauro Carvalho Chehab wrote:
> Hi Greg,
>
> As requested, this is a rebased version on the top of v5.10-rc1
> adding support for having the Linux ABI documentted inside
> the Linux admin manual.
>
> When compared with the version I sent years ago, this
> version has:
>
> - a logic to detect duplicated ABI symbols;
> - it auto-generate cross-reference markups for ABI symbols,
> ABI files and .rst files;
> - Other files from 5.10-rc1 required adjustments in order
> to be accepted by the script in rst-source mode;
> - Some bug fixes.
>
> PS.: I didn't try to merge it against linux-next yet. So,
> I won't doubt that applying it could cause some conflicts.
>
> Feel free to review it.

In general, I like it.

If there's no complaints, I'd like to take all of the Documentation/ABI/
updates in for 5.10-rc2 at the least, to make it easier to build on top
of and to keep these types of mistakes from living longer than they
should be. And make merging easier with other trees over time.

thanks,

greg k-h

2020-10-29 08:42:27

by Mauro Carvalho Chehab

Subject: [PATCH 21/33] docs: ABI: make it parse ABI/stable as ReST-compatible files

From: Mauro Carvalho Chehab <[email protected]>

Now that the stable ABI files are compatible with ReST,
parse them without converting complex descriptions as literal
blocks nor escaping special characters.

Please notice that escaping special characters will probably
be needed at descriptions, at least for the asterisk character.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/abi-stable.rst | 1 +
Documentation/sphinx/kernel_abi.py | 8 ++++++--
2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst
index 7495d7a35048..70490736e0d3 100644
--- a/Documentation/admin-guide/abi-stable.rst
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -11,3 +11,4 @@ Most interfaces (like syscalls) are expected to never change and always
be available.

.. kernel-abi:: $srctree/Documentation/ABI/stable
+ :rst:
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index ce5f3b0ae811..f3da859c9878 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -73,12 +73,13 @@ class KernelCmd(Directive):
u"""KernelABI (``kernel-abi``) directive"""

required_arguments = 1
- optional_arguments = 0
+ optional_arguments = 2
has_content = False
final_argument_whitespace = True

option_spec = {
- "debug" : directives.flag
+ "debug" : directives.flag,
+ "rst" : directives.unchanged
}

def run(self):
@@ -92,6 +93,9 @@ class KernelCmd(Directive):
cmd = "get_abi.pl rest --enable-lineno --dir "
cmd += self.arguments[0]

+ if 'rst' in self.options:
+ cmd += " --rst-source"
+
srctree = path.abspath(os.environ["srctree"])

fname = cmd
--
2.26.2

2020-10-29 08:42:43

by Mauro Carvalho Chehab

Subject: Re: [PATCH 00/33] ABI: add it to the documentation build system

Em Wed, 28 Oct 2020 15:39:37 +0100
Greg Kroah-Hartman <[email protected]> escreveu:

> On Wed, Oct 28, 2020 at 03:22:58PM +0100, Mauro Carvalho Chehab wrote:
> > Hi Greg,
> >
> > As requested, this is a rebased version on the top of v5.10-rc1
> > adding support for having the Linux ABI documentted inside
> > the Linux admin manual.
> >
> > When compared with the version I sent years ago, this
> > version has:
> >
> > - a logic to detect duplicated ABI symbols;
> > - it auto-generate cross-reference markups for ABI symbols,
> > ABI files and .rst files;
> > - Other files from 5.10-rc1 required adjustments in order
> > to be accepted by the script in rst-source mode;
> > - Some bug fixes.
> >
> > PS.: I didn't try to merge it against linux-next yet. So,
> > I won't doubt that applying it could cause some conflicts.
> >
> > Feel free to review it.
>
> After applying the first 10 patches, and running it, I see a bunch of
> these types of warnings:
>
> Use of uninitialized value $kernelversion in substitution (s///) at ./scripts/get_abi.pl line 444.
> Use of uninitialized value $users in substitution (s///) at ./scripts/get_abi.pl line 446.
> Use of uninitialized value $users in substitution (s///) at ./scripts/get_abi.pl line 447.

Hmm.. I didn't test search after adding "use warnings".

The thing is that "use warnings" was added on one of get_abi.pl
patches, just to be sure that some ABI parsers were 100%.

That makes perl very pedantic, as it won't accept things like:

my $foo;
...
my $bar = $foo;

Without "warnings", $bar will be undefined, and everything
works properly, but, when this used, the above will still
work properly, but will start producing warnings like the
one you're seeing.

I'm enclosing a diff addressing it for "search" mode.

It should be fold on this patch:

scripts: get_abi.pl: cleanup ABI cross-reference logic

Which is the one that added "use warnings".

Feel free to fold it there. Otherwise, I'll fold it and
send you on a v2 of this series.

>
> When doing something like:
> $ ./scripts/get_abi.pl search usb --dir Documentation/ABI/stable/
>
> Is that expected?
>
> thanks,
>
> greg k-h


Thanks,
Mauro

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index bdef3e5c35c7..00b6ddec0ebb 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -442,17 +442,20 @@ sub search_symbols {

print "\n$what\n$bar\n\n";

- my $kernelversion = $data{$what}->{kernelversion};
- my $contact = $data{$what}->{contact};
- my $users = $data{$what}->{users};
- my $date = $data{$what}->{date};
- my $desc = $data{$what}->{description};
- $kernelversion =~ s/^\s+//;
- $contact =~ s/^\s+//;
- $users =~ s/^\s+//;
- $users =~ s/\n//g;
- $date =~ s/^\s+//;
- $desc =~ s/^\s+//;
+ my $kernelversion = $data{$what}->{kernelversion} if (defined($data{$what}->{kernelversion}));
+ my $contact = $data{$what}->{contact} if (defined($data{$what}->{contact}));
+ my $users = $data{$what}->{users} if (defined($data{$what}->{users}));
+ my $date = $data{$what}->{date} if (defined($data{$what}->{date}));
+ my $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
+
+ $kernelversion =~ s/^\s+// if ($kernelversion);
+ $contact =~ s/^\s+// if ($contact);
+ if ($users) {
+ $users =~ s/^\s+//;
+ $users =~ s/\n//g;
+ }
+ $date =~ s/^\s+// if ($date);
+ $desc =~ s/^\s+// if ($desc);

printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion);
printf "Date:\t\t\t%s\n", $date if ($date);

2020-10-29 08:43:10

by Mauro Carvalho Chehab

Subject: [PATCH 31/33] docs: ABI: change read/write attributes

Unfortunately, (R) and (W) are valid markups for enumerated
lists, as described at:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists

So, we ned to replace them by:

(R) -> (Read)
(W) -> (Write)

As otherwise, (R) will be displayed as R., with is not what
it is desired.

There's no need to touch (RO) and (RW).

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/ABI/testing/debugfs-moxtet | 2 +-
.../ABI/testing/debugfs-turris-mox-rwtm | 15 ++--
.../testing/sysfs-bus-coresight-devices-cti | 60 +++++++--------
.../testing/sysfs-bus-coresight-devices-etb10 | 16 ++--
.../testing/sysfs-bus-coresight-devices-etm3x | 10 +--
.../testing/sysfs-bus-coresight-devices-etm4x | 76 +++++++++----------
.../testing/sysfs-bus-coresight-devices-stm | 2 +-
.../testing/sysfs-bus-coresight-devices-tmc | 20 ++---
.../ABI/testing/sysfs-bus-moxtet-devices | 6 +-
.../testing/sysfs-firmware-turris-mox-rwtm | 10 +--
10 files changed, 109 insertions(+), 108 deletions(-)

diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
index 15dfaecb2892..6eee10c3d5a1 100644
--- a/Documentation/ABI/testing/debugfs-moxtet
+++ b/Documentation/ABI/testing/debugfs-moxtet
@@ -2,7 +2,7 @@ What: /sys/kernel/debug/moxtet/input
Date: March 2019
KernelVersion: 5.3
Contact: Marek Behún <[email protected]>
-Description: (R) Read input from the shift registers, in hexadecimal.
+Description: (Read) Read input from the shift registers, in hexadecimal.
Returns N+1 bytes, where N is the number of Moxtet connected
modules. The first byte is from the CPU board itself.

diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
index ad08f535af3b..326df1b74707 100644
--- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
+++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
@@ -4,10 +4,11 @@ KernelVersion: 5.8
Contact: Marek Behún <[email protected]>
Description:

- === ===========================================================
- (W) Message to sign with the ECDSA private key stored in
- device's OTP. The message must be exactly 64 bytes (since
- this is intended for SHA-512 hashes).
- (R) The resulting signature, 136 bytes. This contains the R and
- S values of the ECDSA signature, both in big-endian format.
- === ===========================================================
+ ======= ===========================================================
+ (Write) Message to sign with the ECDSA private key stored in
+ device's OTP. The message must be exactly 64 bytes
+ (since this is intended for SHA-512 hashes).
+ (Read) The resulting signature, 136 bytes. This contains the
+ R and S values of the ECDSA signature, both in
+ big-endian format.
+ ======= ===========================================================
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
index 9d11502b4390..bf2869c413e7 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
@@ -8,50 +8,50 @@ What: /sys/bus/coresight/devices/<cti-name>/powered
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Indicate if the CTI hardware is powered.
+Description: (Read) Indicate if the CTI hardware is powered.

What: /sys/bus/coresight/devices/<cti-name>/ctmid
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Display the associated CTM ID
+Description: (Read) Display the associated CTM ID

What: /sys/bus/coresight/devices/<cti-name>/nr_trigger_cons
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Number of devices connected to triggers on this CTI
+Description: (Read) Number of devices connected to triggers on this CTI

What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/name
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Name of connected device <N>
+Description: (Read) Name of connected device <N>

What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/in_signals
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Input trigger signals from connected device <N>
+Description: (Read) Input trigger signals from connected device <N>

What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/in_types
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Functional types for the input trigger signals
+Description: (Read) Functional types for the input trigger signals
from connected device <N>

What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/out_signals
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Output trigger signals to connected device <N>
+Description: (Read) Output trigger signals to connected device <N>

What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/out_types
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Functional types for the output trigger signals
+Description: (Read) Functional types for the output trigger signals
to connected device <N>

What: /sys/bus/coresight/devices/<cti-name>/regs/inout_sel
@@ -88,7 +88,7 @@ What: /sys/bus/coresight/devices/<cti-name>/regs/intack
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Write the INTACK register.
+Description: (Write) Write the INTACK register.

What: /sys/bus/coresight/devices/<cti-name>/regs/appset
Date: March 2020
@@ -101,99 +101,99 @@ What: /sys/bus/coresight/devices/<cti-name>/regs/appclear
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Write APPCLEAR register to deactivate channel.
+Description: (Write) Write APPCLEAR register to deactivate channel.

What: /sys/bus/coresight/devices/<cti-name>/regs/apppulse
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Write APPPULSE to pulse a channel active for one clock
+Description: (Write) Write APPPULSE to pulse a channel active for one clock
cycle.

What: /sys/bus/coresight/devices/<cti-name>/regs/chinstatus
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Read current status of channel inputs.
+Description: (Read) Read current status of channel inputs.

What: /sys/bus/coresight/devices/<cti-name>/regs/choutstatus
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) read current status of channel outputs.
+Description: (Read) read current status of channel outputs.

What: /sys/bus/coresight/devices/<cti-name>/regs/triginstatus
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) read current status of input trigger signals
+Description: (Read) read current status of input trigger signals

What: /sys/bus/coresight/devices/<cti-name>/regs/trigoutstatus
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) read current status of output trigger signals.
+Description: (Read) read current status of output trigger signals.

What: /sys/bus/coresight/devices/<cti-name>/channels/trigin_attach
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Attach a CTI input trigger to a CTM channel.
+Description: (Write) Attach a CTI input trigger to a CTM channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/trigin_detach
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Detach a CTI input trigger from a CTM channel.
+Description: (Write) Detach a CTI input trigger from a CTM channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_attach
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Attach a CTI output trigger to a CTM channel.
+Description: (Write) Attach a CTI output trigger to a CTM channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_detach
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Detach a CTI output trigger from a CTM channel.
+Description: (Write) Detach a CTI output trigger from a CTM channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_gate_enable
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (RW) Enable CTIGATE for single channel (W) or list enabled
+Description: (RW) Enable CTIGATE for single channel (Write) or list enabled
channels through the gate (R).

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_gate_disable
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Disable CTIGATE for single channel.
+Description: (Write) Disable CTIGATE for single channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_set
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Activate a single channel.
+Description: (Write) Activate a single channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_clear
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Deactivate a single channel.
+Description: (Write) Deactivate a single channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_pulse
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Pulse a single channel - activate for a single clock cycle.
+Description: (Write) Pulse a single channel - activate for a single clock cycle.

What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_filtered
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) List of output triggers filtered across all connections.
+Description: (Read) List of output triggers filtered across all connections.

What: /sys/bus/coresight/devices/<cti-name>/channels/trig_filter_enable
Date: March 2020
@@ -205,13 +205,13 @@ What: /sys/bus/coresight/devices/<cti-name>/channels/chan_inuse
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) show channels with at least one attached trigger signal.
+Description: (Read) show channels with at least one attached trigger signal.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_free
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) show channels with no attached trigger signals.
+Description: (Read) show channels with no attached trigger signals.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_sel
Date: March 2020
@@ -224,18 +224,18 @@ What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_in
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Read to see input triggers connected to selected view
+Description: (Read) Read to see input triggers connected to selected view
channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_out
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (R) Read to see output triggers connected to selected view
+Description: (Read) Read to see output triggers connected to selected view
channel.

What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_reset
Date: March 2020
KernelVersion 5.7
Contact: Mike Leach or Mathieu Poirier
-Description: (W) Clear all channel / trigger programming.
+Description: (Write) Clear all channel / trigger programming.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
index 3e92cbd3fd83..9a383f6a74eb 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
@@ -23,21 +23,21 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rdp
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Defines the depth, in words, of the trace RAM in powers of
+Description: (Read) Defines the depth, in words, of the trace RAM in powers of
2. The value is read directly from HW register RDP, 0x004.

What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/sts
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the ETB status register. The value
+Description: (Read) Shows the value held by the ETB status register. The value
is read directly from HW register STS, 0x00C.

What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rrp
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the ETB RAM Read Pointer register
+Description: (Read) Shows the value held by the ETB RAM Read Pointer register
that is used to read entries from the Trace RAM over the APB
interface. The value is read directly from HW register RRP,
0x014.
@@ -46,7 +46,7 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rwp
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the ETB RAM Write Pointer register
+Description: (Read) Shows the value held by the ETB RAM Write Pointer register
that is used to sets the write pointer to write entries from
the CoreSight bus into the Trace RAM. The value is read directly
from HW register RWP, 0x018.
@@ -55,21 +55,21 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/trg
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Similar to "trigger_cntr" above except that this value is
+Description: (Read) Similar to "trigger_cntr" above except that this value is
read directly from HW register TRG, 0x01C.

What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ctl
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the ETB Control register. The value
+Description: (Read) Shows the value held by the ETB Control register. The value
is read directly from HW register CTL, 0x020.

What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffsr
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the ETB Formatter and Flush Status
+Description: (Read) Shows the value held by the ETB Formatter and Flush Status
register. The value is read directly from HW register FFSR,
0x300.

@@ -77,6 +77,6 @@ What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffcr
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the ETB Formatter and Flush Control
+Description: (Read) Shows the value held by the ETB Formatter and Flush Control
register. The value is read directly from HW register FFCR,
0x304.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
index 924265a1295d..651602a61eac 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
@@ -146,28 +146,28 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_addr_cmp
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Provides the number of address comparators pairs accessible
+Description: (Read) Provides the number of address comparators pairs accessible
on a trace unit, as specified by bit 3:0 of register ETMCCR.

What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_cntr
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Provides the number of counters accessible on a trace unit,
+Description: (Read) Provides the number of counters accessible on a trace unit,
as specified by bit 15:13 of register ETMCCR.

What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_ctxid_cmp
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Provides the number of context ID comparator available on a
+Description: (Read) Provides the number of context ID comparator available on a
trace unit, as specified by bit 25:24 of register ETMCCR.

What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/reset
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <[email protected]>
-Description: (W) Cancels all configuration on a trace unit and set it back
+Description: (Write) Cancels all configuration on a trace unit and set it back
to its boot configuration.

What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_12_event
@@ -216,7 +216,7 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/curr_seq_state
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Holds the current state of the sequencer.
+Description: (Read) Holds the current state of the sequencer.

What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/sync_freq
Date: November 2014
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
index 614874e2cf53..881f0cd99ce4 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
@@ -12,75 +12,75 @@ What: /sys/bus/coresight/devices/etm<N>/cpu
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) The CPU this tracing entity is associated with.
+Description: (Read) The CPU this tracing entity is associated with.

What: /sys/bus/coresight/devices/etm<N>/nr_pe_cmp
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of PE comparator inputs that are
+Description: (Read) Indicates the number of PE comparator inputs that are
available for tracing.

What: /sys/bus/coresight/devices/etm<N>/nr_addr_cmp
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of address comparator pairs that are
+Description: (Read) Indicates the number of address comparator pairs that are
available for tracing.

What: /sys/bus/coresight/devices/etm<N>/nr_cntr
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of counters that are available for
+Description: (Read) Indicates the number of counters that are available for
tracing.

What: /sys/bus/coresight/devices/etm<N>/nr_ext_inp
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates how many external inputs are implemented.
+Description: (Read) Indicates how many external inputs are implemented.

What: /sys/bus/coresight/devices/etm<N>/numcidc
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of Context ID comparators that are
+Description: (Read) Indicates the number of Context ID comparators that are
available for tracing.

What: /sys/bus/coresight/devices/etm<N>/numvmidc
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of VMID comparators that are available
+Description: (Read) Indicates the number of VMID comparators that are available
for tracing.

What: /sys/bus/coresight/devices/etm<N>/nrseqstate
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of sequencer states that are
+Description: (Read) Indicates the number of sequencer states that are
implemented.

What: /sys/bus/coresight/devices/etm<N>/nr_resource
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of resource selection pairs that are
+Description: (Read) Indicates the number of resource selection pairs that are
available for tracing.

What: /sys/bus/coresight/devices/etm<N>/nr_ss_cmp
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the number of single-shot comparator controls that
+Description: (Read) Indicates the number of single-shot comparator controls that
are available for tracing.

What: /sys/bus/coresight/devices/etm<N>/reset
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (W) Cancels all configuration on a trace unit and set it back
+Description: (Write) Cancels all configuration on a trace unit and set it back
to its boot configuration.

What: /sys/bus/coresight/devices/etm<N>/mode
@@ -300,7 +300,7 @@ What: /sys/bus/coresight/devices/etm<N>/addr_cmp_view
Date: December 2019
KernelVersion: 5.5
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the current settings for the selected address
+Description: (Read) Print the current settings for the selected address
comparator.

What: /sys/bus/coresight/devices/etm<N>/sshot_idx
@@ -319,7 +319,7 @@ What: /sys/bus/coresight/devices/etm<N>/sshot_status
Date: December 2019
KernelVersion: 5.5
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the current value of the selected single shot
+Description: (Read) Print the current value of the selected single shot
status register.

What: /sys/bus/coresight/devices/etm<N>/sshot_pe_ctrl
@@ -333,111 +333,111 @@ What: /sys/bus/coresight/devices/etm<N>/mgmt/trcoslsr
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the OS Lock Status Register (0x304).
+Description: (Read) Print the content of the OS Lock Status Register (0x304).
The value it taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpdcr
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Power Down Control Register
+Description: (Read) Print the content of the Power Down Control Register
(0x310). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpdsr
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Power Down Status Register
+Description: (Read) Print the content of the Power Down Status Register
(0x314). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trclsr
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the SW Lock Status Register
+Description: (Read) Print the content of the SW Lock Status Register
(0xFB4). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcauthstatus
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Authentication Status Register
+Description: (Read) Print the content of the Authentication Status Register
(0xFB8). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcdevid
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Device ID Register
+Description: (Read) Print the content of the Device ID Register
(0xFC8). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcdevtype
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Device Type Register
+Description: (Read) Print the content of the Device Type Register
(0xFCC). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr0
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Peripheral ID0 Register
+Description: (Read) Print the content of the Peripheral ID0 Register
(0xFE0). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr1
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Peripheral ID1 Register
+Description: (Read) Print the content of the Peripheral ID1 Register
(0xFE4). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr2
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Peripheral ID2 Register
+Description: (Read) Print the content of the Peripheral ID2 Register
(0xFE8). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr3
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the Peripheral ID3 Register
+Description: (Read) Print the content of the Peripheral ID3 Register
(0xFEC). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trcconfig
Date: February 2016
KernelVersion: 4.07
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the trace configuration register
+Description: (Read) Print the content of the trace configuration register
(0x010) as currently set by SW.

What: /sys/bus/coresight/devices/etm<N>/mgmt/trctraceid
Date: February 2016
KernelVersion: 4.07
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Print the content of the trace ID register (0x040).
+Description: (Read) Print the content of the trace ID register (0x040).

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr0
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the tracing capabilities of the trace unit (0x1E0).
+Description: (Read) Returns the tracing capabilities of the trace unit (0x1E0).
The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr1
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the tracing capabilities of the trace unit (0x1E4).
+Description: (Read) Returns the tracing capabilities of the trace unit (0x1E4).
The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr2
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the maximum size of the data value, data address,
+Description: (Read) Returns the maximum size of the data value, data address,
VMID, context ID and instuction address in the trace unit
(0x1E8). The value is taken directly from the HW.

@@ -445,7 +445,7 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr3
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the value associated with various resources
+Description: (Read) Returns the value associated with various resources
available to the trace unit. See the Trace Macrocell
architecture specification for more details (0x1E8).
The value is taken directly from the HW.
@@ -454,42 +454,42 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr4
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns how many resources the trace unit supports (0x1F0).
+Description: (Read) Returns how many resources the trace unit supports (0x1F0).
The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr5
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns how many resources the trace unit supports (0x1F4).
+Description: (Read) Returns how many resources the trace unit supports (0x1F4).
The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr8
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the maximum speculation depth of the instruction
+Description: (Read) Returns the maximum speculation depth of the instruction
trace stream. (0x180). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr9
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the number of P0 right-hand keys that the trace unit
+Description: (Read) Returns the number of P0 right-hand keys that the trace unit
can use (0x184). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr10
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the number of P1 right-hand keys that the trace unit
+Description: (Read) Returns the number of P1 right-hand keys that the trace unit
can use (0x188). The value is taken directly from the HW.

What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr11
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the number of special P1 right-hand keys that the
+Description: (Read) Returns the number of special P1 right-hand keys that the
trace unit can use (0x18C). The value is taken directly from
the HW.

@@ -497,7 +497,7 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr12
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the number of conditional P1 right-hand keys that
+Description: (Read) Returns the number of conditional P1 right-hand keys that
the trace unit can use (0x190). The value is taken directly
from the HW.

@@ -505,6 +505,6 @@ What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr13
Date: April 2015
KernelVersion: 4.01
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Returns the number of special conditional P1 right-hand keys
+Description: (Read) Returns the number of special conditional P1 right-hand keys
that the trace unit can use (0x194). The value is taken
directly from the HW.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
index 1dffabe7f48d..53e1f4815d64 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
@@ -42,7 +42,7 @@ What: /sys/bus/coresight/devices/<memory_map>.stm/status
Date: April 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) List various control and status registers. The specific
+Description: (Read) List various control and status registers. The specific
layout and content is driver specific.

What: /sys/bus/coresight/devices/<memory_map>.stm/traceid
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
index ab49b9ac3bcb..6aa527296c71 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
@@ -11,21 +11,21 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rsz
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Defines the size, in 32-bit words, of the local RAM buffer.
+Description: (Read) Defines the size, in 32-bit words, of the local RAM buffer.
The value is read directly from HW register RSZ, 0x004.

What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/sts
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the TMC status register. The value
+Description: (Read) Shows the value held by the TMC status register. The value
is read directly from HW register STS, 0x00C.

What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rrp
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the TMC RAM Read Pointer register
+Description: (Read) Shows the value held by the TMC RAM Read Pointer register
that is used to read entries from the Trace RAM over the APB
interface. The value is read directly from HW register RRP,
0x014.
@@ -34,7 +34,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rwp
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the TMC RAM Write Pointer register
+Description: (Read) Shows the value held by the TMC RAM Write Pointer register
that is used to sets the write pointer to write entries from
the CoreSight bus into the Trace RAM. The value is read directly
from HW register RWP, 0x018.
@@ -43,21 +43,21 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/trg
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Similar to "trigger_cntr" above except that this value is
+Description: (Read) Similar to "trigger_cntr" above except that this value is
read directly from HW register TRG, 0x01C.

What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ctl
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the TMC Control register. The value
+Description: (Read) Shows the value held by the TMC Control register. The value
is read directly from HW register CTL, 0x020.

What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffsr
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the TMC Formatter and Flush Status
+Description: (Read) Shows the value held by the TMC Formatter and Flush Status
register. The value is read directly from HW register FFSR,
0x300.

@@ -65,7 +65,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffcr
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the TMC Formatter and Flush Control
+Description: (Read) Shows the value held by the TMC Formatter and Flush Control
register. The value is read directly from HW register FFCR,
0x304.

@@ -73,7 +73,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/mode
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Shows the value held by the TMC Mode register, which
+Description: (Read) Shows the value held by the TMC Mode register, which
indicate the mode the device has been configured to enact. The
The value is read directly from the MODE register, 0x028.

@@ -81,7 +81,7 @@ What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/devid
Date: March 2016
KernelVersion: 4.7
Contact: Mathieu Poirier <[email protected]>
-Description: (R) Indicates the capabilities of the Coresight TMC.
+Description: (Read) Indicates the capabilities of the Coresight TMC.
The value is read directly from the DEVID register, 0xFC8,

What: /sys/bus/coresight/devices/<memory_map>.tmc/buffer_size
diff --git a/Documentation/ABI/testing/sysfs-bus-moxtet-devices b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
index 355958527fa3..4a6d61b44f3f 100644
--- a/Documentation/ABI/testing/sysfs-bus-moxtet-devices
+++ b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
@@ -2,16 +2,16 @@ What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_description
Date: March 2019
KernelVersion: 5.3
Contact: Marek Behún <[email protected]>
-Description: (R) Moxtet module description. Format: string
+Description: (Read) Moxtet module description. Format: string

What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_id
Date: March 2019
KernelVersion: 5.3
Contact: Marek Behún <[email protected]>
-Description: (R) Moxtet module ID. Format: %x
+Description: (Read) Moxtet module ID. Format: %x

What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_name
Date: March 2019
KernelVersion: 5.3
Contact: Marek Behún <[email protected]>
-Description: (R) Moxtet module name. Format: string
+Description: (Read) Moxtet module name. Format: string
diff --git a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
index 15595fab88d1..b8631f5a29c4 100644
--- a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
+++ b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
@@ -2,21 +2,21 @@ What: /sys/firmware/turris-mox-rwtm/board_version
Date: August 2019
KernelVersion: 5.4
Contact: Marek Behún <[email protected]>
-Description: (R) Board version burned into eFuses of this Turris Mox board.
+Description: (Read) Board version burned into eFuses of this Turris Mox board.
Format: %i

What: /sys/firmware/turris-mox-rwtm/mac_address*
Date: August 2019
KernelVersion: 5.4
Contact: Marek Behún <[email protected]>
-Description: (R) MAC addresses burned into eFuses of this Turris Mox board.
+Description: (Read) MAC addresses burned into eFuses of this Turris Mox board.
Format: %pM

What: /sys/firmware/turris-mox-rwtm/pubkey
Date: August 2019
KernelVersion: 5.4
Contact: Marek Behún <[email protected]>
-Description: (R) ECDSA public key (in pubkey hex compressed form) computed
+Description: (Read) ECDSA public key (in pubkey hex compressed form) computed
as pair to the ECDSA private key burned into eFuses of this
Turris Mox Board.
Format: string
@@ -25,7 +25,7 @@ What: /sys/firmware/turris-mox-rwtm/ram_size
Date: August 2019
KernelVersion: 5.4
Contact: Marek Behún <[email protected]>
-Description: (R) RAM size in MiB of this Turris Mox board as was detected
+Description: (Read) RAM size in MiB of this Turris Mox board as was detected
during manufacturing and burned into eFuses. Can be 512 or 1024.
Format: %i

@@ -33,5 +33,5 @@ What: /sys/firmware/turris-mox-rwtm/serial_number
Date: August 2019
KernelVersion: 5.4
Contact: Marek Behún <[email protected]>
-Description: (R) Serial number burned into eFuses of this Turris Mox device.
+Description: (Read) Serial number burned into eFuses of this Turris Mox device.
Format: %016X
--
2.26.2

2020-10-29 08:43:36

by Mauro Carvalho Chehab

Subject: [PATCH 16/33] docs: kernel_abi.py: Handle with a lazy Sphinx parser

From: Mauro Carvalho Chehab <[email protected]>

The Sphinx docutils parser is lazy: if the content is bigger than
a certain number of lines, it silenlty stops parsing it,
producing an incomplete content. This seems to be worse on newer
Sphinx versions, like 2.0.

So, change the logic to parse the contents per input file.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/sphinx/kernel_abi.py | 39 ++++++++++++++++++++----------
1 file changed, 26 insertions(+), 13 deletions(-)

diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 096dec482e96..ce5f3b0ae811 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -37,6 +37,7 @@ import os
import subprocess
import sys
import re
+import kernellog

from os import path

@@ -80,12 +81,6 @@ class KernelCmd(Directive):
"debug" : directives.flag
}

- def warn(self, message, **replace):
- replace["fname"] = self.state.document.current_source
- replace["line_no"] = replace.get("line_no", self.lineno)
- message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
- self.state.document.settings.env.app.warn(message, prefix="")
-
def run(self):

doc = self.state.document
@@ -111,7 +106,7 @@ class KernelCmd(Directive):
shell_env["srctree"] = srctree

lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
- nodeList = self.nestedParse(lines, fname)
+ nodeList = self.nestedParse(lines, self.arguments[0])
return nodeList

def runCmd(self, cmd, **kwargs):
@@ -138,9 +133,9 @@ class KernelCmd(Directive):
% (self.name, ErrorString(exc)))
return out

- def nestedParse(self, lines, f):
+ def nestedParse(self, lines, fname):
content = ViewList()
- node = nodes.section()
+ node = nodes.section()

if "debug" in self.options:
code_block = "\n\n.. code-block:: rst\n :linenos:\n"
@@ -150,22 +145,42 @@ class KernelCmd(Directive):

line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$")
ln = 0
+ n = 0
+ f = fname

for line in lines.split("\n"):
+ n = n + 1
match = line_regex.search(line)
if match:
- f = match.group(1)
+ new_f = match.group(1)
+
+ # Sphinx parser is lazy: it stops parsing contents in the
+ # middle, if it is too big. So, handle it per input file
+ if new_f != f and content:
+ self.do_parse(content, node)
+ content = ViewList()
+
+ f = new_f
+
# sphinx counts lines from 0
ln = int(match.group(2)) - 1
else:
content.append(line, f, ln)

- buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ kernellog.info(self.state.document.settings.env.app, "%s: parsed %i lines" % (fname, n))

+ if content:
+ self.do_parse(content, node)
+
+ return node.children
+
+ def do_parse(self, content, node):
if Use_SSI:
with switch_source_input(self.state, content):
self.state.nested_parse(content, 0, node, match_titles=1)
else:
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+
self.state.memo.title_styles = []
self.state.memo.section_level = 0
self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
@@ -173,5 +188,3 @@ class KernelCmd(Directive):
self.state.nested_parse(content, 0, node, match_titles=1)
finally:
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
-
- return node.children
--
2.26.2

2020-10-29 08:44:47

by Mauro Carvalho Chehab

Subject: [PATCH 33/33] docs: ABI: unify /sys/class/leds/<led>/max_brightness documentation

This ABI is defined twice, one for normal leds and another
one for multicolor ones.

Ensure that just one definition is there at ABI.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/ABI/testing/sysfs-class-led | 25 ++++++++++++++++---
.../ABI/testing/sysfs-class-led-multicolor | 23 +++++------------
2 files changed, 28 insertions(+), 20 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index 0ed5c2629c6f..2e24ac3bd7ef 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -3,9 +3,26 @@ Date: March 2006
KernelVersion: 2.6.17
Contact: Richard Purdie <[email protected]>
Description:
- Set the brightness of the LED. Most LEDs don't
- have hardware brightness support, so will just be turned on for
- non-zero brightness settings. The value is between 0 and
+ Set the brightness of the LED.
+
+ Most LEDs don't have hardware brightness support, so will
+ just be turned on for non-zero brightness settings.
+
+ .. Note::
+
+ For multicolor LEDs, writing to this file will update all
+ LEDs within the group to a calculated percentage of what
+ each color LED intensity is set to.
+
+ The percentage is calculated for each grouped LED via
+ the equation below::
+
+ led_brightness = brightness * multi_intensity/max_brightness
+
+ For additional details please refer to
+ Documentation/leds/leds-class-multicolor.rst.
+
+ The value is between 0 and
/sys/class/leds/<led>/max_brightness.

Writing 0 to this file clears active trigger.
@@ -13,6 +30,8 @@ Description:
Writing non-zero to this file while trigger is active changes the
top brightness trigger is going to use.

+
+
What: /sys/class/leds/<led>/max_brightness
Date: March 2006
KernelVersion: 2.6.17
diff --git a/Documentation/ABI/testing/sysfs-class-led-multicolor b/Documentation/ABI/testing/sysfs-class-led-multicolor
index eeeddcbdbbe3..16fc827b10cb 100644
--- a/Documentation/ABI/testing/sysfs-class-led-multicolor
+++ b/Documentation/ABI/testing/sysfs-class-led-multicolor
@@ -1,20 +1,3 @@
-What: /sys/class/leds/<led>/brightness
-Date: March 2020
-KernelVersion: 5.9
-Contact: Dan Murphy <[email protected]>
-Description: read/write
- Writing to this file will update all LEDs within the group to a
- calculated percentage of what each color LED intensity is set
- to. The percentage is calculated for each grouped LED via the
- equation below:
-
- led_brightness = brightness * multi_intensity/max_brightness
-
- For additional details please refer to
- Documentation/leds/leds-class-multicolor.rst.
-
- The value of the LED is from 0 to
- /sys/class/leds/<led>/max_brightness.

What: /sys/class/leds/<led>/multi_index
Date: March 2020
@@ -25,6 +8,9 @@ Description: read
as an array of strings as they are indexed in the
multi_intensity file.

+ For additional details please refer to
+ Documentation/leds/leds-class-multicolor.rst.
+
What: /sys/class/leds/<led>/multi_intensity
Date: March 2020
KernelVersion: 5.9
@@ -33,3 +19,6 @@ Description: read/write
This file contains array of integers. Order of components is
described by the multi_index array. The maximum intensity should
not exceed /sys/class/leds/<led>/max_brightness.
+
+ For additional details please refer to
+ Documentation/leds/leds-class-multicolor.rst.
--
2.26.2

2020-10-29 08:45:09

by Mauro Carvalho Chehab

Subject: [PATCH 25/33] docs: Kconfig/Makefile: add a check for broken ABI files

From: Mauro Carvalho Chehab <[email protected]>

The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.

Allow checking if they're following the syntax by running
the ABI parser script on COMPILE_TEST.

With that, when there's a problem with a file under
Documentation/ABI, it would produce a warning like:

Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/Kconfig | 10 ++++++++++
Documentation/Makefile | 5 +++++
lib/Kconfig.debug | 2 ++
scripts/get_abi.pl | 14 +++++++++++---
4 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/Documentation/Kconfig b/Documentation/Kconfig
index 66046fa1c341..e549a61f4d96 100644
--- a/Documentation/Kconfig
+++ b/Documentation/Kconfig
@@ -10,4 +10,14 @@ config WARN_MISSING_DOCUMENTS

If unsure, select 'N'.

+config WARN_ABI_ERRORS
+ bool "Warn if there are errors at ABI files"
+ depends on COMPILE_TEST
+ help
+ The files under Documentation/ABI should follow what's
+ described at Documentation/ABI/README. Yet, as they're manually
+ written, it would be possible that some of those files would
+ have errors that would break them for being parsed by
+ scripts/get_abi.pl. Add a check to verify them.

+ If unsure, select 'N'.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4e47dff8b315..61a7310b49e0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -10,6 +10,11 @@ ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
endif

+# Check for broken ABI files
+ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
+$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
+endif
+
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index d7a7bc3b6098..c789b39ed527 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -2446,4 +2446,6 @@ config HYPERV_TESTING

endmenu # "Kernel Testing and Coverage"

+source "Documentation/Kconfig"
+
endmenu # Kernel hacking
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 3cff7cdf1397..413349789145 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -50,7 +50,15 @@ my %symbols;
sub parse_error($$$$) {
my ($file, $ln, $msg, $data) = @_;

- print STDERR "file $file#$ln: $msg at\n\t$data";
+ $data =~ s/\s+$/\n/;
+
+ print STDERR "Warning: file $file#$ln:\n\t$msg";
+
+ if ($data ne "") {
+ print STDERR ". Line\n\t\t$data";
+ } else {
+ print STDERR "\n";
+ }
}

#
@@ -110,7 +118,7 @@ sub parse_abi {

# Invalid, but it is a common mistake
if ($new_tag eq "where") {
- parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_);
+ parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", "");
$new_tag = "what";
}

@@ -225,7 +233,7 @@ sub parse_abi {
}

# Everything else is error
- parse_error($file, $ln, "Unexpected line:", $_);
+ parse_error($file, $ln, "Unexpected content", $_);
}
$data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description});
if ($what) {
--
2.26.2

2020-10-29 09:09:14

by Mauro Carvalho Chehab

Subject: Re: [PATCH 00/33] ABI: add it to the documentation build system

Em Wed, 28 Oct 2020 15:43:21 +0100
Greg Kroah-Hartman <[email protected]> escreveu:

> On Wed, Oct 28, 2020 at 03:22:58PM +0100, Mauro Carvalho Chehab wrote:
> > Hi Greg,
> >
> > As requested, this is a rebased version on the top of v5.10-rc1
> > adding support for having the Linux ABI documentted inside
> > the Linux admin manual.
> >
> > When compared with the version I sent years ago, this
> > version has:
> >
> > - a logic to detect duplicated ABI symbols;
> > - it auto-generate cross-reference markups for ABI symbols,
> > ABI files and .rst files;
> > - Other files from 5.10-rc1 required adjustments in order
> > to be accepted by the script in rst-source mode;
> > - Some bug fixes.
> >
> > PS.: I didn't try to merge it against linux-next yet. So,
> > I won't doubt that applying it could cause some conflicts.
> >
> > Feel free to review it.
>
> In general, I like it.
>
> If there's no complaints, I'd like to take all of the Documentation/ABI/
> updates in for 5.10-rc2 at the least, to make it easier to build on top
> of and to keep these types of mistakes from living longer than they
> should be. And make merging easier with other trees over time.

I rebased today on the top of linux-next. All patches applied as-is.

There's just a few new warnings due to a single patch, added via
platform-driver-x86:

[PATCH v7] Introduce support for Systems Management Driver over WMI for Dell Systems

(plus, it generated a get_abi.pl warning, due to a description added there
without Description:)

The ReST warnings are:

/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Title underline too short.

Dell specific class extensions
--------------------------
/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Unexpected indentation.
/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Unexpected indentation.
/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:173: WARNING: Unexpected indentation.
/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:173: WARNING: Unexpected indentation.
/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:173: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs/Documentation/ABI/testing/sysfs-class-firmware-attributes:111: WARNING: Inline emphasis start-string without end-string.

Without looking at the file, from the warnings, I suspect
that adding a few blank before/after indented lines should be
enough to fix them.

I'll prepare a separate patch to the file author, fixing those,
to be merged via the platform-driver-x86 git tree.

Thanks,
Mauro

2020-10-29 09:56:04

by Mauro Carvalho Chehab

Subject: [PATCH 12/33] docs: kernel_abi.py: add a script to parse ABI documentation

From: Mauro Carvalho Chehab <[email protected]>

The ABI documentation is special: it is not plain text files,
but, instead, files with an strict format, as specified by
Documentation/ABI/README.

Add a parser for it.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/sphinx/kernel_abi.py | 157 +++++++++++++++++++++++++++++
1 file changed, 157 insertions(+)
create mode 100644 Documentation/sphinx/kernel_abi.py

diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
new file mode 100644
index 000000000000..f8e7a02066c2
--- /dev/null
+++ b/Documentation/sphinx/kernel_abi.py
@@ -0,0 +1,157 @@
+# -*- coding: utf-8; mode: python -*-
+# SPDX-License-Identifier: GPL-2.0
+u"""
+ kernel-abi
+ ~~~~~~~~~~
+
+ Implementation of the ``kernel-abi`` reST-directive.
+
+ :copyright: Copyright (C) 2016 Markus Heiser
+ :copyright: Copyright (C) 2016-2020 Mauro Carvalho Chehab
+ :maintained-by: Mauro Carvalho Chehab <[email protected]>
+ :license: GPL Version 2, June 1991 see Linux/COPYING for details.
+
+ The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
+ scripts/get_abi.pl script to parse the Kernel ABI files.
+
+ Overview of directive's argument and options.
+
+ .. code-block:: rst
+
+ .. kernel-abi:: <ABI directory location>
+ :debug:
+
+ The argument ``<ABI directory location>`` is required. It contains the
+ location of the ABI files to be parsed.
+
+ ``debug``
+ Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
+ what reST is generated.
+
+"""
+
+import sys
+import os
+from os import path
+import subprocess
+
+from sphinx.ext.autodoc import AutodocReporter
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import ViewList
+from docutils.utils.error_reporting import ErrorString
+
+
+__version__ = '1.0'
+
+# We can't assume that six is installed
+PY3 = sys.version_info[0] == 3
+PY2 = sys.version_info[0] == 2
+if PY3:
+ # pylint: disable=C0103, W0622
+ unicode = str
+ basestring = str
+
+def setup(app):
+
+ app.add_directive("kernel-abi", KernelCmd)
+ return dict(
+ version = __version__
+ , parallel_read_safe = True
+ , parallel_write_safe = True
+ )
+
+class KernelCmd(Directive):
+
+ u"""KernelABI (``kernel-abi``) directive"""
+
+ required_arguments = 1
+ optional_arguments = 0
+ has_content = False
+ final_argument_whitespace = True
+
+ option_spec = {
+ "debug" : directives.flag
+ }
+
+ def warn(self, message, **replace):
+ replace["fname"] = self.state.document.current_source
+ replace["line_no"] = replace.get("line_no", self.lineno)
+ message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
+ self.state.document.settings.env.app.warn(message, prefix="")
+
+ def run(self):
+
+ doc = self.state.document
+ if not doc.settings.file_insertion_enabled:
+ raise self.warning("docutils: file insertion disabled")
+
+ env = doc.settings.env
+ cwd = path.dirname(doc.current_source)
+ cmd = "get_abi.pl rest --dir "
+ cmd += self.arguments[0]
+
+ srctree = path.abspath(os.environ["srctree"])
+
+ fname = cmd
+
+ # extend PATH with $(srctree)/scripts
+ path_env = os.pathsep.join([
+ srctree + os.sep + "scripts",
+ os.environ["PATH"]
+ ])
+ shell_env = os.environ.copy()
+ shell_env["PATH"] = path_env
+ shell_env["srctree"] = srctree
+
+ lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
+ nodeList = self.nestedParse(lines, fname)
+ return nodeList
+
+ def runCmd(self, cmd, **kwargs):
+ u"""Run command ``cmd`` and return it's stdout as unicode."""
+
+ try:
+ proc = subprocess.Popen(
+ cmd
+ , stdout = subprocess.PIPE
+ , stderr = subprocess.PIPE
+ , universal_newlines = True
+ , **kwargs
+ )
+ out, err = proc.communicate()
+ if err:
+ self.warn(err)
+ if proc.returncode != 0:
+ raise self.severe(
+ u"command '%s' failed with return code %d"
+ % (cmd, proc.returncode)
+ )
+ except OSError as exc:
+ raise self.severe(u"problems with '%s' directive: %s."
+ % (self.name, ErrorString(exc)))
+ return unicode(out)
+
+ def nestedParse(self, lines, fname):
+ content = ViewList()
+ node = nodes.section()
+
+ if "debug" in self.options:
+ code_block = "\n\n.. code-block:: rst\n :linenos:\n"
+ for l in lines.split("\n"):
+ code_block += "\n " + l
+ lines = code_block + "\n\n"
+
+ for c, l in enumerate(lines.split("\n")):
+ content.append(l, fname, c)
+
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ self.state.memo.title_styles = []
+ self.state.memo.section_level = 0
+ self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
+ try:
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+ return node.children
--
2.26.2

2020-10-29 09:56:03

by Mauro Carvalho Chehab

Subject: [PATCH 27/33] docs: ABI: fix syntax to be parsed using ReST notation

There are a number of new changes at the ABI files that cause
them to produce warnings when generating ABI output.

Fix them.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../ABI/stable/sysfs-driver-firmware-zynqmp | 62 ++++++++-----
Documentation/ABI/testing/debugfs-moxtet | 28 ++++--
.../ABI/testing/debugfs-turris-mox-rwtm | 6 +-
.../sysfs-bus-event_source-devices-dfl_fme | 14 +--
Documentation/ABI/testing/sysfs-bus-most | 6 +-
Documentation/ABI/testing/sysfs-class-devfreq | 6 +-
Documentation/ABI/testing/sysfs-class-ocxl | 14 +--
.../ABI/testing/sysfs-class-power-wilco | 18 ++--
.../ABI/testing/sysfs-class-rnbd-client | 93 ++++++++++---------
.../ABI/testing/sysfs-class-rtrs-client | 23 +++--
.../sysfs-devices-platform-stratix10-rsu | 10 ++
.../ABI/testing/sysfs-driver-w1_therm | 75 ++++++++++-----
.../ABI/testing/sysfs-platform-dfl-fme | 14 ++-
Documentation/ABI/testing/sysfs-platform-dptf | 11 ++-
.../sysfs-platform-intel-wmi-sbl-fw-update | 1 +
.../testing/sysfs-platform-mellanox-bootctl | 50 ++++++----
.../ABI/testing/sysfs-platform-wilco-ec | 1 +
17 files changed, 271 insertions(+), 161 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
index 00fa04c76ff3..f5724bb5b462 100644
--- a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
+++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
@@ -12,13 +12,15 @@ Description:
resets. Three registers are used by the FSBL and
other Xilinx software products: GLOBAL_GEN_STORAGE{4:6}.

- Usage:
- # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
- # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+ Usage::

- Example:
- # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
- # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+ # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+
+ Example::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+ # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0

Users: Xilinx

@@ -39,13 +41,15 @@ Description:
software products: PERS_GLOB_GEN_STORAGE{4:7}.
Register is reset only by a POR reset.

- Usage:
- # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
- # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+ Usage::

- Example:
- # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
- # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+ # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+
+ Example::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+ # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0

Users: Xilinx

@@ -61,23 +65,28 @@ Description:

Following are available shutdown scopes(subtypes):

- subsystem: Only the APU along with all of its peripherals
+ subsystem:
+ Only the APU along with all of its peripherals
not used by other processing units will be
shut down. This may result in the FPD power
domain being shut down provided that no other
processing unit uses FPD peripherals or DRAM.
- ps_only: The complete PS will be shut down, including the
+ ps_only:
+ The complete PS will be shut down, including the
RPU, PMU, etc. Only the PL domain (FPGA)
remains untouched.
- system: The complete system/device is shut down.
+ system:
+ The complete system/device is shut down.

- Usage:
- # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
- # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+ Usage::

- Example:
- # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
- # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+ # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+
+ Example::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+ # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope

Users: Xilinx

@@ -94,10 +103,13 @@ Description:
system restart.

Usage:
- Set healthy bit
- # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status

- Unset healthy bit
- # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
+ Set healthy bit::
+
+ # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
+
+ Unset healthy bit::
+
+ # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status

Users: Xilinx
diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
index 67b1717794d8..15dfaecb2892 100644
--- a/Documentation/ABI/testing/debugfs-moxtet
+++ b/Documentation/ABI/testing/debugfs-moxtet
@@ -5,10 +5,16 @@ Contact: Marek Behún <[email protected]>
Description: (R) Read input from the shift registers, in hexadecimal.
Returns N+1 bytes, where N is the number of Moxtet connected
modules. The first byte is from the CPU board itself.
- Example: 101214
- 10: CPU board with SD card
- 12: 2 = PCIe module, 1 = IRQ not active
- 14: 4 = Peridot module, 1 = IRQ not active
+
+ Example::
+
+ 101214
+
+ == =======================================
+ 10 CPU board with SD card
+ 12 2 = PCIe module, 1 = IRQ not active
+ 14 4 = Peridot module, 1 = IRQ not active
+ == =======================================

What: /sys/kernel/debug/moxtet/output
Date: March 2019
@@ -17,7 +23,13 @@ Contact: Marek Behún <[email protected]>
Description: (RW) Read last written value to the shift registers, in
hexadecimal, or write values to the shift registers, also
in hexadecimal.
- Example: 0102
- 01: 01 was last written, or is to be written, to the
- first module's shift register
- 02: the same for second module
+
+ Example::
+
+ 0102
+
+ == ================================================
+ 01 01 was last written, or is to be written, to the
+ first module's shift register
+ 02 the same for second module
+ == ================================================
diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
index 2b3255ee68fd..c8f7dadd591c 100644
--- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
+++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
@@ -2,8 +2,10 @@ What: /sys/kernel/debug/turris-mox-rwtm/do_sign
Date: Jun 2020
KernelVersion: 5.8
Contact: Marek Behún <[email protected]>
-Description: (W) Message to sign with the ECDSA private key stored in
+Description: (W)
+ Message to sign with the ECDSA private key stored in
device's OTP. The message must be exactly 64 bytes (since
this is intended for SHA-512 hashes).
- (R) The resulting signature, 136 bytes. This contains the R and
+ (R)
+ The resulting signature, 136 bytes. This contains the R and
S values of the ECDSA signature, both in big-endian format.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
index c9278a3b3df1..63a32ddcb95e 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
@@ -8,13 +8,13 @@ Description: Read-only. Attribute group to describe the magic bits

Each attribute under this group defines a bit range of the
perf_event_attr.config. All supported attributes are listed
- below.
+ below::

event = "config:0-11" - event ID
evtype = "config:12-15" - event type
portid = "config:16-23" - event source

- For example,
+ For example::

fab_mmio_read = "event=0x06,evtype=0x02,portid=0xff"

@@ -40,11 +40,11 @@ Description: Read-only. Attribute group to describe performance monitoring

All supported performance monitoring events are listed below.

- Basic events (evtype=0x00)
+ Basic events (evtype=0x00)::

clock = "event=0x00,evtype=0x00,portid=0xff"

- Cache events (evtype=0x01)
+ Cache events (evtype=0x01)::

cache_read_hit = "event=0x00,evtype=0x01,portid=0xff"
cache_read_miss = "event=0x01,evtype=0x01,portid=0xff"
@@ -59,7 +59,7 @@ Description: Read-only. Attribute group to describe performance monitoring
cache_rx_req_stall = "event=0x09,evtype=0x01,portid=0xff"
cache_eviction = "event=0x0a,evtype=0x01,portid=0xff"

- Fabric events (evtype=0x02)
+ Fabric events (evtype=0x02)::

fab_pcie0_read = "event=0x00,evtype=0x02,portid=0xff"
fab_pcie0_write = "event=0x01,evtype=0x02,portid=0xff"
@@ -78,7 +78,7 @@ Description: Read-only. Attribute group to describe performance monitoring
fab_port_mmio_read = "event=0x06,evtype=0x02,portid=?"
fab_port_mmio_write = "event=0x07,evtype=0x02,portid=?"

- VTD events (evtype=0x03)
+ VTD events (evtype=0x03)::

vtd_port_read_transaction = "event=0x00,evtype=0x03,portid=?"
vtd_port_write_transaction = "event=0x01,evtype=0x03,portid=?"
@@ -88,7 +88,7 @@ Description: Read-only. Attribute group to describe performance monitoring
vtd_port_devtlb_2m_fill = "event=0x05,evtype=0x03,portid=?"
vtd_port_devtlb_1g_fill = "event=0x06,evtype=0x03,portid=?"

- VTD SIP events (evtype=0x04)
+ VTD SIP events (evtype=0x04)::

vtd_sip_iotlb_4k_hit = "event=0x00,evtype=0x04,portid=0xff"
vtd_sip_iotlb_2m_hit = "event=0x01,evtype=0x04,portid=0xff"
diff --git a/Documentation/ABI/testing/sysfs-bus-most b/Documentation/ABI/testing/sysfs-bus-most
index ec0a603d804b..38cc03e408e7 100644
--- a/Documentation/ABI/testing/sysfs-bus-most
+++ b/Documentation/ABI/testing/sysfs-bus-most
@@ -235,7 +235,8 @@ KernelVersion: 4.15
Contact: Christian Gromm <[email protected]>
Description:
This is to read back the configured direction of the channel.
- The following strings will be accepted:
+ The following strings will be accepted::
+
'tx',
'rx'
Users:
@@ -246,7 +247,8 @@ KernelVersion: 4.15
Contact: Christian Gromm <[email protected]>
Description:
This is to read back the configured data type of the channel.
- The following strings will be accepted:
+ The following strings will be accepted::
+
'control',
'async',
'sync',
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
index deefffb3bbe4..b8ebff4b1c4c 100644
--- a/Documentation/ABI/testing/sysfs-class-devfreq
+++ b/Documentation/ABI/testing/sysfs-class-devfreq
@@ -62,7 +62,8 @@ Description:
driver should provide the list of available frequencies
with its profile. If need to reset the statistics of devfreq
behavior on a specific device, enter 0(zero) to 'trans_stat'
- as following:
+ as following::
+
echo 0 > /sys/class/devfreq/.../trans_stat

What: /sys/class/devfreq/.../userspace/set_freq
@@ -117,6 +118,7 @@ Description:
This work timer is used by devfreq workqueue in order to
monitor the device status such as utilization. The user
can change the work timer on runtime according to their demand
- as following:
+ as following::
+
echo deferrable > /sys/class/devfreq/.../timer
echo delayed > /sys/class/devfreq/.../timer
diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
index bf33f4fda58f..847a7edc3113 100644
--- a/Documentation/ABI/testing/sysfs-class-ocxl
+++ b/Documentation/ABI/testing/sysfs-class-ocxl
@@ -13,8 +13,8 @@ Description: read only
where:

==== ===============================================
- n: number of currently active contexts, for debug
- max: maximum number of contexts supported by the AFU
+ n number of currently active contexts, for debug
+ max maximum number of contexts supported by the AFU
==== ===============================================

What: /sys/class/ocxl/<afu name>/pp_mmio_size
@@ -43,7 +43,9 @@ Contact: [email protected]
Description: read/write
Control whether the FPGA is reloaded on a link reset. Enabled
through a vendor-specific logic block on the FPGA.
- 0 Do not reload FPGA image from flash
- 1 Reload FPGA image from flash
- unavailable
- The device does not support this capability
+
+ =========== ===========================================
+ 0 Do not reload FPGA image from flash
+ 1 Reload FPGA image from flash
+ unavailable The device does not support this capability
+ =========== ===========================================
diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco
index 84fde1d0ada0..82af180fcaab 100644
--- a/Documentation/ABI/testing/sysfs-class-power-wilco
+++ b/Documentation/ABI/testing/sysfs-class-power-wilco
@@ -4,17 +4,23 @@ KernelVersion: 5.2
Description:
What charging algorithm to use:

- Standard: Fully charges battery at a standard rate.
- Adaptive: Battery settings adaptively optimized based on
+ Standard:
+ Fully charges battery at a standard rate.
+ Adaptive:
+ Battery settings adaptively optimized based on
typical battery usage pattern.
- Fast: Battery charges over a shorter period.
- Trickle: Extends battery lifespan, intended for users who
+ Fast:
+ Battery charges over a shorter period.
+ Trickle:
+ Extends battery lifespan, intended for users who
primarily use their Chromebook while connected to AC.
- Custom: A low and high threshold percentage is specified.
+ Custom:
+ A low and high threshold percentage is specified.
Charging begins when level drops below
charge_control_start_threshold, and ceases when
level is above charge_control_end_threshold.
- Long Life: Customized charge rate for last longer battery life.
+ Long Life:
+ Customized charge rate for last longer battery life.
On Wilco device this mode is pre-configured in the factory
through EC's private PID. Swiching to a different mode will
be denied by Wilco EC when Long Life mode is enabled.
diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client
index c084f203b41e..00c0286733d4 100644
--- a/Documentation/ABI/testing/sysfs-class-rnbd-client
+++ b/Documentation/ABI/testing/sysfs-class-rnbd-client
@@ -5,62 +5,70 @@ Contact: Jack Wang <[email protected]> Danil Kipnis <danil.kipnis@cloud
Description: Provide information about RNBD-client.
All sysfs files that are not read-only provide the usage information on read:

- Example:
- # cat /sys/class/rnbd-client/ctl/map_device
+ Example::

- > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
- > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
- > [access_mode=<ro|rw|migration>] > map_device
- >
- > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
+ # cat /sys/class/rnbd-client/ctl/map_device
+
+ > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
+ > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
+ > [access_mode=<ro|rw|migration>] > map_device
+ >
+ > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]

What: /sys/class/rnbd-client/ctl/map_device
Date: Feb 2020
KernelVersion: 5.7
Contact: Jack Wang <[email protected]> Danil Kipnis <[email protected]>
-Description: Expected format is the following:
+Description: Expected format is the following::

- sessname=<name of the rtrs session>
- path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
- device_path=<full path on remote side>
- [access_mode=<ro|rw|migration>]
+ sessname=<name of the rtrs session>
+ path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
+ device_path=<full path on remote side>
+ [access_mode=<ro|rw|migration>]

Where:

- sessname: accepts a string not bigger than 256 chars, which identifies
- a given session on the client and on the server.
- I.e. "clt_hostname-srv_hostname" could be a natural choice.
+ sessname:
+ accepts a string not bigger than 256 chars, which identifies
+ a given session on the client and on the server.
+ I.e. "clt_hostname-srv_hostname" could be a natural choice.

- path: describes a connection between the client and the server by
- specifying destination and, when required, the source address.
- The addresses are to be provided in the following format:
+ path:
+ describes a connection between the client and the server by
+ specifying destination and, when required, the source address.
+ The addresses are to be provided in the following format::

- ip:<IPv6>
- ip:<IPv4>
- gid:<GID>
+ ip:<IPv6>
+ ip:<IPv4>
+ gid:<GID>

- for example:
+ for example::
+
+ path=ip:10.0.0.66

- path=ip:10.0.0.66
The single addr is treated as the destination.
The connection will be established to this server from any client IP address.

- path=ip:10.0.0.66,ip:10.0.1.66
+ ::
+
+ path=ip:10.0.0.66,ip:10.0.1.66
+
First addr is the source address and the second is the destination.

If multiple "path=" options are specified multiple connection
will be established and data will be sent according to
the selected multipath policy (see RTRS mp_policy sysfs entry description).

- device_path: Path to the block device on the server side. Path is specified
- relative to the directory on server side configured in the
- 'dev_search_path' module parameter of the rnbd_server.
- The rnbd_server prepends the <device_path> received from client
- with <dev_search_path> and tries to open the
- <dev_search_path>/<device_path> block device. On success,
- a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
- directory and an entry in /sys/class/rnbd-client/ctl/devices
- will be created.
+ device_path:
+ Path to the block device on the server side. Path is specified
+ relative to the directory on server side configured in the
+ 'dev_search_path' module parameter of the rnbd_server.
+ The rnbd_server prepends the <device_path> received from client
+ with <dev_search_path> and tries to open the
+ <dev_search_path>/<device_path> block device. On success,
+ a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
+ directory and an entry in /sys/class/rnbd-client/ctl/devices
+ will be created.

If 'dev_search_path' contains '%SESSNAME%', then each session can
have different devices namespace, e.g. server was configured with
@@ -68,11 +76,12 @@ Description: Expected format is the following:
client has this string "sessname=blya device_path=sda", then server
will try to open: /run/rnbd-devs/blya/sda.

- access_mode: the access_mode parameter specifies if the device is to be
- mapped as "ro" read-only or "rw" read-write. The server allows
- a device to be exported in rw mode only once. The "migration"
- access mode has to be specified if a second mapping in read-write
- mode is desired.
+ access_mode:
+ the access_mode parameter specifies if the device is to be
+ mapped as "ro" read-only or "rw" read-write. The server allows
+ a device to be exported in rw mode only once. The "migration"
+ access mode has to be specified if a second mapping in read-write
+ mode is desired.

By default "rw" is used.

@@ -91,7 +100,7 @@ Description: Expected format is the following:
is the same as the device name. By extracting the last part of the
path the path to the device /dev/<dev-name> can be build.

- o /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)
+ * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)

How to find the <device_id> of the device is described on the next
section.
@@ -106,6 +115,6 @@ Description: For each device mapped on the client a new symbolic link is created
The <device_id> of each device is created as follows:

- If the 'device_path' provided during mapping contains slashes ("/"),
- they are replaced by exclamation mark ("!") and used as as the
- <device_id>. Otherwise, the <device_id> will be the same as the
- "device_path" provided.
+ they are replaced by exclamation mark ("!") and used as as the
+ <device_id>. Otherwise, the <device_id> will be the same as the
+ "device_path" provided.
diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client
index e7e718db8941..0f7165aab251 100644
--- a/Documentation/ABI/testing/sysfs-class-rtrs-client
+++ b/Documentation/ABI/testing/sysfs-class-rtrs-client
@@ -10,10 +10,10 @@ Date: Feb 2020
KernelVersion: 5.7
Contact: Jack Wang <[email protected]> Danil Kipnis <[email protected]>
Description: RW, adds a new path (connection) to an existing session. Expected format is the
- following:
+ following::

- <[source addr,]destination addr>
- *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
+ <[source addr,]destination addr>
+ *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]

What: /sys/class/rtrs-client/<session-name>/max_reconnect_attempts
Date: Feb 2020
@@ -29,10 +29,10 @@ Contact: Jack Wang <[email protected]> Danil Kipnis <danil.kipnis@cloud
Description: Multipath policy specifies which path should be selected on each IO:

round-robin (0):
- select path in per CPU round-robin manner.
+ select path in per CPU round-robin manner.

min-inflight (1):
- select path with minimum inflights.
+ select path with minimum inflights.

What: /sys/class/rtrs-client/<session-name>/paths/
Date: Feb 2020
@@ -109,8 +109,11 @@ Description: RTRS expects that each HCA IRQ is pinned to a separate CPU. If it's
not the case, the processing of an I/O response could be processed on a
different CPU than where it was originally submitted. This file shows
how many interrupts where generated on a non expected CPU.
- "from:" is the CPU on which the IRQ was expected, but not generated.
- "to:" is the CPU on which the IRQ was generated, but not expected.
+
+ "from:"
+ is the CPU on which the IRQ was expected, but not generated.
+ "to:"
+ is the CPU on which the IRQ was generated, but not expected.

What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reconnects
Date: Feb 2020
@@ -125,7 +128,7 @@ Date: Feb 2020
KernelVersion: 5.7
Contact: Jack Wang <[email protected]> Danil Kipnis <[email protected]>
Description: Contains statistics regarding rdma operations and inflight operations.
- The output consists of 6 values:
+ The output consists of 6 values::

- <read-count> <read-total-size> <write-count> <write-total-size> \
- <inflights> <failovered>
+ <read-count> <read-total-size> <write-count> \
+ <write-total-size> <inflights> <failovered>
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
index a8daceb4a956..ee253b033280 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
+++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
@@ -102,6 +102,8 @@ Description:
b[15:0]
inform firmware the current software execution
stage.
+
+ == ===========================================
0 the first stage bootloader didn't run or
didn't reach the point of launching second
stage bootloader.
@@ -111,21 +113,29 @@ Description:
2 both first and second stage bootloader ran
and the operating system launch was
attempted.
+ == ===========================================

b[16]
+ == ===========================================
1 firmware to reset current image retry
counter.
0 no action.
+ == ===========================================

b[17]
+ == ===========================================
1 firmware to clear RSU log
0 no action.
+ == ===========================================

b[18]
this is negative logic
+
+ == ===========================================
1 no action
0 firmware record the notify code defined
in b[15:0].
+ == ===========================================

What: /sys/devices/platform/stratix10-rsu.0/dcmf0
Date: June 2020
diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm
index 8873bbb075cb..6a37dc33ffdb 100644
--- a/Documentation/ABI/testing/sysfs-driver-w1_therm
+++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
@@ -22,8 +22,10 @@ Description:
device data to its embedded EEPROM, either restore data
embedded in device EEPROM. Be aware that devices support
limited EEPROM writing cycles (typical 50k)
+
* 'save': save device RAM to EEPROM
* 'restore': restore EEPROM data in device RAM
+
Users: any user space application which wants to communicate with
w1_term device

@@ -33,9 +35,11 @@ Date: May 2020
Contact: Akira Shimahara <[email protected]>
Description:
(RO) return the power status by asking the device
+
* '0': device parasite powered
* '1': device externally powered
* '-xx': xx is kernel error when reading power status
+
Users: any user space application which wants to communicate with
w1_term device

@@ -49,10 +53,12 @@ Description:
will be changed only in device RAM, so it will be cleared when
power is lost. Trigger a 'save' to EEPROM command to keep
values after power-on. Read or write are :
+
* '9..14': device resolution in bit
- or resolution to set in bit
+ or resolution to set in bit
* '-xx': xx is kernel error when reading the resolution
* Anything else: do nothing
+
Some DS18B20 clones are fixed in 12-bit resolution, so the
actual resolution is read back from the chip and verified. Error
is reported if the results differ.
@@ -65,16 +71,18 @@ Date: May 2020
Contact: Akira Shimahara <[email protected]>
Description:
(RO) return the temperature in 1/1000 degC.
+
* If a bulk read has been triggered, it will directly
- return the temperature computed when the bulk read
- occurred, if available. If not yet available, nothing
- is returned (a debug kernel message is sent), you
- should retry later on.
+ return the temperature computed when the bulk read
+ occurred, if available. If not yet available, nothing
+ is returned (a debug kernel message is sent), you
+ should retry later on.
* If no bulk read has been triggered, it will trigger
- a conversion and send the result. Note that the
- conversion duration depend on the resolution (if
- device support this feature). It takes 94ms in 9bits
- resolution, 750ms for 12bits.
+ a conversion and send the result. Note that the
+ conversion duration depend on the resolution (if
+ device support this feature). It takes 94ms in 9bits
+ resolution, 750ms for 12bits.
+
Users: any user space application which wants to communicate with
w1_term device

@@ -86,12 +94,14 @@ Description:
(RW) return the temperature in 1/1000 degC.
*read*: return 2 lines with the hexa output data sent on the
bus, return the CRC check and temperature in 1/1000 degC
- *write* :
+ *write*:
+
* '0' : save the 2 or 3 bytes to the device EEPROM
- (i.e. TH, TL and config register)
+ (i.e. TH, TL and config register)
* '9..14' : set the device resolution in RAM
- (if supported)
+ (if supported)
* Anything else: do nothing
+
refer to Documentation/w1/slaves/w1_therm.rst for detailed
information.
Users: any user space application which wants to communicate with
@@ -103,14 +113,21 @@ Date: May 2020
Contact: Akira Shimahara <[email protected]>
Description:
(RW) trigger a bulk read conversion. read the status
+
*read*:
- * '-1': conversion in progress on at least 1 sensor
- * '1' : conversion complete but at least one sensor
+ * '-1':
+ conversion in progress on at least 1 sensor
+ * '1' :
+ conversion complete but at least one sensor
value has not been read yet
- * '0' : no bulk operation. Reading temperature will
+ * '0' :
+ no bulk operation. Reading temperature will
trigger a conversion on each device
- *write*: 'trigger': trigger a bulk read on all supporting
+
+ *write*:
+ 'trigger': trigger a bulk read on all supporting
devices on the bus
+
Note that if a bulk read is sent but one sensor is not read
immediately, the next access to temperature on this device
will return the temperature measured at the time of issue
@@ -128,14 +145,19 @@ Description:
reset to default (datasheet) conversion time for a new
resolution.

- *read*: Actual conversion time in milliseconds. *write*:
- '0': Set the default conversion time from the datasheet.
- '1': Measure and set the conversion time. Make a single
+ *read*:
+ Actual conversion time in milliseconds.
+
+ *write*:
+ * '0':
+ Set the default conversion time from the datasheet.
+ * '1':
+ Measure and set the conversion time. Make a single
temperature conversion, measure an actual value.
Increase it by 20% for temperature range. A new
conversion time can be obtained by reading this
same attribute.
- other positive value:
+ * other positive value:
Set the conversion time in milliseconds.

Users: An application using the w1_term device
@@ -148,16 +170,21 @@ Description:
(RW) Control optional driver settings.
Bit masks to read/write (bitwise OR):

- 1: Enable check for conversion success. If byte 6 of
+ == ============================================================
+ 1 Enable check for conversion success. If byte 6 of
scratchpad memory is 0xC after conversion, and
temperature reads 85.00 (powerup value) or 127.94
(insufficient power) - return a conversion error.

- 2: Enable poll for conversion completion. Generate read cycles
+ 2 Enable poll for conversion completion. Generate read cycles
after the conversion start and wait for 1's. In parasite
power mode this feature is not available.
+ == ============================================================

- *read*: Currently selected features.
- *write*: Select features.
+ *read*:
+ Currently selected features.
+
+ *write*:
+ Select features.

Users: An application using the w1_term device
diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme
index 3683cb1cdc3d..d6ab34e81b9b 100644
--- a/Documentation/ABI/testing/sysfs-platform-dfl-fme
+++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
@@ -113,8 +113,11 @@ KernelVersion: 5.5
Contact: Wu Hao <[email protected]>
Description: Read-Only. Read this file to get the name of hwmon device, it
supports values:
- 'dfl_fme_thermal' - thermal hwmon device name
- 'dfl_fme_power' - power hwmon device name
+
+ ================= =========================
+ 'dfl_fme_thermal' thermal hwmon device name
+ 'dfl_fme_power' power hwmon device name
+ ================= =========================

What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_input
Date: October 2019
@@ -169,8 +172,11 @@ KernelVersion: 5.5
Contact: Wu Hao <[email protected]>
Description: Read-Only. Read this file to get the policy of hardware threshold1
(see 'temp1_max'). It only supports two values (policies):
- 0 - AP2 state (90% throttling)
- 1 - AP1 state (50% throttling)
+
+ == ==========================
+ 0 AP2 state (90% throttling)
+ 1 AP1 state (50% throttling)
+ == ==========================

What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_input
Date: October 2019
diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
index 2cbc660d163b..141834342a4d 100644
--- a/Documentation/ABI/testing/sysfs-platform-dptf
+++ b/Documentation/ABI/testing/sysfs-platform-dptf
@@ -27,12 +27,15 @@ KernelVersion: v4.10
Contact: [email protected]
Description:
(RO) Display the platform power source
+
+ ========= ============================
bits[3:0] Current power source
- 0x00 = DC
- 0x01 = AC
- 0x02 = USB
- 0x03 = Wireless Charger
+ - 0x00 = DC
+ - 0x01 = AC
+ - 0x02 = USB
+ - 0x03 = Wireless Charger
bits[7:4] Power source sequence number
+ ========= ============================

What: /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
Date: Jul, 2016
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
index 5aa618987cad..02ae1e9bbfc8 100644
--- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
+++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
@@ -8,5 +8,6 @@ Description:
of 0 and userspace can signal SBL to update firmware,
on next reboot, by writing a value of 1.
There are two available states:
+
* 0 -> Skip firmware update while rebooting
* 1 -> Attempt firmware update on next reboot
diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
index 401d202f478b..e79ca22e2f45 100644
--- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
+++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
@@ -5,10 +5,13 @@ Contact: "Liming Sun <[email protected]>"
Description:
The Life-cycle state of the SoC, which could be one of the
following values.
- Production - Production state and can be updated to secure
- GA Secured - Secure chip and not able to change state
- GA Non-Secured - Non-Secure chip and not able to change state
- RMA - Return Merchandise Authorization
+
+ ============== =============================================
+ Production Production state and can be updated to secure
+ GA Secured Secure chip and not able to change state
+ GA Non-Secured Non-Secure chip and not able to change state
+ RMA Return Merchandise Authorization
+ ============== =============================================

What: /sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog
Date: Oct 2019
@@ -25,10 +28,13 @@ KernelVersion: 5.5
Contact: "Liming Sun <[email protected]>"
Description:
The source of the boot stream for the next reset. It could be
- one of the following values.
- external - boot from external source (USB or PCIe)
- emmc - boot from the onchip eMMC
- emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
+ one of the following values:
+
+ =========== ===============================================
+ external boot from external source (USB or PCIe)
+ emmc boot from the onchip eMMC
+ emmc_legacy boot from the onchip eMMC in legacy (slow) mode
+ =========== ===============================================

What: /sys/bus/platform/devices/MLNXBF04:00/second_reset_action
Date: Oct 2019
@@ -38,11 +44,14 @@ Description:
Update the source of the boot stream after next reset. It could
be one of the following values and will be applied after next
reset.
- external - boot from external source (USB or PCIe)
- emmc - boot from the onchip eMMC
- emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
- swap_emmc - swap the primary / secondary boot partition
- none - cancel the action
+
+ =========== ===============================================
+ external boot from external source (USB or PCIe)
+ emmc boot from the onchip eMMC
+ emmc_legacy boot from the onchip eMMC in legacy (slow) mode
+ swap_emmc swap the primary / secondary boot partition
+ none cancel the action
+ =========== ===============================================

What: /sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state
Date: Oct 2019
@@ -50,9 +59,12 @@ KernelVersion: 5.5
Contact: "Liming Sun <[email protected]>"
Description:
The state of eFuse versions with the following values.
- InUse - burnt, valid and currently in use
- Used - burnt and valid
- Free - not burnt and free to use
- Skipped - not burnt but not free (skipped)
- Wasted - burnt and invalid
- Invalid - not burnt but marked as valid (error state).
+
+ ======= ===============================================
+ InUse burnt, valid and currently in use
+ Used burnt and valid
+ Free not burnt and free to use
+ Skipped not burnt but not free (skipped)
+ Wasted burnt and invalid
+ Invalid not burnt but marked as valid (error state).
+ ======= ===============================================
diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec b/Documentation/ABI/testing/sysfs-platform-wilco-ec
index 5f60b184a5a5..4439d0644091 100644
--- a/Documentation/ABI/testing/sysfs-platform-wilco-ec
+++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec
@@ -39,6 +39,7 @@ Description:
which affects charging via the special USB PowerShare port
(marked with a small lightning bolt or battery icon) when in
low power states:
+
- In S0, the port will always provide power.
- In S0ix, if usb_charge is enabled, then power will be
supplied to the port when on AC or if battery is > 50%.
--
2.26.2