* [PATCH v4 00/28] Convert files to ReST - part 1
@ 2019-06-12 17:52 Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 01/28] docs: aoe: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (24 more replies)
0 siblings, 25 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Palmer Dabbelt, Albert Ou, Alexei Starovoitov, Daniel Borkmann,
Martin KaFai Lau, Song Liu, Yonghong Song, Greentime Hu,
Vincent Chen, linux-riscv, netdev, bpf
This is mostly a rebase of the /33 series v3 I sent, on the top of the latest
linux-next (next-20190612).
Changes from v3:
- dropped cpufreq conversion - documents are too outdated;
- infiniband patch is not here anymore - as it should be merged via RDMA;
- s390 patches were already merged;
- Dropped Geert as Maintainer from fb/framebuffer.rst, as per his request;
- Did a minor editorial change at popwerpc/cxl.rst per Andrew Donellan
request;
- Added acks/reviews;
- trivial rebase fixups.
Jon,
the first version of this series was sent back on April, 15. So, I
suspect it should be fine to merge those patches via docs tree.
I should be sending soon the next part of this conversion series.
-
This is the first part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, this series is based on today's docs-next
+ linux-next, at tag next-20190607.
I have right now about 85 patches with this undergoing work. That's
because I opted to do ~1 patch per converted directory.
That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts. Those patches should probably be good to be merged
either by subsystem maintainers or via the docs tree.
I opted to mark new files not included yet to the main index.rst (directly or
indirectly ) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement.
Both this series and the next parts are on my devel git tree,
at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v4.2
The final output in html (after all patches I currently have, including
the upcoming series) can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
Mauro Carvalho Chehab (28):
docs: aoe: convert docs to ReST and rename to *.rst
docs: arm64: convert docs to ReST and rename to .rst
docs: cdrom-standard.tex: convert from LaTeX to ReST
docs: cdrom: convert docs to ReST and rename to *.rst
docs: cgroup-v1: convert docs to ReST and rename to *.rst
docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
docs: convert docs to ReST and rename to *.rst
docs: fault-injection: convert docs to ReST and rename to *.rst
docs: fb: convert docs to ReST and rename to *.rst
docs: fpga: convert docs to ReST and rename to *.rst
docs: ide: convert docs to ReST and rename to *.rst
docs: kbuild: convert docs to ReST and rename to *.rst
docs: kdump: convert docs to ReST and rename to *.rst
docs: locking: convert docs to ReST and rename to *.rst
docs: mic: convert docs to ReST and rename to *.rst
docs: netlabel: convert docs to ReST and rename to *.rst
docs: pcmcia: convert docs to ReST and rename to *.rst
docs: convert docs to ReST and rename to *.rst
docs: powerpc: convert docs to ReST and rename to *.rst
docs: pps.txt: convert to ReST and rename to pps.rst
docs: ptp.txt: convert to ReST and move to driver-api
docs: riscv: convert docs to ReST and rename to *.rst
docs: target: convert docs to ReST and rename to *.rst
docs: timers: convert docs to ReST and rename to *.rst
docs: watchdog: convert docs to ReST and rename to *.rst
docs: xilinx: convert eemi.txt to eemi.rst
docs: scheduler: convert docs to ReST and rename to *.rst
docs: EDID/HOWTO.txt: convert it and rename to howto.rst
.../ABI/testing/sysfs-class-powercap | 2 +-
Documentation/ABI/testing/sysfs-kernel-uids | 2 +-
Documentation/EDID/{HOWTO.txt => howto.rst} | 31 +-
Documentation/PCI/pci-error-recovery.rst | 23 +-
Documentation/admin-guide/README.rst | 2 +-
Documentation/admin-guide/bug-hunting.rst | 2 +-
Documentation/admin-guide/hw-vuln/l1tf.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 24 +-
.../admin-guide/mm/numa_memory_policy.rst | 2 +-
Documentation/aoe/{aoe.txt => aoe.rst} | 63 +-
Documentation/aoe/examples.rst | 23 +
Documentation/aoe/index.rst | 19 +
Documentation/aoe/{todo.txt => todo.rst} | 3 +
Documentation/aoe/udev.txt | 2 +-
...object_usage.txt => acpi_object_usage.rst} | 288 +++--
.../arm64/{arm-acpi.txt => arm-acpi.rst} | 155 +--
.../arm64/{booting.txt => booting.rst} | 91 +-
...egisters.txt => cpu-feature-registers.rst} | 204 ++--
.../arm64/{elf_hwcaps.txt => elf_hwcaps.rst} | 56 +-
.../{hugetlbpage.txt => hugetlbpage.rst} | 7 +-
Documentation/arm64/index.rst | 28 +
...structions.txt => legacy_instructions.rst} | 43 +-
Documentation/arm64/memory.rst | 98 ++
Documentation/arm64/memory.txt | 97 --
...ication.txt => pointer-authentication.rst} | 2 +
...{silicon-errata.txt => silicon-errata.rst} | 65 +-
Documentation/arm64/{sve.txt => sve.rst} | 12 +-
...agged-pointers.txt => tagged-pointers.rst} | 6 +-
Documentation/block/bfq-iosched.txt | 2 +-
Documentation/cdrom/Makefile | 21 -
Documentation/cdrom/cdrom-standard.rst | 1063 +++++++++++++++++
Documentation/cdrom/cdrom-standard.tex | 1026 ----------------
Documentation/cdrom/{ide-cd => ide-cd.rst} | 196 +--
Documentation/cdrom/index.rst | 19 +
...{packet-writing.txt => packet-writing.rst} | 27 +-
...io-controller.txt => blkio-controller.rst} | 103 +-
.../cgroup-v1/{cgroups.txt => cgroups.rst} | 184 +--
.../cgroup-v1/{cpuacct.txt => cpuacct.rst} | 15 +-
.../cgroup-v1/{cpusets.txt => cpusets.rst} | 205 ++--
.../cgroup-v1/{devices.txt => devices.rst} | 40 +-
...er-subsystem.txt => freezer-subsystem.rst} | 14 +-
.../cgroup-v1/{hugetlb.txt => hugetlb.rst} | 39 +-
Documentation/cgroup-v1/index.rst | 30 +
.../{memcg_test.txt => memcg_test.rst} | 263 ++--
.../cgroup-v1/{memory.txt => memory.rst} | 449 ++++---
.../cgroup-v1/{net_cls.txt => net_cls.rst} | 37 +-
.../cgroup-v1/{net_prio.txt => net_prio.rst} | 24 +-
.../cgroup-v1/{pids.txt => pids.rst} | 78 +-
.../cgroup-v1/{rdma.txt => rdma.rst} | 66 +-
Documentation/cpu-freq/core.txt | 2 +-
...{cache-policies.txt => cache-policies.rst} | 24 +-
.../device-mapper/{cache.txt => cache.rst} | 206 ++--
.../device-mapper/{delay.txt => delay.rst} | 29 +-
.../{dm-crypt.txt => dm-crypt.rst} | 57 +-
.../{dm-flakey.txt => dm-flakey.rst} | 45 +-
.../{dm-init.txt => dm-init.rst} | 75 +-
.../{dm-integrity.txt => dm-integrity.rst} | 62 +-
.../device-mapper/{dm-io.txt => dm-io.rst} | 14 +-
.../device-mapper/{dm-log.txt => dm-log.rst} | 5 +-
...m-queue-length.txt => dm-queue-length.rst} | 25 +-
.../{dm-raid.txt => dm-raid.rst} | 225 ++--
...m-service-time.txt => dm-service-time.rst} | 68 +-
Documentation/device-mapper/dm-uevent.rst | 110 ++
Documentation/device-mapper/dm-uevent.txt | 97 --
.../{dm-zoned.txt => dm-zoned.rst} | 10 +-
.../device-mapper/{era.txt => era.rst} | 36 +-
Documentation/device-mapper/index.rst | 44 +
.../device-mapper/{kcopyd.txt => kcopyd.rst} | 10 +-
Documentation/device-mapper/linear.rst | 63 +
Documentation/device-mapper/linear.txt | 61 -
.../{log-writes.txt => log-writes.rst} | 91 +-
...ersistent-data.txt => persistent-data.rst} | 4 +
.../{snapshot.txt => snapshot.rst} | 116 +-
.../{statistics.txt => statistics.rst} | 62 +-
Documentation/device-mapper/striped.rst | 61 +
Documentation/device-mapper/striped.txt | 57 -
.../device-mapper/{switch.txt => switch.rst} | 47 +-
...provisioning.txt => thin-provisioning.rst} | 68 +-
.../{unstriped.txt => unstriped.rst} | 111 +-
.../device-mapper/{verity.txt => verity.rst} | 20 +-
.../{writecache.txt => writecache.rst} | 13 +-
.../device-mapper/{zero.txt => zero.rst} | 14 +-
Documentation/driver-api/pm/devices.rst | 6 +-
.../{pps/pps.txt => driver-api/pps.rst} | 67 +-
.../{ptp/ptp.txt => driver-api/ptp.rst} | 26 +-
.../driver-api/usb/power-management.rst | 2 +-
...ault-injection.txt => fault-injection.rst} | 265 ++--
Documentation/fault-injection/index.rst | 20 +
...r-inject.txt => notifier-error-inject.rst} | 18 +-
.../fault-injection/nvme-fault-injection.rst | 120 ++
.../fault-injection/nvme-fault-injection.txt | 116 --
.../fault-injection/provoke-crashes.rst | 48 +
.../fault-injection/provoke-crashes.txt | 38 -
Documentation/fb/{api.txt => api.rst} | 29 +-
Documentation/fb/{arkfb.txt => arkfb.rst} | 8 +-
.../fb/{aty128fb.txt => aty128fb.rst} | 35 +-
.../fb/{cirrusfb.txt => cirrusfb.rst} | 47 +-
.../fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} | 57 +-
.../fb/{deferred_io.txt => deferred_io.rst} | 28 +-
Documentation/fb/{efifb.txt => efifb.rst} | 18 +-
.../fb/{ep93xx-fb.txt => ep93xx-fb.rst} | 27 +-
Documentation/fb/{fbcon.txt => fbcon.rst} | 177 +--
.../fb/{framebuffer.txt => framebuffer.rst} | 80 +-
Documentation/fb/{gxfb.txt => gxfb.rst} | 24 +-
Documentation/fb/index.rst | 50 +
.../fb/{intel810.txt => intel810.rst} | 79 +-
Documentation/fb/{intelfb.txt => intelfb.rst} | 62 +-
.../fb/{internals.txt => internals.rst} | 24 +-
Documentation/fb/{lxfb.txt => lxfb.rst} | 25 +-
Documentation/fb/matroxfb.rst | 443 +++++++
Documentation/fb/matroxfb.txt | 413 -------
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/pvr2fb.rst | 66 +
Documentation/fb/pvr2fb.txt | 65 -
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
Documentation/fb/sh7760fb.rst | 130 ++
Documentation/fb/sh7760fb.txt | 131 --
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/sstfb.rst | 207 ++++
Documentation/fb/sstfb.txt | 174 ---
Documentation/fb/{tgafb.txt => tgafb.rst} | 30 +-
.../fb/{tridentfb.txt => tridentfb.rst} | 36 +-
Documentation/fb/{udlfb.txt => udlfb.rst} | 55 +-
Documentation/fb/{uvesafb.txt => uvesafb.rst} | 128 +-
Documentation/fb/{vesafb.txt => vesafb.rst} | 121 +-
Documentation/fb/viafb.rst | 297 +++++
Documentation/fb/viafb.txt | 252 ----
.../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +-
Documentation/filesystems/tmpfs.txt | 2 +-
.../filesystems/ubifs-authentication.md | 4 +-
Documentation/fpga/{dfl.txt => dfl.rst} | 58 +-
Documentation/fpga/index.rst | 17 +
Documentation/ide/changelogs.rst | 17 +
.../ide/{ide-tape.txt => ide-tape.rst} | 23 +-
Documentation/ide/{ide.txt => ide.rst} | 147 +--
Documentation/ide/index.rst | 21 +
...arm-plug-howto.txt => warm-plug-howto.rst} | 10 +-
...eaders_install.txt => headers_install.rst} | 5 +-
Documentation/kbuild/index.rst | 27 +
Documentation/kbuild/issues.rst | 11 +
.../kbuild/{kbuild.txt => kbuild.rst} | 119 +-
...nfig-language.txt => kconfig-language.rst} | 232 ++--
...anguage.txt => kconfig-macro-language.rst} | 37 +-
.../kbuild/{kconfig.txt => kconfig.rst} | 136 ++-
.../kbuild/{makefiles.txt => makefiles.rst} | 530 +++++---
.../kbuild/{modules.txt => modules.rst} | 168 +--
Documentation/kdump/index.rst | 21 +
Documentation/kdump/{kdump.txt => kdump.rst} | 131 +-
.../kdump/{vmcoreinfo.txt => vmcoreinfo.rst} | 59 +-
Documentation/kernel-hacking/hacking.rst | 4 +-
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/kernel-per-CPU-kthreads.txt | 2 +-
Documentation/locking/index.rst | 24 +
...{lockdep-design.txt => lockdep-design.rst} | 51 +-
Documentation/locking/lockstat.rst | 204 ++++
Documentation/locking/lockstat.txt | 183 ---
.../{locktorture.txt => locktorture.rst} | 105 +-
.../{mutex-design.txt => mutex-design.rst} | 26 +-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++-
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +-
.../locking/{spinlocks.txt => spinlocks.rst} | 32 +-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +-
Documentation/mic/index.rst | 18 +
.../{mic_overview.txt => mic_overview.rst} | 6 +-
.../{scif_overview.txt => scif_overview.rst} | 58 +-
.../{cipso_ipv4.txt => cipso_ipv4.rst} | 19 +-
Documentation/netlabel/draft_ietf.rst | 5 +
Documentation/netlabel/index.rst | 21 +
.../{introduction.txt => introduction.rst} | 16 +-
.../{lsm_interface.txt => lsm_interface.rst} | 16 +-
Documentation/networking/timestamping.txt | 2 +-
.../{devicetable.txt => devicetable.rst} | 4 +
...{driver-changes.txt => driver-changes.rst} | 35 +-
.../pcmcia/{driver.txt => driver.rst} | 18 +-
Documentation/pcmcia/index.rst | 20 +
.../pcmcia/{locking.txt => locking.rst} | 39 +-
Documentation/pi-futex.txt | 2 +-
.../power/{apm-acpi.txt => apm-acpi.rst} | 10 +-
...m-debugging.txt => basic-pm-debugging.rst} | 79 +-
...harger-manager.txt => charger-manager.rst} | 101 +-
...rivers-testing.txt => drivers-testing.rst} | 15 +-
.../{energy-model.txt => energy-model.rst} | 101 +-
...ing-of-tasks.txt => freezing-of-tasks.rst} | 91 +-
Documentation/power/index.rst | 46 +
.../power/{interface.txt => interface.rst} | 24 +-
Documentation/power/{opp.txt => opp.rst} | 175 +--
Documentation/power/{pci.txt => pci.rst} | 87 +-
...qos_interface.txt => pm_qos_interface.rst} | 127 +-
Documentation/power/power_supply_class.rst | 282 +++++
Documentation/power/power_supply_class.txt | 231 ----
Documentation/power/powercap/powercap.rst | 257 ++++
Documentation/power/powercap/powercap.txt | 236 ----
.../regulator/{consumer.txt => consumer.rst} | 141 ++-
.../regulator/{design.txt => design.rst} | 9 +-
.../regulator/{machine.txt => machine.rst} | 47 +-
.../regulator/{overview.txt => overview.rst} | 57 +-
Documentation/power/regulator/regulator.rst | 32 +
Documentation/power/regulator/regulator.txt | 30 -
.../power/{runtime_pm.txt => runtime_pm.rst} | 234 ++--
Documentation/power/{s2ram.txt => s2ram.rst} | 20 +-
...hotplug.txt => suspend-and-cpuhotplug.rst} | 42 +-
...errupts.txt => suspend-and-interrupts.rst} | 2 +
...ap-files.txt => swsusp-and-swap-files.rst} | 17 +-
...{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} | 120 +-
Documentation/power/swsusp.rst | 501 ++++++++
Documentation/power/swsusp.txt | 446 -------
.../power/{tricks.txt => tricks.rst} | 6 +-
...serland-swsusp.txt => userland-swsusp.rst} | 55 +-
Documentation/power/{video.txt => video.rst} | 156 ++-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 119 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
Documentation/powerpc/ptrace.rst | 156 +++
Documentation/powerpc/ptrace.txt | 151 ---
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/process/4.Coding.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
Documentation/process/submit-checklist.rst | 2 +-
Documentation/process/submitting-drivers.rst | 2 +-
Documentation/riscv/index.rst | 17 +
Documentation/riscv/{pmu.txt => pmu.rst} | 98 +-
.../{completion.txt => completion.rst} | 38 +-
Documentation/scheduler/index.rst | 29 +
.../{sched-arch.txt => sched-arch.rst} | 18 +-
.../{sched-bwc.txt => sched-bwc.rst} | 30 +-
...{sched-deadline.txt => sched-deadline.rst} | 297 ++---
...ed-design-CFS.txt => sched-design-CFS.rst} | 17 +-
.../{sched-domains.txt => sched-domains.rst} | 8 +-
.../{sched-energy.txt => sched-energy.rst} | 53 +-
...-nice-design.txt => sched-nice-design.rst} | 6 +-
...{sched-rt-group.txt => sched-rt-group.rst} | 30 +-
.../{sched-stats.txt => sched-stats.rst} | 35 +-
Documentation/scheduler/text_files.rst | 5 +
Documentation/target/index.rst | 19 +
Documentation/target/scripts.rst | 11 +
Documentation/target/tcm_mod_builder.rst | 149 +++
Documentation/target/tcm_mod_builder.txt | 145 ---
.../{tcmu-design.txt => tcmu-design.rst} | 268 +++--
.../timers/{highres.txt => highres.rst} | 13 +-
Documentation/timers/{hpet.txt => hpet.rst} | 4 +-
.../timers/{hrtimers.txt => hrtimers.rst} | 6 +-
Documentation/timers/index.rst | 22 +
Documentation/timers/{NO_HZ.txt => no_hz.rst} | 40 +-
.../{timekeeping.txt => timekeeping.rst} | 3 +-
.../{timers-howto.txt => timers-howto.rst} | 15 +-
Documentation/trace/coresight-cpu-debug.txt | 2 +-
.../it_IT/kernel-hacking/hacking.rst | 4 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../it_IT/process/coding-style.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../translations/zh_CN/arm64/booting.txt | 4 +-
.../zh_CN/arm64/legacy_instructions.txt | 4 +-
.../translations/zh_CN/arm64/memory.txt | 4 +-
.../zh_CN/arm64/silicon-errata.txt | 4 +-
.../zh_CN/arm64/tagged-pointers.txt | 4 +-
.../translations/zh_CN/oops-tracing.txt | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
.../zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
.../zh_CN/process/submitting-drivers.rst | 2 +-
Documentation/virtual/kvm/api.txt | 2 +-
Documentation/vm/numa.rst | 6 +-
Documentation/vm/page_migration.rst | 2 +-
Documentation/vm/unevictable-lru.rst | 2 +-
....txt => convert_drivers_to_kernel_api.rst} | 109 +-
.../watchdog/{hpwdt.txt => hpwdt.rst} | 27 +-
Documentation/watchdog/index.rst | 25 +
.../watchdog/{mlx-wdt.txt => mlx-wdt.rst} | 24 +-
.../{pcwd-watchdog.txt => pcwd-watchdog.rst} | 13 +-
.../{watchdog-api.txt => watchdog-api.rst} | 76 +-
...kernel-api.txt => watchdog-kernel-api.rst} | 91 +-
.../watchdog/watchdog-parameters.rst | 736 ++++++++++++
.../watchdog/watchdog-parameters.txt | 410 -------
.../{watchdog-pm.txt => watchdog-pm.rst} | 3 +
Documentation/watchdog/{wdt.txt => wdt.rst} | 31 +-
.../x86/x86_64/fake-numa-for-cpusets.rst | 4 +-
Documentation/xilinx/{eemi.txt => eemi.rst} | 8 +-
Documentation/xilinx/index.rst | 17 +
Kconfig | 2 +-
MAINTAINERS | 34 +-
arch/arc/plat-eznps/Kconfig | 2 +-
arch/arm/Kconfig | 2 +-
arch/arm64/Kconfig | 2 +-
arch/arm64/include/asm/efi.h | 2 +-
arch/arm64/include/asm/image.h | 2 +-
arch/arm64/include/uapi/asm/sigcontext.h | 2 +-
arch/arm64/kernel/kexec_image.c | 2 +-
arch/c6x/Kconfig | 2 +-
arch/m68k/q40/README | 2 +-
arch/microblaze/Kconfig.debug | 2 +-
arch/microblaze/Kconfig.platform | 2 +-
arch/nds32/Kconfig | 2 +-
arch/openrisc/Kconfig | 2 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
arch/powerpc/sysdev/Kconfig | 2 +-
arch/riscv/Kconfig | 2 +-
arch/sh/Kconfig | 2 +-
arch/x86/Kconfig | 6 +-
block/Kconfig | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/block/Kconfig | 2 +-
drivers/cdrom/cdrom.c | 2 +-
drivers/firmware/Kconfig | 2 +-
drivers/gpu/drm/Kconfig | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 2 +-
drivers/ide/Kconfig | 20 +-
drivers/ide/ide-cd.c | 2 +-
drivers/md/Kconfig | 2 +-
drivers/md/dm-init.c | 2 +-
drivers/md/dm-raid.c | 2 +-
drivers/media/usb/dvb-usb-v2/anysee.c | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
drivers/mtd/devices/Kconfig | 2 +-
drivers/net/ethernet/smsc/Kconfig | 6 +-
drivers/net/wireless/intel/iwlegacy/Kconfig | 4 +-
drivers/net/wireless/intel/iwlwifi/Kconfig | 2 +-
drivers/opp/Kconfig | 2 +-
drivers/parport/Kconfig | 2 +-
drivers/pcmcia/ds.c | 2 +-
drivers/power/supply/power_supply_core.c | 2 +-
drivers/regulator/core.c | 2 +-
drivers/scsi/Kconfig | 4 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/staging/sm750fb/Kconfig | 2 +-
drivers/tty/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
drivers/usb/misc/Kconfig | 4 +-
drivers/video/fbdev/Kconfig | 38 +-
drivers/video/fbdev/matrox/matroxfb_base.c | 2 +-
drivers/video/fbdev/pxafb.c | 2 +-
drivers/video/fbdev/sh7760fb.c | 2 +-
drivers/watchdog/Kconfig | 6 +-
drivers/watchdog/smsc37b787_wdt.c | 2 +-
include/linux/cgroup-defs.h | 2 +-
include/linux/fault-inject.h | 2 +-
include/linux/interrupt.h | 2 +-
include/linux/iopoll.h | 4 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/pci.h | 2 +-
include/linux/pm.h | 2 +-
include/linux/regmap.h | 4 +-
include/linux/rwsem.h | 2 +-
include/pcmcia/ds.h | 2 +-
include/pcmcia/ss.h | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
include/uapi/linux/bpf.h | 2 +-
init/Kconfig | 8 +-
kernel/cgroup/cpuset.c | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
kernel/power/Kconfig | 6 +-
kernel/sched/deadline.c | 2 +-
lib/Kconfig.debug | 6 +-
net/bridge/netfilter/Kconfig | 2 +-
net/ipv4/netfilter/Kconfig | 2 +-
net/ipv6/netfilter/Kconfig | 2 +-
net/netfilter/Kconfig | 16 +-
net/tipc/Kconfig | 2 +-
net/wireless/Kconfig | 2 +-
scripts/Kbuild.include | 4 +-
scripts/Makefile.host | 2 +-
scripts/checkpatch.pl | 8 +-
scripts/documentation-file-ref-check | 2 +-
scripts/kconfig/symbol.c | 2 +-
.../tests/err_recursive_dep/expected_stderr | 14 +-
security/device_cgroup.c | 2 +-
sound/oss/dmasound/Kconfig | 6 +-
sound/soc/sof/ops.h | 2 +-
tools/include/uapi/linux/bpf.h | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
392 files changed, 12880 insertions(+), 9641 deletions(-)
rename Documentation/EDID/{HOWTO.txt => howto.rst} (83%)
rename Documentation/aoe/{aoe.txt => aoe.rst} (79%)
create mode 100644 Documentation/aoe/examples.rst
create mode 100644 Documentation/aoe/index.rst
rename Documentation/aoe/{todo.txt => todo.rst} (98%)
rename Documentation/arm64/{acpi_object_usage.txt => acpi_object_usage.rst} (84%)
rename Documentation/arm64/{arm-acpi.txt => arm-acpi.rst} (86%)
rename Documentation/arm64/{booting.txt => booting.rst} (86%)
rename Documentation/arm64/{cpu-feature-registers.txt => cpu-feature-registers.rst} (65%)
rename Documentation/arm64/{elf_hwcaps.txt => elf_hwcaps.rst} (92%)
rename Documentation/arm64/{hugetlbpage.txt => hugetlbpage.rst} (86%)
create mode 100644 Documentation/arm64/index.rst
rename Documentation/arm64/{legacy_instructions.txt => legacy_instructions.rst} (73%)
create mode 100644 Documentation/arm64/memory.rst
delete mode 100644 Documentation/arm64/memory.txt
rename Documentation/arm64/{pointer-authentication.txt => pointer-authentication.rst} (99%)
rename Documentation/arm64/{silicon-errata.txt => silicon-errata.rst} (55%)
rename Documentation/arm64/{sve.txt => sve.rst} (98%)
rename Documentation/arm64/{tagged-pointers.txt => tagged-pointers.rst} (94%)
delete mode 100644 Documentation/cdrom/Makefile
create mode 100644 Documentation/cdrom/cdrom-standard.rst
delete mode 100644 Documentation/cdrom/cdrom-standard.tex
rename Documentation/cdrom/{ide-cd => ide-cd.rst} (82%)
create mode 100644 Documentation/cdrom/index.rst
rename Documentation/cdrom/{packet-writing.txt => packet-writing.rst} (91%)
rename Documentation/cgroup-v1/{blkio-controller.txt => blkio-controller.rst} (89%)
rename Documentation/cgroup-v1/{cgroups.txt => cgroups.rst} (88%)
rename Documentation/cgroup-v1/{cpuacct.txt => cpuacct.rst} (90%)
rename Documentation/cgroup-v1/{cpusets.txt => cpusets.rst} (90%)
rename Documentation/cgroup-v1/{devices.txt => devices.rst} (88%)
rename Documentation/cgroup-v1/{freezer-subsystem.txt => freezer-subsystem.rst} (95%)
rename Documentation/cgroup-v1/{hugetlb.txt => hugetlb.rst} (70%)
create mode 100644 Documentation/cgroup-v1/index.rst
rename Documentation/cgroup-v1/{memcg_test.txt => memcg_test.rst} (62%)
rename Documentation/cgroup-v1/{memory.txt => memory.rst} (71%)
rename Documentation/cgroup-v1/{net_cls.txt => net_cls.rst} (50%)
rename Documentation/cgroup-v1/{net_prio.txt => net_prio.rst} (71%)
rename Documentation/cgroup-v1/{pids.txt => pids.rst} (62%)
rename Documentation/cgroup-v1/{rdma.txt => rdma.rst} (79%)
rename Documentation/device-mapper/{cache-policies.txt => cache-policies.rst} (94%)
rename Documentation/device-mapper/{cache.txt => cache.rst} (61%)
rename Documentation/device-mapper/{delay.txt => delay.rst} (53%)
rename Documentation/device-mapper/{dm-crypt.txt => dm-crypt.rst} (87%)
rename Documentation/device-mapper/{dm-flakey.txt => dm-flakey.rst} (60%)
rename Documentation/device-mapper/{dm-init.txt => dm-init.rst} (69%)
rename Documentation/device-mapper/{dm-integrity.txt => dm-integrity.rst} (90%)
rename Documentation/device-mapper/{dm-io.txt => dm-io.rst} (92%)
rename Documentation/device-mapper/{dm-log.txt => dm-log.rst} (90%)
rename Documentation/device-mapper/{dm-queue-length.txt => dm-queue-length.rst} (76%)
rename Documentation/device-mapper/{dm-raid.txt => dm-raid.rst} (71%)
rename Documentation/device-mapper/{dm-service-time.txt => dm-service-time.rst} (60%)
create mode 100644 Documentation/device-mapper/dm-uevent.rst
delete mode 100644 Documentation/device-mapper/dm-uevent.txt
rename Documentation/device-mapper/{dm-zoned.txt => dm-zoned.rst} (97%)
rename Documentation/device-mapper/{era.txt => era.rst} (70%)
create mode 100644 Documentation/device-mapper/index.rst
rename Documentation/device-mapper/{kcopyd.txt => kcopyd.rst} (93%)
create mode 100644 Documentation/device-mapper/linear.rst
delete mode 100644 Documentation/device-mapper/linear.txt
rename Documentation/device-mapper/{log-writes.txt => log-writes.rst} (61%)
rename Documentation/device-mapper/{persistent-data.txt => persistent-data.rst} (98%)
rename Documentation/device-mapper/{snapshot.txt => snapshot.rst} (62%)
rename Documentation/device-mapper/{statistics.txt => statistics.rst} (87%)
create mode 100644 Documentation/device-mapper/striped.rst
delete mode 100644 Documentation/device-mapper/striped.txt
rename Documentation/device-mapper/{switch.txt => switch.rst} (84%)
rename Documentation/device-mapper/{thin-provisioning.txt => thin-provisioning.rst} (92%)
rename Documentation/device-mapper/{unstriped.txt => unstriped.rst} (60%)
rename Documentation/device-mapper/{verity.txt => verity.rst} (98%)
rename Documentation/device-mapper/{writecache.txt => writecache.rst} (96%)
rename Documentation/device-mapper/{zero.txt => zero.rst} (83%)
rename Documentation/{pps/pps.txt => driver-api/pps.rst} (89%)
rename Documentation/{ptp/ptp.txt => driver-api/ptp.rst} (88%)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
create mode 100644 Documentation/fault-injection/nvme-fault-injection.rst
delete mode 100644 Documentation/fault-injection/nvme-fault-injection.txt
create mode 100644 Documentation/fault-injection/provoke-crashes.rst
delete mode 100644 Documentation/fault-injection/provoke-crashes.txt
rename Documentation/fb/{api.txt => api.rst} (97%)
rename Documentation/fb/{arkfb.txt => arkfb.rst} (92%)
rename Documentation/fb/{aty128fb.txt => aty128fb.rst} (61%)
rename Documentation/fb/{cirrusfb.txt => cirrusfb.rst} (75%)
rename Documentation/fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} (50%)
rename Documentation/fb/{deferred_io.txt => deferred_io.rst} (86%)
rename Documentation/fb/{efifb.txt => efifb.rst} (75%)
rename Documentation/fb/{ep93xx-fb.txt => ep93xx-fb.rst} (85%)
rename Documentation/fb/{fbcon.txt => fbcon.rst} (69%)
rename Documentation/fb/{framebuffer.txt => framebuffer.rst} (92%)
rename Documentation/fb/{gxfb.txt => gxfb.rst} (60%)
create mode 100644 Documentation/fb/index.rst
rename Documentation/fb/{intel810.txt => intel810.rst} (83%)
rename Documentation/fb/{intelfb.txt => intelfb.rst} (73%)
rename Documentation/fb/{internals.txt => internals.rst} (82%)
rename Documentation/fb/{lxfb.txt => lxfb.rst} (60%)
create mode 100644 Documentation/fb/matroxfb.rst
delete mode 100644 Documentation/fb/matroxfb.txt
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
create mode 100644 Documentation/fb/pvr2fb.rst
delete mode 100644 Documentation/fb/pvr2fb.txt
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
create mode 100644 Documentation/fb/sh7760fb.rst
delete mode 100644 Documentation/fb/sh7760fb.txt
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
create mode 100644 Documentation/fb/sstfb.rst
delete mode 100644 Documentation/fb/sstfb.txt
rename Documentation/fb/{tgafb.txt => tgafb.rst} (71%)
rename Documentation/fb/{tridentfb.txt => tridentfb.rst} (70%)
rename Documentation/fb/{udlfb.txt => udlfb.rst} (77%)
rename Documentation/fb/{uvesafb.txt => uvesafb.rst} (52%)
rename Documentation/fb/{vesafb.txt => vesafb.rst} (57%)
create mode 100644 Documentation/fb/viafb.rst
delete mode 100644 Documentation/fb/viafb.txt
rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%)
rename Documentation/fpga/{dfl.txt => dfl.rst} (89%)
create mode 100644 Documentation/fpga/index.rst
create mode 100644 Documentation/ide/changelogs.rst
rename Documentation/ide/{ide-tape.txt => ide-tape.rst} (83%)
rename Documentation/ide/{ide.txt => ide.rst} (72%)
create mode 100644 Documentation/ide/index.rst
rename Documentation/ide/{warm-plug-howto.txt => warm-plug-howto.rst} (61%)
rename Documentation/kbuild/{headers_install.txt => headers_install.rst} (96%)
create mode 100644 Documentation/kbuild/index.rst
create mode 100644 Documentation/kbuild/issues.rst
rename Documentation/kbuild/{kbuild.txt => kbuild.rst} (72%)
rename Documentation/kbuild/{kconfig-language.txt => kconfig-language.rst} (85%)
rename Documentation/kbuild/{kconfig-macro-language.txt => kconfig-macro-language.rst} (94%)
rename Documentation/kbuild/{kconfig.txt => kconfig.rst} (80%)
rename Documentation/kbuild/{makefiles.txt => makefiles.rst} (83%)
rename Documentation/kbuild/{modules.txt => modules.rst} (84%)
create mode 100644 Documentation/kdump/index.rst
rename Documentation/kdump/{kdump.txt => kdump.rst} (91%)
rename Documentation/kdump/{vmcoreinfo.txt => vmcoreinfo.rst} (95%)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
create mode 100644 Documentation/locking/lockstat.rst
delete mode 100644 Documentation/locking/lockstat.txt
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
create mode 100644 Documentation/mic/index.rst
rename Documentation/mic/{mic_overview.txt => mic_overview.rst} (96%)
rename Documentation/mic/{scif_overview.txt => scif_overview.rst} (76%)
rename Documentation/netlabel/{cipso_ipv4.txt => cipso_ipv4.rst} (87%)
create mode 100644 Documentation/netlabel/draft_ietf.rst
create mode 100644 Documentation/netlabel/index.rst
rename Documentation/netlabel/{introduction.txt => introduction.rst} (91%)
rename Documentation/netlabel/{lsm_interface.txt => lsm_interface.rst} (88%)
rename Documentation/pcmcia/{devicetable.txt => devicetable.rst} (97%)
rename Documentation/pcmcia/{driver-changes.txt => driver-changes.rst} (90%)
rename Documentation/pcmcia/{driver.txt => driver.rst} (66%)
create mode 100644 Documentation/pcmcia/index.rst
rename Documentation/pcmcia/{locking.txt => locking.rst} (81%)
rename Documentation/power/{apm-acpi.txt => apm-acpi.rst} (87%)
rename Documentation/power/{basic-pm-debugging.txt => basic-pm-debugging.rst} (87%)
rename Documentation/power/{charger-manager.txt => charger-manager.rst} (78%)
rename Documentation/power/{drivers-testing.txt => drivers-testing.rst} (86%)
rename Documentation/power/{energy-model.txt => energy-model.rst} (74%)
rename Documentation/power/{freezing-of-tasks.txt => freezing-of-tasks.rst} (75%)
create mode 100644 Documentation/power/index.rst
rename Documentation/power/{interface.txt => interface.rst} (84%)
rename Documentation/power/{opp.txt => opp.rst} (78%)
rename Documentation/power/{pci.txt => pci.rst} (97%)
rename Documentation/power/{pm_qos_interface.txt => pm_qos_interface.rst} (62%)
create mode 100644 Documentation/power/power_supply_class.rst
delete mode 100644 Documentation/power/power_supply_class.txt
create mode 100644 Documentation/power/powercap/powercap.rst
delete mode 100644 Documentation/power/powercap/powercap.txt
rename Documentation/power/regulator/{consumer.txt => consumer.rst} (61%)
rename Documentation/power/regulator/{design.txt => design.rst} (86%)
rename Documentation/power/regulator/{machine.txt => machine.rst} (75%)
rename Documentation/power/regulator/{overview.txt => overview.rst} (79%)
create mode 100644 Documentation/power/regulator/regulator.rst
delete mode 100644 Documentation/power/regulator/regulator.txt
rename Documentation/power/{runtime_pm.txt => runtime_pm.rst} (89%)
rename Documentation/power/{s2ram.txt => s2ram.rst} (92%)
rename Documentation/power/{suspend-and-cpuhotplug.txt => suspend-and-cpuhotplug.rst} (90%)
rename Documentation/power/{suspend-and-interrupts.txt => suspend-and-interrupts.rst} (98%)
rename Documentation/power/{swsusp-and-swap-files.txt => swsusp-and-swap-files.rst} (83%)
rename Documentation/power/{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} (67%)
create mode 100644 Documentation/power/swsusp.rst
delete mode 100644 Documentation/power/swsusp.txt
rename Documentation/power/{tricks.txt => tricks.rst} (93%)
rename Documentation/power/{userland-swsusp.txt => userland-swsusp.rst} (85%)
rename Documentation/power/{video.txt => video.rst} (56%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
create mode 100644 Documentation/powerpc/ptrace.rst
delete mode 100644 Documentation/powerpc/ptrace.txt
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
create mode 100644 Documentation/riscv/index.rst
rename Documentation/riscv/{pmu.txt => pmu.rst} (77%)
rename Documentation/scheduler/{completion.txt => completion.rst} (94%)
create mode 100644 Documentation/scheduler/index.rst
rename Documentation/scheduler/{sched-arch.txt => sched-arch.rst} (81%)
rename Documentation/scheduler/{sched-bwc.txt => sched-bwc.rst} (90%)
rename Documentation/scheduler/{sched-deadline.txt => sched-deadline.rst} (88%)
rename Documentation/scheduler/{sched-design-CFS.txt => sched-design-CFS.rst} (97%)
rename Documentation/scheduler/{sched-domains.txt => sched-domains.rst} (97%)
rename Documentation/scheduler/{sched-energy.txt => sched-energy.rst} (96%)
rename Documentation/scheduler/{sched-nice-design.txt => sched-nice-design.rst} (98%)
rename Documentation/scheduler/{sched-rt-group.txt => sched-rt-group.rst} (95%)
rename Documentation/scheduler/{sched-stats.txt => sched-stats.rst} (91%)
create mode 100644 Documentation/scheduler/text_files.rst
create mode 100644 Documentation/target/index.rst
create mode 100644 Documentation/target/scripts.rst
create mode 100644 Documentation/target/tcm_mod_builder.rst
delete mode 100644 Documentation/target/tcm_mod_builder.txt
rename Documentation/target/{tcmu-design.txt => tcmu-design.rst} (69%)
rename Documentation/timers/{highres.txt => highres.rst} (98%)
rename Documentation/timers/{hpet.txt => hpet.rst} (91%)
rename Documentation/timers/{hrtimers.txt => hrtimers.rst} (98%)
create mode 100644 Documentation/timers/index.rst
rename Documentation/timers/{NO_HZ.txt => no_hz.rst} (93%)
rename Documentation/timers/{timekeeping.txt => timekeeping.rst} (98%)
rename Documentation/timers/{timers-howto.txt => timers-howto.rst} (93%)
rename Documentation/watchdog/{convert_drivers_to_kernel_api.txt => convert_drivers_to_kernel_api.rst} (75%)
rename Documentation/watchdog/{hpwdt.txt => hpwdt.rst} (78%)
create mode 100644 Documentation/watchdog/index.rst
rename Documentation/watchdog/{mlx-wdt.txt => mlx-wdt.rst} (78%)
rename Documentation/watchdog/{pcwd-watchdog.txt => pcwd-watchdog.rst} (89%)
rename Documentation/watchdog/{watchdog-api.txt => watchdog-api.rst} (80%)
rename Documentation/watchdog/{watchdog-kernel-api.txt => watchdog-kernel-api.rst} (90%)
create mode 100644 Documentation/watchdog/watchdog-parameters.rst
delete mode 100644 Documentation/watchdog/watchdog-parameters.txt
rename Documentation/watchdog/{watchdog-pm.txt => watchdog-pm.rst} (92%)
rename Documentation/watchdog/{wdt.txt => wdt.rst} (68%)
rename Documentation/xilinx/{eemi.txt => eemi.rst} (92%)
create mode 100644 Documentation/xilinx/index.rst
--
2.21.0
^ permalink raw reply [flat|nested] 39+ messages in thread
* [PATCH v4 01/28] docs: aoe: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst Mauro Carvalho Chehab
` (23 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
There are only two files within Documentation/aoe dir that are
documentation. The remaining ones are examples and shell
scripts.
Convert the two AoE files to ReST format, and add the others
as literal, as they're part of the documentation.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/aoe/{aoe.txt => aoe.rst} | 63 +++++++++++++-----------
Documentation/aoe/examples.rst | 23 +++++++++
Documentation/aoe/index.rst | 19 +++++++
Documentation/aoe/{todo.txt => todo.rst} | 3 ++
Documentation/aoe/udev.txt | 2 +-
5 files changed, 81 insertions(+), 29 deletions(-)
rename Documentation/aoe/{aoe.txt => aoe.rst} (79%)
create mode 100644 Documentation/aoe/examples.rst
create mode 100644 Documentation/aoe/index.rst
rename Documentation/aoe/{todo.txt => todo.rst} (98%)
diff --git a/Documentation/aoe/aoe.txt b/Documentation/aoe/aoe.rst
similarity index 79%
rename from Documentation/aoe/aoe.txt
rename to Documentation/aoe/aoe.rst
index c71487d399d1..58747ecec71d 100644
--- a/Documentation/aoe/aoe.txt
+++ b/Documentation/aoe/aoe.rst
@@ -1,3 +1,6 @@
+Introduction
+============
+
ATA over Ethernet is a network protocol that provides simple access to
block storage on the LAN.
@@ -22,7 +25,8 @@ document the use of the driver and are not necessary if you install
the aoetools.
-CREATING DEVICE NODES
+Creating Device Nodes
+=====================
Users of udev should find the block device nodes created
automatically, but to create all the necessary device nodes, use the
@@ -38,7 +42,8 @@ CREATING DEVICE NODES
confusing when an AoE device is not present the first time the a
command is run but appears a second later.
-USING DEVICE NODES
+Using Device Nodes
+==================
"cat /dev/etherd/err" blocks, waiting for error diagnostic output,
like any retransmitted packets.
@@ -55,7 +60,7 @@ USING DEVICE NODES
by sysfs counterparts. Using the commands in aoetools insulates
users from these implementation details.
- The block devices are named like this:
+ The block devices are named like this::
e{shelf}.{slot}
e{shelf}.{slot}p{part}
@@ -64,7 +69,8 @@ USING DEVICE NODES
first shelf (shelf address zero). That's the whole disk. The first
partition on that disk would be "e0.2p1".
-USING SYSFS
+Using sysfs
+===========
Each aoe block device in /sys/block has the extra attributes of
state, mac, and netif. The state attribute is "up" when the device
@@ -78,29 +84,29 @@ USING SYSFS
There is a script in this directory that formats this information in
a convenient way. Users with aoetools should use the aoe-stat
- command.
+ command::
- root@makki root# sh Documentation/aoe/status.sh
- e10.0 eth3 up
- e10.1 eth3 up
- e10.2 eth3 up
- e10.3 eth3 up
- e10.4 eth3 up
- e10.5 eth3 up
- e10.6 eth3 up
- e10.7 eth3 up
- e10.8 eth3 up
- e10.9 eth3 up
- e4.0 eth1 up
- e4.1 eth1 up
- e4.2 eth1 up
- e4.3 eth1 up
- e4.4 eth1 up
- e4.5 eth1 up
- e4.6 eth1 up
- e4.7 eth1 up
- e4.8 eth1 up
- e4.9 eth1 up
+ root@makki root# sh Documentation/aoe/status.sh
+ e10.0 eth3 up
+ e10.1 eth3 up
+ e10.2 eth3 up
+ e10.3 eth3 up
+ e10.4 eth3 up
+ e10.5 eth3 up
+ e10.6 eth3 up
+ e10.7 eth3 up
+ e10.8 eth3 up
+ e10.9 eth3 up
+ e4.0 eth1 up
+ e4.1 eth1 up
+ e4.2 eth1 up
+ e4.3 eth1 up
+ e4.4 eth1 up
+ e4.5 eth1 up
+ e4.6 eth1 up
+ e4.7 eth1 up
+ e4.8 eth1 up
+ e4.9 eth1 up
Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver
option discussed below) instead of /dev/etherd/interfaces to limit
@@ -113,12 +119,13 @@ USING SYSFS
for this purpose. You can also directly use the
/dev/etherd/discover special file described above.
-DRIVER OPTIONS
+Driver Options
+==============
There is a boot option for the built-in aoe driver and a
corresponding module parameter, aoe_iflist. Without this option,
all network interfaces may be used for ATA over Ethernet. Here is a
- usage example for the module parameter.
+ usage example for the module parameter::
modprobe aoe_iflist="eth1 eth3"
diff --git a/Documentation/aoe/examples.rst b/Documentation/aoe/examples.rst
new file mode 100644
index 000000000000..91f3198e52c1
--- /dev/null
+++ b/Documentation/aoe/examples.rst
@@ -0,0 +1,23 @@
+Example of udev rules
+---------------------
+
+ .. include:: udev.txt
+ :literal:
+
+Example of udev install rules script
+------------------------------------
+
+ .. literalinclude:: udev-install.sh
+ :language: shell
+
+Example script to get status
+----------------------------
+
+ .. literalinclude:: status.sh
+ :language: shell
+
+Example of AoE autoload script
+------------------------------
+
+ .. literalinclude:: autoload.sh
+ :language: shell
diff --git a/Documentation/aoe/index.rst b/Documentation/aoe/index.rst
new file mode 100644
index 000000000000..4394b9b7913c
--- /dev/null
+++ b/Documentation/aoe/index.rst
@@ -0,0 +1,19 @@
+:orphan:
+
+=======================
+ATA over Ethernet (AoE)
+=======================
+
+.. toctree::
+ :maxdepth: 1
+
+ aoe
+ todo
+ examples
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/aoe/todo.txt b/Documentation/aoe/todo.rst
similarity index 98%
rename from Documentation/aoe/todo.txt
rename to Documentation/aoe/todo.rst
index c09dfad4aed8..dea8db5a33e1 100644
--- a/Documentation/aoe/todo.txt
+++ b/Documentation/aoe/todo.rst
@@ -1,3 +1,6 @@
+TODO
+====
+
There is a potential for deadlock when allocating a struct sk_buff for
data that needs to be written out to aoe storage. If the data is
being written from a dirty page in order to free that page, and if
diff --git a/Documentation/aoe/udev.txt b/Documentation/aoe/udev.txt
index 1f06daf03f5b..54feda5a0772 100644
--- a/Documentation/aoe/udev.txt
+++ b/Documentation/aoe/udev.txt
@@ -11,7 +11,7 @@
# udev_rules="/etc/udev/rules.d/"
# bash# ls /etc/udev/rules.d/
# 10-wacom.rules 50-udev.rules
-# bash# cp /path/to/linux-2.6.xx/Documentation/aoe/udev.txt \
+# bash# cp /path/to/linux/Documentation/aoe/udev.txt \
# /etc/udev/rules.d/60-aoe.rules
#
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 01/28] docs: aoe: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-14 20:10 ` Jonathan Corbet
2019-06-12 17:52 ` [PATCH v4 04/28] docs: cdrom: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (22 subsequent siblings)
24 siblings, 1 reply; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Catalin Marinas, Will Deacon, Harry Wei,
Alex Shi, Paolo Bonzini, Radim Krčmář,
Ard Biesheuvel, linux-arm-kernel, kvm, linux-efi
The documentation is in a format that is very close to ReST format.
The conversion is actually:
- add blank lines in order to identify paragraphs;
- fixing tables markups;
- adding some lists markups;
- marking literal blocks;
- adjust some title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...object_usage.txt => acpi_object_usage.rst} | 288 ++++++++++++------
.../arm64/{arm-acpi.txt => arm-acpi.rst} | 155 +++++-----
.../arm64/{booting.txt => booting.rst} | 91 ++++--
...egisters.txt => cpu-feature-registers.rst} | 204 +++++++------
.../arm64/{elf_hwcaps.txt => elf_hwcaps.rst} | 56 +---
.../{hugetlbpage.txt => hugetlbpage.rst} | 7 +-
Documentation/arm64/index.rst | 28 ++
...structions.txt => legacy_instructions.rst} | 43 ++-
Documentation/arm64/memory.rst | 98 ++++++
Documentation/arm64/memory.txt | 97 ------
...ication.txt => pointer-authentication.rst} | 2 +
...{silicon-errata.txt => silicon-errata.rst} | 65 +++-
Documentation/arm64/{sve.txt => sve.rst} | 12 +-
...agged-pointers.txt => tagged-pointers.rst} | 6 +-
.../translations/zh_CN/arm64/booting.txt | 4 +-
.../zh_CN/arm64/legacy_instructions.txt | 4 +-
.../translations/zh_CN/arm64/memory.txt | 4 +-
.../zh_CN/arm64/silicon-errata.txt | 4 +-
.../zh_CN/arm64/tagged-pointers.txt | 4 +-
Documentation/virtual/kvm/api.txt | 2 +-
arch/arm64/include/asm/efi.h | 2 +-
arch/arm64/include/asm/image.h | 2 +-
arch/arm64/include/uapi/asm/sigcontext.h | 2 +-
arch/arm64/kernel/kexec_image.c | 2 +-
24 files changed, 703 insertions(+), 479 deletions(-)
rename Documentation/arm64/{acpi_object_usage.txt => acpi_object_usage.rst} (84%)
rename Documentation/arm64/{arm-acpi.txt => arm-acpi.rst} (86%)
rename Documentation/arm64/{booting.txt => booting.rst} (86%)
rename Documentation/arm64/{cpu-feature-registers.txt => cpu-feature-registers.rst} (65%)
rename Documentation/arm64/{elf_hwcaps.txt => elf_hwcaps.rst} (92%)
rename Documentation/arm64/{hugetlbpage.txt => hugetlbpage.rst} (86%)
create mode 100644 Documentation/arm64/index.rst
rename Documentation/arm64/{legacy_instructions.txt => legacy_instructions.rst} (73%)
create mode 100644 Documentation/arm64/memory.rst
delete mode 100644 Documentation/arm64/memory.txt
rename Documentation/arm64/{pointer-authentication.txt => pointer-authentication.rst} (99%)
rename Documentation/arm64/{silicon-errata.txt => silicon-errata.rst} (55%)
rename Documentation/arm64/{sve.txt => sve.rst} (98%)
rename Documentation/arm64/{tagged-pointers.txt => tagged-pointers.rst} (94%)
diff --git a/Documentation/arm64/acpi_object_usage.txt b/Documentation/arm64/acpi_object_usage.rst
similarity index 84%
rename from Documentation/arm64/acpi_object_usage.txt
rename to Documentation/arm64/acpi_object_usage.rst
index c77010c5c1f0..d51b69dc624d 100644
--- a/Documentation/arm64/acpi_object_usage.txt
+++ b/Documentation/arm64/acpi_object_usage.rst
@@ -1,5 +1,7 @@
+===========
ACPI Tables
------------
+===========
+
The expectations of individual ACPI tables are discussed in the list that
follows.
@@ -11,54 +13,71 @@ outside of the UEFI Forum (see Section 5.2.6 of the specification).
For ACPI on arm64, tables also fall into the following categories:
- -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
+ - Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
- -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
+ - Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
- -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
+ - Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO,
TCPA, TPM2, UEFI, XENV
- -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
+ - Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
+====== ========================================================================
Table Usage for ARMv8 Linux
------ ----------------------------------------------------------------
+====== ========================================================================
BERT Section 18.3 (signature == "BERT")
- == Boot Error Record Table ==
+
+ **Boot Error Record Table**
+
Must be supplied if RAS support is provided by the platform. It
is recommended this table be supplied.
BOOT Signature Reserved (signature == "BOOT")
- == simple BOOT flag table ==
+
+ **simple BOOT flag table**
+
Microsoft only table, will not be supported.
BGRT Section 5.2.22 (signature == "BGRT")
- == Boot Graphics Resource Table ==
+
+ **Boot Graphics Resource Table**
+
Optional, not currently supported, with no real use-case for an
ARM server.
CPEP Section 5.2.18 (signature == "CPEP")
- == Corrected Platform Error Polling table ==
+
+ **Corrected Platform Error Polling table**
+
Optional, not currently supported, and not recommended until such
time as ARM-compatible hardware is available, and the specification
suitably modified.
CSRT Signature Reserved (signature == "CSRT")
- == Core System Resources Table ==
+
+ **Core System Resources Table**
+
Optional, not currently supported.
DBG2 Signature Reserved (signature == "DBG2")
- == DeBuG port table 2 ==
+
+ **DeBuG port table 2**
+
License has changed and should be usable. Optional if used instead
of earlycon=<device> on the command line.
DBGP Signature Reserved (signature == "DBGP")
- == DeBuG Port table ==
+
+ **DeBuG Port table**
+
Microsoft only table, will not be supported.
DSDT Section 5.2.11.1 (signature == "DSDT")
- == Differentiated System Description Table ==
+
+ **Differentiated System Description Table**
+
A DSDT is required; see also SSDT.
ACPI tables contain only one DSDT but can contain one or more SSDTs,
@@ -66,22 +85,30 @@ DSDT Section 5.2.11.1 (signature == "DSDT")
but cannot modify or replace anything in the DSDT.
DMAR Signature Reserved (signature == "DMAR")
- == DMA Remapping table ==
+
+ **DMA Remapping table**
+
x86 only table, will not be supported.
DRTM Signature Reserved (signature == "DRTM")
- == Dynamic Root of Trust for Measurement table ==
+
+ **Dynamic Root of Trust for Measurement table**
+
Optional, not currently supported.
ECDT Section 5.2.16 (signature == "ECDT")
- == Embedded Controller Description Table ==
+
+ **Embedded Controller Description Table**
+
Optional, not currently supported, but could be used on ARM if and
only if one uses the GPE_BIT field to represent an IRQ number, since
there are no GPE blocks defined in hardware reduced mode. This would
need to be modified in the ACPI specification.
EINJ Section 18.6 (signature == "EINJ")
- == Error Injection table ==
+
+ **Error Injection table**
+
This table is very useful for testing platform response to error
conditions; it allows one to inject an error into the system as
if it had actually occurred. However, this table should not be
@@ -89,27 +116,35 @@ EINJ Section 18.6 (signature == "EINJ")
and executed with the ACPICA tools only during testing.
ERST Section 18.5 (signature == "ERST")
- == Error Record Serialization Table ==
+
+ **Error Record Serialization Table**
+
On a platform supports RAS, this table must be supplied if it is not
UEFI-based; if it is UEFI-based, this table may be supplied. When this
table is not present, UEFI run time service will be utilized to save
and retrieve hardware error information to and from a persistent store.
ETDT Signature Reserved (signature == "ETDT")
- == Event Timer Description Table ==
+
+ **Event Timer Description Table**
+
Obsolete table, will not be supported.
FACS Section 5.2.10 (signature == "FACS")
- == Firmware ACPI Control Structure ==
+
+ **Firmware ACPI Control Structure**
+
It is unlikely that this table will be terribly useful. If it is
provided, the Global Lock will NOT be used since it is not part of
the hardware reduced profile, and only 64-bit address fields will
be considered valid.
FADT Section 5.2.9 (signature == "FACP")
- == Fixed ACPI Description Table ==
+
+ **Fixed ACPI Description Table**
Required for arm64.
+
The HW_REDUCED_ACPI flag must be set. All of the fields that are
to be ignored when HW_REDUCED_ACPI is set are expected to be set to
zero.
@@ -118,22 +153,28 @@ FADT Section 5.2.9 (signature == "FACP")
used, not FIRMWARE_CTRL.
If PSCI is used (as is recommended), make sure that ARM_BOOT_ARCH is
- filled in properly -- that the PSCI_COMPLIANT flag is set and that
+ filled in properly - that the PSCI_COMPLIANT flag is set and that
PSCI_USE_HVC is set or unset as needed (see table 5-37).
For the DSDT that is also required, the X_DSDT field is to be used,
not the DSDT field.
FPDT Section 5.2.23 (signature == "FPDT")
- == Firmware Performance Data Table ==
+
+ **Firmware Performance Data Table**
+
Optional, not currently supported.
GTDT Section 5.2.24 (signature == "GTDT")
- == Generic Timer Description Table ==
+
+ **Generic Timer Description Table**
+
Required for arm64.
HEST Section 18.3.2 (signature == "HEST")
- == Hardware Error Source Table ==
+
+ **Hardware Error Source Table**
+
ARM-specific error sources have been defined; please use those or the
PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER
Bridge), or use type 9 (Generic Hardware Error Source). Firmware first
@@ -144,122 +185,174 @@ HEST Section 18.3.2 (signature == "HEST")
is recommended this table be supplied.
HPET Signature Reserved (signature == "HPET")
- == High Precision Event timer Table ==
+
+ **High Precision Event timer Table**
+
x86 only table, will not be supported.
IBFT Signature Reserved (signature == "IBFT")
- == iSCSI Boot Firmware Table ==
+
+ **iSCSI Boot Firmware Table**
+
Microsoft defined table, support TBD.
IORT Signature Reserved (signature == "IORT")
- == Input Output Remapping Table ==
+
+ **Input Output Remapping Table**
+
arm64 only table, required in order to describe IO topology, SMMUs,
and GIC ITSs, and how those various components are connected together,
such as identifying which components are behind which SMMUs/ITSs.
This table will only be required on certain SBSA platforms (e.g.,
- when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it
+ when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it
remains optional.
IVRS Signature Reserved (signature == "IVRS")
- == I/O Virtualization Reporting Structure ==
+
+ **I/O Virtualization Reporting Structure**
+
x86_64 (AMD) only table, will not be supported.
LPIT Signature Reserved (signature == "LPIT")
- == Low Power Idle Table ==
+
+ **Low Power Idle Table**
+
x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor
descriptions and power states on ARM platforms should use the DSDT
and define processor container devices (_HID ACPI0010, Section 8.4,
and more specifically 8.4.3 and and 8.4.4).
MADT Section 5.2.12 (signature == "APIC")
- == Multiple APIC Description Table ==
+
+ **Multiple APIC Description Table**
+
Required for arm64. Only the GIC interrupt controller structures
should be used (types 0xA - 0xF).
MCFG Signature Reserved (signature == "MCFG")
- == Memory-mapped ConFiGuration space ==
+
+ **Memory-mapped ConFiGuration space**
+
If the platform supports PCI/PCIe, an MCFG table is required.
MCHI Signature Reserved (signature == "MCHI")
- == Management Controller Host Interface table ==
+
+ **Management Controller Host Interface table**
+
Optional, not currently supported.
MPST Section 5.2.21 (signature == "MPST")
- == Memory Power State Table ==
+
+ **Memory Power State Table**
+
Optional, not currently supported.
MSCT Section 5.2.19 (signature == "MSCT")
- == Maximum System Characteristic Table ==
+
+ **Maximum System Characteristic Table**
+
Optional, not currently supported.
MSDM Signature Reserved (signature == "MSDM")
- == Microsoft Data Management table ==
+
+ **Microsoft Data Management table**
+
Microsoft only table, will not be supported.
NFIT Section 5.2.25 (signature == "NFIT")
- == NVDIMM Firmware Interface Table ==
+
+ **NVDIMM Firmware Interface Table**
+
Optional, not currently supported.
OEMx Signature of "OEMx" only
- == OEM Specific Tables ==
+
+ **OEM Specific Tables**
+
All tables starting with a signature of "OEM" are reserved for OEM
use. Since these are not meant to be of general use but are limited
to very specific end users, they are not recommended for use and are
not supported by the kernel for arm64.
PCCT Section 14.1 (signature == "PCCT)
- == Platform Communications Channel Table ==
+
+ **Platform Communications Channel Table**
+
Recommend for use on arm64; use of PCC is recommended when using CPPC
to control performance and power for platform processors.
PMTT Section 5.2.21.12 (signature == "PMTT")
- == Platform Memory Topology Table ==
+
+ **Platform Memory Topology Table**
+
Optional, not currently supported.
PSDT Section 5.2.11.3 (signature == "PSDT")
- == Persistent System Description Table ==
+
+ **Persistent System Description Table**
+
Obsolete table, will not be supported.
RASF Section 5.2.20 (signature == "RASF")
- == RAS Feature table ==
+
+ **RAS Feature table**
+
Optional, not currently supported.
RSDP Section 5.2.5 (signature == "RSD PTR")
- == Root System Description PoinTeR ==
+
+ **Root System Description PoinTeR**
+
Required for arm64.
RSDT Section 5.2.7 (signature == "RSDT")
- == Root System Description Table ==
+
+ **Root System Description Table**
+
Since this table can only provide 32-bit addresses, it is deprecated
on arm64, and will not be used. If provided, it will be ignored.
SBST Section 5.2.14 (signature == "SBST")
- == Smart Battery Subsystem Table ==
+
+ **Smart Battery Subsystem Table**
+
Optional, not currently supported.
SLIC Signature Reserved (signature == "SLIC")
- == Software LIcensing table ==
+
+ **Software LIcensing table**
+
Microsoft only table, will not be supported.
SLIT Section 5.2.17 (signature == "SLIT")
- == System Locality distance Information Table ==
+
+ **System Locality distance Information Table**
+
Optional in general, but required for NUMA systems.
SPCR Signature Reserved (signature == "SPCR")
- == Serial Port Console Redirection table ==
+
+ **Serial Port Console Redirection table**
+
Required for arm64.
SPMI Signature Reserved (signature == "SPMI")
- == Server Platform Management Interface table ==
+
+ **Server Platform Management Interface table**
+
Optional, not currently supported.
SRAT Section 5.2.16 (signature == "SRAT")
- == System Resource Affinity Table ==
+
+ **System Resource Affinity Table**
+
Optional, but if used, only the GICC Affinity structures are read.
To support arm64 NUMA, this table is required.
SSDT Section 5.2.11.2 (signature == "SSDT")
- == Secondary System Description Table ==
+
+ **Secondary System Description Table**
+
These tables are a continuation of the DSDT; these are recommended
for use with devices that can be added to a running system, but can
also serve the purpose of dividing up device descriptions into more
@@ -272,49 +365,69 @@ SSDT Section 5.2.11.2 (signature == "SSDT")
one DSDT but can contain many SSDTs.
STAO Signature Reserved (signature == "STAO")
- == _STA Override table ==
+
+ **_STA Override table**
+
Optional, but only necessary in virtualized environments in order to
hide devices from guest OSs.
TCPA Signature Reserved (signature == "TCPA")
- == Trusted Computing Platform Alliance table ==
+
+ **Trusted Computing Platform Alliance table**
+
Optional, not currently supported, and may need changes to fully
interoperate with arm64.
TPM2 Signature Reserved (signature == "TPM2")
- == Trusted Platform Module 2 table ==
+
+ **Trusted Platform Module 2 table**
+
Optional, not currently supported, and may need changes to fully
interoperate with arm64.
UEFI Signature Reserved (signature == "UEFI")
- == UEFI ACPI data table ==
+
+ **UEFI ACPI data table**
+
Optional, not currently supported. No known use case for arm64,
at present.
WAET Signature Reserved (signature == "WAET")
- == Windows ACPI Emulated devices Table ==
+
+ **Windows ACPI Emulated devices Table**
+
Microsoft only table, will not be supported.
WDAT Signature Reserved (signature == "WDAT")
- == Watch Dog Action Table ==
+
+ **Watch Dog Action Table**
+
Microsoft only table, will not be supported.
WDRT Signature Reserved (signature == "WDRT")
- == Watch Dog Resource Table ==
+
+ **Watch Dog Resource Table**
+
Microsoft only table, will not be supported.
WPBT Signature Reserved (signature == "WPBT")
- == Windows Platform Binary Table ==
+
+ **Windows Platform Binary Table**
+
Microsoft only table, will not be supported.
XENV Signature Reserved (signature == "XENV")
- == Xen project table ==
+
+ **Xen project table**
+
Optional, used only by Xen at present.
XSDT Section 5.2.8 (signature == "XSDT")
- == eXtended System Description Table ==
+
+ **eXtended System Description Table**
+
Required for arm64.
-
+====== ========================================================================
ACPI Objects
------------
@@ -323,10 +436,11 @@ shown in the list that follows; any object not explicitly mentioned below
should be used as needed for a particular platform or particular subsystem,
such as power management or PCI.
+===== ================ ========================================================
Name Section Usage for ARMv8 Linux
----- ------------ -------------------------------------------------
+===== ================ ========================================================
_CCA 6.2.17 This method must be defined for all bus masters
- on arm64 -- there are no assumptions made about
+ on arm64 - there are no assumptions made about
whether such devices are cache coherent or not.
The _CCA value is inherited by all descendants of
these devices so it does not need to be repeated.
@@ -422,8 +536,8 @@ _OSC 6.2.11 This method can be a global method in ACPI (i.e.,
by the kernel community, then register it with the
UEFI Forum.
-\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is
- concerned, _OSI is not to be used to determine what
+\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is
+ concerned, _OSI is not to be used to determine what
sort of system is being used or what functionality
is provided. The _OSC method is to be used instead.
@@ -447,7 +561,7 @@ _PSx 7.3.2-5 Use as needed; power management specific. If _PS0 is
usage, change them in these methods.
_RDI 8.4.4.4 Recommended for use with processor definitions (_HID
- ACPI0010) on arm64. This should only be used in
+ ACPI0010) on arm64. This should only be used in
conjunction with _LPI.
\_REV 5.7.4 Always returns the latest version of ACPI supported.
@@ -476,6 +590,7 @@ _SWS 7.4.3 Use as needed; power management specific; this may
_UID 6.1.12 Recommended for distinguishing devices of the same
class; define it if at all possible.
+===== ================ ========================================================
@@ -488,7 +603,7 @@ platforms, ACPI events must be signaled differently.
There are two options: GPIO-signaled interrupts (Section 5.6.5), and
interrupt-signaled events (Section 5.6.9). Interrupt-signaled events are a
-new feature in the ACPI 6.1 specification. Either -- or both -- can be used
+new feature in the ACPI 6.1 specification. Either - or both - can be used
on a given platform, and which to use may be dependent of limitations in any
given SoC. If possible, interrupt-signaled events are recommended.
@@ -564,39 +679,40 @@ supported.
The following classes of objects are not supported:
- -- Section 9.2: ambient light sensor devices
+ - Section 9.2: ambient light sensor devices
- -- Section 9.3: battery devices
+ - Section 9.3: battery devices
- -- Section 9.4: lids (e.g., laptop lids)
+ - Section 9.4: lids (e.g., laptop lids)
- -- Section 9.8.2: IDE controllers
+ - Section 9.8.2: IDE controllers
- -- Section 9.9: floppy controllers
+ - Section 9.9: floppy controllers
- -- Section 9.10: GPE block devices
+ - Section 9.10: GPE block devices
- -- Section 9.15: PC/AT RTC/CMOS devices
+ - Section 9.15: PC/AT RTC/CMOS devices
- -- Section 9.16: user presence detection devices
+ - Section 9.16: user presence detection devices
- -- Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
+ - Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
- -- Section 9.18: time and alarm devices (see 9.15)
+ - Section 9.18: time and alarm devices (see 9.15)
- -- Section 10: power source and power meter devices
+ - Section 10: power source and power meter devices
- -- Section 11: thermal management
+ - Section 11: thermal management
- -- Section 12: embedded controllers interface
+ - Section 12: embedded controllers interface
- -- Section 13: SMBus interfaces
+ - Section 13: SMBus interfaces
This also means that there is no support for the following objects:
+==== =========================== ==== ==========
Name Section Name Section
----- ------------ ---- ------------
+==== =========================== ==== ==========
_ALC 9.3.4 _FDM 9.10.3
_ALI 9.3.2 _FIX 6.2.7
_ALP 9.3.6 _GAI 10.4.5
@@ -619,4 +735,4 @@ _DCK 6.5.2 _UPD 9.16.1
_EC 12.12 _UPP 9.16.2
_FDE 9.10.1 _WPC 10.5.2
_FDI 9.10.2 _WPP 10.5.3
-
+==== =========================== ==== ==========
diff --git a/Documentation/arm64/arm-acpi.txt b/Documentation/arm64/arm-acpi.rst
similarity index 86%
rename from Documentation/arm64/arm-acpi.txt
rename to Documentation/arm64/arm-acpi.rst
index 1a74a041a443..872dbbc73d4a 100644
--- a/Documentation/arm64/arm-acpi.txt
+++ b/Documentation/arm64/arm-acpi.rst
@@ -1,5 +1,7 @@
+=====================
ACPI on ARMv8 Servers
----------------------
+=====================
+
ACPI can be used for ARMv8 general purpose servers designed to follow
the ARM SBSA (Server Base System Architecture) [0] and SBBR (Server
Base Boot Requirements) [1] specifications. Please note that the SBBR
@@ -34,28 +36,28 @@ of the summary text almost directly, to be honest.
The short form of the rationale for ACPI on ARM is:
--- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
+- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
while DT explicitly does not support this. For hardware vendors, being
able to encode behavior is a key tool used in supporting operating
system releases on new hardware.
--- ACPI’s OSPM defines a power management model that constrains what the
+- ACPI’s OSPM defines a power management model that constrains what the
platform is allowed to do into a specific model, while still providing
flexibility in hardware design.
--- In the enterprise server environment, ACPI has established bindings (such
+- In the enterprise server environment, ACPI has established bindings (such
as for RAS) which are currently used in production systems. DT does not.
Such bindings could be defined in DT at some point, but doing so means ARM
and x86 would end up using completely different code paths in both firmware
and the kernel.
--- Choosing a single interface to describe the abstraction between a platform
+- Choosing a single interface to describe the abstraction between a platform
and an OS is important. Hardware vendors would not be required to implement
both DT and ACPI if they want to support multiple operating systems. And,
agreeing on a single interface instead of being fragmented into per OS
interfaces makes for better interoperability overall.
--- The new ACPI governance process works well and Linux is now at the same
+- The new ACPI governance process works well and Linux is now at the same
table as hardware vendors and other OS vendors. In fact, there is no
longer any reason to feel that ACPI only belongs to Windows or that
Linux is in any way secondary to Microsoft in this arena. The move of
@@ -169,31 +171,31 @@ For the ACPI core to operate properly, and in turn provide the information
the kernel needs to configure devices, it expects to find the following
tables (all section numbers refer to the ACPI 6.1 specification):
- -- RSDP (Root System Description Pointer), section 5.2.5
+ - RSDP (Root System Description Pointer), section 5.2.5
- -- XSDT (eXtended System Description Table), section 5.2.8
+ - XSDT (eXtended System Description Table), section 5.2.8
- -- FADT (Fixed ACPI Description Table), section 5.2.9
+ - FADT (Fixed ACPI Description Table), section 5.2.9
- -- DSDT (Differentiated System Description Table), section
+ - DSDT (Differentiated System Description Table), section
5.2.11.1
- -- MADT (Multiple APIC Description Table), section 5.2.12
+ - MADT (Multiple APIC Description Table), section 5.2.12
- -- GTDT (Generic Timer Description Table), section 5.2.24
+ - GTDT (Generic Timer Description Table), section 5.2.24
- -- If PCI is supported, the MCFG (Memory mapped ConFiGuration
+ - If PCI is supported, the MCFG (Memory mapped ConFiGuration
Table), section 5.2.6, specifically Table 5-31.
- -- If booting without a console=<device> kernel parameter is
+ - If booting without a console=<device> kernel parameter is
supported, the SPCR (Serial Port Console Redirection table),
section 5.2.6, specifically Table 5-31.
- -- If necessary to describe the I/O topology, SMMUs and GIC ITSs,
+ - If necessary to describe the I/O topology, SMMUs and GIC ITSs,
the IORT (Input Output Remapping Table, section 5.2.6, specifically
Table 5-31).
- -- If NUMA is supported, the SRAT (System Resource Affinity Table)
+ - If NUMA is supported, the SRAT (System Resource Affinity Table)
and SLIT (System Locality distance Information Table), sections
5.2.16 and 5.2.17, respectively.
@@ -269,9 +271,9 @@ describes how to define the structure of an object returned via _DSD, and
how specific data structures are defined by specific UUIDs. Linux should
only use the _DSD Device Properties UUID [5]:
- -- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
+ - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
- -- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+ - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
The UEFI Forum provides a mechanism for registering device properties [4]
so that they may be used across all operating systems supporting ACPI.
@@ -327,10 +329,10 @@ turning a device full off.
There are two options for using those Power Resources. They can:
- -- be managed in a _PSx method which gets called on entry to power
+ - be managed in a _PSx method which gets called on entry to power
state Dx.
- -- be declared separately as power resources with their own _ON and _OFF
+ - be declared separately as power resources with their own _ON and _OFF
methods. They are then tied back to D-states for a particular device
via _PRx which specifies which power resources a device needs to be on
while in Dx. Kernel then tracks number of devices using a power resource
@@ -339,16 +341,16 @@ There are two options for using those Power Resources. They can:
The kernel ACPI code will also assume that the _PSx methods follow the normal
ACPI rules for such methods:
- -- If either _PS0 or _PS3 is implemented, then the other method must also
+ - If either _PS0 or _PS3 is implemented, then the other method must also
be implemented.
- -- If a device requires usage or setup of a power resource when on, the ASL
+ - If a device requires usage or setup of a power resource when on, the ASL
should organize that it is allocated/enabled using the _PS0 method.
- -- Resources allocated or enabled in the _PS0 method should be disabled
+ - Resources allocated or enabled in the _PS0 method should be disabled
or de-allocated in the _PS3 method.
- -- Firmware will leave the resources in a reasonable state before handing
+ - Firmware will leave the resources in a reasonable state before handing
over control to the kernel.
Such code in _PSx methods will of course be very platform specific. But,
@@ -394,52 +396,52 @@ else must be discovered by the driver probe function. Then, have the rest
of the driver operate off of the contents of that struct. Doing so should
allow most divergence between ACPI and DT functionality to be kept local to
the probe function instead of being scattered throughout the driver. For
-example:
+example::
-static int device_probe_dt(struct platform_device *pdev)
-{
- /* DT specific functionality */
- ...
-}
+ static int device_probe_dt(struct platform_device *pdev)
+ {
+ /* DT specific functionality */
+ ...
+ }
-static int device_probe_acpi(struct platform_device *pdev)
-{
- /* ACPI specific functionality */
- ...
-}
+ static int device_probe_acpi(struct platform_device *pdev)
+ {
+ /* ACPI specific functionality */
+ ...
+ }
-static int device_probe(struct platform_device *pdev)
-{
- ...
- struct device_node node = pdev->dev.of_node;
- ...
+ static int device_probe(struct platform_device *pdev)
+ {
+ ...
+ struct device_node node = pdev->dev.of_node;
+ ...
- if (node)
- ret = device_probe_dt(pdev);
- else if (ACPI_HANDLE(&pdev->dev))
- ret = device_probe_acpi(pdev);
- else
- /* other initialization */
- ...
- /* Continue with any generic probe operations */
- ...
-}
+ if (node)
+ ret = device_probe_dt(pdev);
+ else if (ACPI_HANDLE(&pdev->dev))
+ ret = device_probe_acpi(pdev);
+ else
+ /* other initialization */
+ ...
+ /* Continue with any generic probe operations */
+ ...
+ }
DO keep the MODULE_DEVICE_TABLE entries together in the driver to make it
clear the different names the driver is probed for, both from DT and from
-ACPI:
+ACPI::
-static struct of_device_id virtio_mmio_match[] = {
- { .compatible = "virtio,mmio", },
- { }
-};
-MODULE_DEVICE_TABLE(of, virtio_mmio_match);
+ static struct of_device_id virtio_mmio_match[] = {
+ { .compatible = "virtio,mmio", },
+ { }
+ };
+ MODULE_DEVICE_TABLE(of, virtio_mmio_match);
-static const struct acpi_device_id virtio_mmio_acpi_match[] = {
- { "LNRO0005", },
- { }
-};
-MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
+ static const struct acpi_device_id virtio_mmio_acpi_match[] = {
+ { "LNRO0005", },
+ { }
+ };
+ MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
ASWG
@@ -471,7 +473,8 @@ Linux Code
Individual items specific to Linux on ARM, contained in the the Linux
source code, are in the list that follows:
-ACPI_OS_NAME This macro defines the string to be returned when
+ACPI_OS_NAME
+ This macro defines the string to be returned when
an ACPI method invokes the _OS method. On ARM64
systems, this macro will be "Linux" by default.
The command line parameter acpi_os=<string>
@@ -482,38 +485,44 @@ ACPI_OS_NAME This macro defines the string to be returned when
ACPI Objects
------------
Detailed expectations for ACPI tables and object are listed in the file
-Documentation/arm64/acpi_object_usage.txt.
+Documentation/arm64/acpi_object_usage.rst.
References
----------
-[0] http://silver.arm.com -- document ARM-DEN-0029, or newer
+[0] http://silver.arm.com
+ document ARM-DEN-0029, or newer:
"Server Base System Architecture", version 2.3, dated 27 Mar 2014
[1] http://infocenter.arm.com/help/topic/com.arm.doc.den0044a/Server_Base_Boot_Requirements.pdf
Document ARM-DEN-0044A, or newer: "Server Base Boot Requirements, System
Software on ARM Platforms", dated 16 Aug 2014
-[2] http://www.secretlab.ca/archives/151, 10 Jan 2015, Copyright (c) 2015,
+[2] http://www.secretlab.ca/archives/151,
+ 10 Jan 2015, Copyright (c) 2015,
Linaro Ltd., written by Grant Likely.
-[3] AMD ACPI for Seattle platform documentation:
+[3] AMD ACPI for Seattle platform documentation
http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf
-[4] http://www.uefi.org/acpi -- please see the link for the "ACPI _DSD Device
+
+[4] http://www.uefi.org/acpi
+ please see the link for the "ACPI _DSD Device
Property Registry Instructions"
-[5] http://www.uefi.org/acpi -- please see the link for the "_DSD (Device
+[5] http://www.uefi.org/acpi
+ please see the link for the "_DSD (Device
Specific Data) Implementation Guide"
-[6] Kernel code for the unified device property interface can be found in
+[6] Kernel code for the unified device
+ property interface can be found in
include/linux/property.h and drivers/base/property.c.
Authors
-------
-Al Stone <al.stone@linaro.org>
-Graeme Gregory <graeme.gregory@linaro.org>
-Hanjun Guo <hanjun.guo@linaro.org>
+- Al Stone <al.stone@linaro.org>
+- Graeme Gregory <graeme.gregory@linaro.org>
+- Hanjun Guo <hanjun.guo@linaro.org>
-Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
+- Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
diff --git a/Documentation/arm64/booting.txt b/Documentation/arm64/booting.rst
similarity index 86%
rename from Documentation/arm64/booting.txt
rename to Documentation/arm64/booting.rst
index fbab7e21d116..3d041d0d16e8 100644
--- a/Documentation/arm64/booting.txt
+++ b/Documentation/arm64/booting.rst
@@ -1,7 +1,9 @@
- Booting AArch64 Linux
- =====================
+=====================
+Booting AArch64 Linux
+=====================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 07 September 2012
This document is based on the ARM booting document by Russell King and
@@ -12,7 +14,7 @@ The AArch64 exception model is made up of a number of exception levels
counterpart. EL2 is the hypervisor level and exists only in non-secure
mode. EL3 is the highest priority level and exists only in secure mode.
-For the purposes of this document, we will use the term `boot loader'
+For the purposes of this document, we will use the term `boot loader`
simply to define all software that executes on the CPU(s) before control
is passed to the Linux kernel. This may include secure monitor and
hypervisor code, or it may just be a handful of instructions for
@@ -70,7 +72,7 @@ Image target is available instead.
Requirement: MANDATORY
-The decompressed kernel image contains a 64-byte header as follows:
+The decompressed kernel image contains a 64-byte header as follows::
u32 code0; /* Executable code */
u32 code1; /* Executable code */
@@ -103,19 +105,26 @@ Header notes:
- The flags field (introduced in v3.17) is a little-endian 64-bit field
composed as follows:
- Bit 0: Kernel endianness. 1 if BE, 0 if LE.
- Bit 1-2: Kernel Page size.
- 0 - Unspecified.
- 1 - 4K
- 2 - 16K
- 3 - 64K
- Bit 3: Kernel physical placement
- 0 - 2MB aligned base should be as close as possible
- to the base of DRAM, since memory below it is not
- accessible via the linear mapping
- 1 - 2MB aligned base may be anywhere in physical
- memory
- Bits 4-63: Reserved.
+
+ ============= ===============================================================
+ Bit 0 Kernel endianness. 1 if BE, 0 if LE.
+ Bit 1-2 Kernel Page size.
+
+ * 0 - Unspecified.
+ * 1 - 4K
+ * 2 - 16K
+ * 3 - 64K
+ Bit 3 Kernel physical placement
+
+ 0
+ 2MB aligned base should be as close as possible
+ to the base of DRAM, since memory below it is not
+ accessible via the linear mapping
+ 1
+ 2MB aligned base may be anywhere in physical
+ memory
+ Bits 4-63 Reserved.
+ ============= ===============================================================
- When image_size is zero, a bootloader should attempt to keep as much
memory as possible free for use by the kernel immediately after the
@@ -147,19 +156,22 @@ Before jumping into the kernel, the following conditions must be met:
corrupted by bogus network packets or disk data. This will save
you many hours of debug.
-- Primary CPU general-purpose register settings
- x0 = physical address of device tree blob (dtb) in system RAM.
- x1 = 0 (reserved for future use)
- x2 = 0 (reserved for future use)
- x3 = 0 (reserved for future use)
+- Primary CPU general-purpose register settings:
+
+ - x0 = physical address of device tree blob (dtb) in system RAM.
+ - x1 = 0 (reserved for future use)
+ - x2 = 0 (reserved for future use)
+ - x3 = 0 (reserved for future use)
- CPU mode
+
All forms of interrupts must be masked in PSTATE.DAIF (Debug, SError,
IRQ and FIQ).
The CPU must be in either EL2 (RECOMMENDED in order to have access to
the virtualisation extensions) or non-secure EL1.
- Caches, MMUs
+
The MMU must be off.
Instruction cache may be on or off.
The address range corresponding to the loaded kernel image must be
@@ -172,18 +184,21 @@ Before jumping into the kernel, the following conditions must be met:
operations (not recommended) must be configured and disabled.
- Architected timers
+
CNTFRQ must be programmed with the timer frequency and CNTVOFF must
be programmed with a consistent value on all CPUs. If entering the
kernel at EL1, CNTHCTL_EL2 must have EL1PCTEN (bit 0) set where
available.
- Coherency
+
All CPUs to be booted by the kernel must be part of the same coherency
domain on entry to the kernel. This may require IMPLEMENTATION DEFINED
initialisation to enable the receiving of maintenance operations on
each CPU.
- System registers
+
All writable architected system registers at the exception level where
the kernel image will be entered must be initialised by software at a
higher exception level to prevent execution in an UNKNOWN state.
@@ -195,28 +210,40 @@ Before jumping into the kernel, the following conditions must be met:
For systems with a GICv3 interrupt controller to be used in v3 mode:
- If EL3 is present:
- ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
- ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
+ - ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
+ - ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
- If the kernel is entered at EL1:
- ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
- ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
+ - ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
+ - ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
- The DT or ACPI tables must describe a GICv3 interrupt controller.
For systems with a GICv3 interrupt controller to be used in
compatibility (v2) mode:
+
- If EL3 is present:
- ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
+ ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
- If the kernel is entered at EL1:
- ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
+ ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
- The DT or ACPI tables must describe a GICv2 interrupt controller.
For CPUs with pointer authentication functionality:
- If EL3 is present:
- SCR_EL3.APK (bit 16) must be initialised to 0b1
- SCR_EL3.API (bit 17) must be initialised to 0b1
+
+ - SCR_EL3.APK (bit 16) must be initialised to 0b1
+ - SCR_EL3.API (bit 17) must be initialised to 0b1
+
- If the kernel is entered at EL1:
- HCR_EL2.APK (bit 40) must be initialised to 0b1
- HCR_EL2.API (bit 41) must be initialised to 0b1
+
+ - HCR_EL2.APK (bit 40) must be initialised to 0b1
+ - HCR_EL2.API (bit 41) must be initialised to 0b1
The requirements described above for CPU mode, caches, MMUs, architected
timers, coherency and system registers apply to all CPUs. All CPUs must
diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.rst
similarity index 65%
rename from Documentation/arm64/cpu-feature-registers.txt
rename to Documentation/arm64/cpu-feature-registers.rst
index 684a0da39378..2955287e9acc 100644
--- a/Documentation/arm64/cpu-feature-registers.txt
+++ b/Documentation/arm64/cpu-feature-registers.rst
@@ -1,5 +1,6 @@
- ARM64 CPU Feature Registers
- ===========================
+===========================
+ARM64 CPU Feature Registers
+===========================
Author: Suzuki K Poulose <suzuki.poulose@arm.com>
@@ -9,7 +10,7 @@ registers to userspace. The availability of this ABI is advertised
via the HWCAP_CPUID in HWCAPs.
1. Motivation
----------------
+-------------
The ARM architecture defines a set of feature registers, which describe
the capabilities of the CPU/system. Access to these system registers is
@@ -33,9 +34,10 @@ there are some issues with their usage.
2. Requirements
------------------
+---------------
+
+ a) Safety:
- a) Safety :
Applications should be able to use the information provided by the
infrastructure to run safely across the system. This has greater
implications on a system with heterogeneous CPUs.
@@ -47,7 +49,8 @@ there are some issues with their usage.
Otherwise an application could crash when scheduled on the CPU
which doesn't support CRC32.
- b) Security :
+ b) Security:
+
Applications should only be able to receive information that is
relevant to the normal operation in userspace. Hence, some of the
fields are masked out(i.e, made invisible) and their values are set to
@@ -58,10 +61,12 @@ there are some issues with their usage.
(even when the CPU provides it).
c) Implementation Defined Features
+
The infrastructure doesn't expose any register which is
IMPLEMENTATION DEFINED as per ARMv8-A Architecture.
- d) CPU Identification :
+ d) CPU Identification:
+
MIDR_EL1 is exposed to help identify the processor. On a
heterogeneous system, this could be racy (just like getcpu()). The
process could be migrated to another CPU by the time it uses the
@@ -70,7 +75,7 @@ there are some issues with their usage.
currently executing on. The REVIDR is not exposed due to this
constraint, as REVIDR makes sense only in conjunction with the
MIDR. Alternately, MIDR_EL1 and REVIDR_EL1 are exposed via sysfs
- at:
+ at::
/sys/devices/system/cpu/cpu$ID/regs/identification/
\- midr
@@ -85,7 +90,8 @@ exception and ends up in SIGILL being delivered to the process.
The infrastructure hooks into the exception handler and emulates the
operation if the source belongs to the supported system register space.
-The infrastructure emulates only the following system register space:
+The infrastructure emulates only the following system register space::
+
Op0=3, Op1=0, CRn=0, CRm=0,4,5,6,7
(See Table C5-6 'System instruction encodings for non-Debug System
@@ -107,73 +113,76 @@ infrastructure:
-------------------------------------------
1) ID_AA64ISAR0_EL1 - Instruction Set Attribute Register 0
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| TS | [55-52] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FHM | [51-48] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DP | [47-44] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM4 | [43-40] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM3 | [39-36] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA3 | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| RDM | [31-28] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| ATOMICS | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| CRC32 | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA2 | [15-12] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA1 | [11-8] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AES | [7-4] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
2) ID_AA64PFR0_EL1 - Processor Feature Register 0
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DIT | [51-48] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SVE | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GIC | [27-24] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AdvSIMD | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FP | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL3 | [15-12] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL2 | [11-8] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL1 | [7-4] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL0 | [3-0] | n |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
3) MIDR_EL1 - Main ID Register
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Implementer | [31-24] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Variant | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Architecture | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| PartNum | [15-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Revision | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
NOTE: The 'visible' fields of MIDR_EL1 will contain the value
as available on the CPU where it is fetched and is not a system
@@ -181,90 +190,92 @@ infrastructure:
4) ID_AA64ISAR1_EL1 - Instruction set attribute register 1
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GPI | [31-28] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GPA | [27-24] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| LRCPC | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FCMA | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| JSCVT | [15-12] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| API | [11-8] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| APA | [7-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DPB | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
5) ID_AA64MMFR2_EL1 - Memory model feature register 2
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AT | [35-32] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
6) ID_AA64ZFR0_EL1 - SVE feature ID register 0
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM4 | [43-40] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA3 | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| BitPerm | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AES | [7-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SVEVer | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
Appendix I: Example
----------------------------
+-------------------
-/*
- * Sample program to demonstrate the MRS emulation ABI.
- *
- * Copyright (C) 2015-2016, ARM Ltd
- *
- * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- */
+::
-#include <asm/hwcap.h>
-#include <stdio.h>
-#include <sys/auxv.h>
+ /*
+ * Sample program to demonstrate the MRS emulation ABI.
+ *
+ * Copyright (C) 2015-2016, ARM Ltd
+ *
+ * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ */
-#define get_cpu_ftr(id) ({ \
+ #include <asm/hwcap.h>
+ #include <stdio.h>
+ #include <sys/auxv.h>
+
+ #define get_cpu_ftr(id) ({ \
unsigned long __val; \
asm("mrs %0, "#id : "=r" (__val)); \
printf("%-20s: 0x%016lx\n", #id, __val); \
})
-int main(void)
-{
+ int main(void)
+ {
if (!(getauxval(AT_HWCAP) & HWCAP_CPUID)) {
fputs("CPUID registers unavailable\n", stderr);
@@ -284,13 +295,10 @@ int main(void)
get_cpu_ftr(MPIDR_EL1);
get_cpu_ftr(REVIDR_EL1);
-#if 0
+ #if 0
/* Unexposed register access causes SIGILL */
get_cpu_ftr(ID_MMFR0_EL1);
-#endif
+ #endif
return 0;
-}
-
-
-
+ }
diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.rst
similarity index 92%
rename from Documentation/arm64/elf_hwcaps.txt
rename to Documentation/arm64/elf_hwcaps.rst
index b73a2519ecf2..c7cbf4b571c0 100644
--- a/Documentation/arm64/elf_hwcaps.txt
+++ b/Documentation/arm64/elf_hwcaps.rst
@@ -1,3 +1,4 @@
+================
ARM64 ELF hwcaps
================
@@ -15,16 +16,16 @@ of flags called hwcaps, exposed in the auxilliary vector.
Userspace software can test for features by acquiring the AT_HWCAP or
AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
-flags are set, e.g.
+flags are set, e.g.::
-bool floating_point_is_present(void)
-{
- unsigned long hwcaps = getauxval(AT_HWCAP);
- if (hwcaps & HWCAP_FP)
- return true;
+ bool floating_point_is_present(void)
+ {
+ unsigned long hwcaps = getauxval(AT_HWCAP);
+ if (hwcaps & HWCAP_FP)
+ return true;
- return false;
-}
+ return false;
+ }
Where software relies on a feature described by a hwcap, it should check
the relevant hwcap flag to verify that the feature is present before
@@ -45,7 +46,7 @@ userspace code at EL0. These hwcaps are defined in terms of ID register
fields, and should be interpreted with reference to the definition of
these fields in the ARM Architecture Reference Manual (ARM ARM).
-Such hwcaps are described below in the form:
+Such hwcaps are described below in the form::
Functionality implied by idreg.field == val.
@@ -64,75 +65,58 @@ reference to ID registers, and may refer to other documentation.
---------------------------------
HWCAP_FP
-
Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
HWCAP_ASIMD
-
Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
HWCAP_EVTSTRM
-
The generic timer is configured to generate events at a frequency of
approximately 100KHz.
HWCAP_AES
-
Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
HWCAP_PMULL
-
Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
HWCAP_SHA1
-
Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
HWCAP_SHA2
-
Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
HWCAP_CRC32
-
Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
HWCAP_ATOMICS
-
Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
HWCAP_FPHP
-
Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
HWCAP_ASIMDHP
-
Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
HWCAP_CPUID
-
EL0 access to certain ID registers is available, to the extent
- described by Documentation/arm64/cpu-feature-registers.txt.
+ described by Documentation/arm64/cpu-feature-registers.rst.
These ID registers may imply the availability of features.
HWCAP_ASIMDRDM
-
Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
HWCAP_JSCVT
-
Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
HWCAP_FCMA
-
Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
HWCAP_LRCPC
-
Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
HWCAP_DCPOP
-
Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
HWCAP2_DCPODP
@@ -140,27 +124,21 @@ HWCAP2_DCPODP
Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
HWCAP_SHA3
-
Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
HWCAP_SM3
-
Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
HWCAP_SM4
-
Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
HWCAP_ASIMDDP
-
Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
HWCAP_SHA512
-
Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
HWCAP_SVE
-
Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
HWCAP2_SVE2
@@ -188,40 +166,32 @@ HWCAP2_SVESM4
Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
HWCAP_ASIMDFHM
-
Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
HWCAP_DIT
-
Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
HWCAP_USCAT
-
Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
HWCAP_ILRCPC
-
Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
HWCAP_FLAGM
-
Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
HWCAP_SSBS
-
Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
HWCAP_PACA
-
Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
ID_AA64ISAR1_EL1.API == 0b0001, as described by
- Documentation/arm64/pointer-authentication.txt.
+ Documentation/arm64/pointer-authentication.rst.
HWCAP_PACG
-
Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
- Documentation/arm64/pointer-authentication.txt.
+ Documentation/arm64/pointer-authentication.rst.
4. Unused AT_HWCAP bits
diff --git a/Documentation/arm64/hugetlbpage.txt b/Documentation/arm64/hugetlbpage.rst
similarity index 86%
rename from Documentation/arm64/hugetlbpage.txt
rename to Documentation/arm64/hugetlbpage.rst
index cfae87dc653b..b44f939e5210 100644
--- a/Documentation/arm64/hugetlbpage.txt
+++ b/Documentation/arm64/hugetlbpage.rst
@@ -1,3 +1,4 @@
+====================
HugeTLBpage on ARM64
====================
@@ -31,8 +32,10 @@ and level of the page table.
The following hugepage sizes are supported -
- CONT PTE PMD CONT PMD PUD
- -------- --- -------- ---
+ ====== ======== ==== ======== ===
+ - CONT PTE PMD CONT PMD PUD
+ ====== ======== ==== ======== ===
4K: 64K 2M 32M 1G
16K: 2M 32M 1G
64K: 2M 512M 16G
+ ====== ======== ==== ======== ===
diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst
new file mode 100644
index 000000000000..018b7836ecb7
--- /dev/null
+++ b/Documentation/arm64/index.rst
@@ -0,0 +1,28 @@
+:orphan:
+
+==================
+ARM64 Architecture
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ acpi_object_usage
+ arm-acpi
+ booting
+ cpu-feature-registers
+ elf_hwcaps
+ hugetlbpage
+ legacy_instructions
+ memory
+ pointer-authentication
+ silicon-errata
+ sve
+ tagged-pointers
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/arm64/legacy_instructions.txt b/Documentation/arm64/legacy_instructions.rst
similarity index 73%
rename from Documentation/arm64/legacy_instructions.txt
rename to Documentation/arm64/legacy_instructions.rst
index 01bf3d9fac85..54401b22cb8f 100644
--- a/Documentation/arm64/legacy_instructions.txt
+++ b/Documentation/arm64/legacy_instructions.rst
@@ -1,3 +1,7 @@
+===================
+Legacy instructions
+===================
+
The arm64 port of the Linux kernel provides infrastructure to support
emulation of instructions which have been deprecated, or obsoleted in
the architecture. The infrastructure code uses undefined instruction
@@ -9,19 +13,22 @@ The emulation mode can be controlled by writing to sysctl nodes
behaviours and the corresponding values of the sysctl nodes -
* Undef
- Value: 0
+ Value: 0
+
Generates undefined instruction abort. Default for instructions that
have been obsoleted in the architecture, e.g., SWP
* Emulate
- Value: 1
+ Value: 1
+
Uses software emulation. To aid migration of software, in this mode
usage of emulated instruction is traced as well as rate limited
warnings are issued. This is the default for deprecated
instructions, .e.g., CP15 barriers
* Hardware Execution
- Value: 2
+ Value: 2
+
Although marked as deprecated, some implementations may support the
enabling/disabling of hardware support for the execution of these
instructions. Using hardware execution generally provides better
@@ -38,20 +45,24 @@ individual instruction notes for further information.
Supported legacy instructions
-----------------------------
* SWP{B}
-Node: /proc/sys/abi/swp
-Status: Obsolete
-Default: Undef (0)
+
+:Node: /proc/sys/abi/swp
+:Status: Obsolete
+:Default: Undef (0)
* CP15 Barriers
-Node: /proc/sys/abi/cp15_barrier
-Status: Deprecated
-Default: Emulate (1)
+
+:Node: /proc/sys/abi/cp15_barrier
+:Status: Deprecated
+:Default: Emulate (1)
* SETEND
-Node: /proc/sys/abi/setend
-Status: Deprecated
-Default: Emulate (1)*
-Note: All the cpus on the system must have mixed endian support at EL0
-for this feature to be enabled. If a new CPU - which doesn't support mixed
-endian - is hotplugged in after this feature has been enabled, there could
-be unexpected results in the application.
+
+:Node: /proc/sys/abi/setend
+:Status: Deprecated
+:Default: Emulate (1)*
+
+ Note: All the cpus on the system must have mixed endian support at EL0
+ for this feature to be enabled. If a new CPU - which doesn't support mixed
+ endian - is hotplugged in after this feature has been enabled, there could
+ be unexpected results in the application.
diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst
new file mode 100644
index 000000000000..464b880fc4b7
--- /dev/null
+++ b/Documentation/arm64/memory.rst
@@ -0,0 +1,98 @@
+==============================
+Memory Layout on AArch64 Linux
+==============================
+
+Author: Catalin Marinas <catalin.marinas@arm.com>
+
+This document describes the virtual memory layout used by the AArch64
+Linux kernel. The architecture allows up to 4 levels of translation
+tables with a 4KB page size and up to 3 levels with a 64KB page size.
+
+AArch64 Linux uses either 3 levels or 4 levels of translation tables
+with the 4KB page configuration, allowing 39-bit (512GB) or 48-bit
+(256TB) virtual addresses, respectively, for both user and kernel. With
+64KB pages, only 2 levels of translation tables, allowing 42-bit (4TB)
+virtual address, are used but the memory layout is the same.
+
+User addresses have bits 63:48 set to 0 while the kernel addresses have
+the same bits set to 1. TTBRx selection is given by bit 63 of the
+virtual address. The swapper_pg_dir contains only kernel (global)
+mappings while the user pgd contains only user (non-global) mappings.
+The swapper_pg_dir address is written to TTBR1 and never written to
+TTBR0.
+
+
+AArch64 Linux memory layout with 4KB pages + 3 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000007fffffffff 512GB user
+ ffffff8000000000 ffffffffffffffff 512GB kernel
+
+
+AArch64 Linux memory layout with 4KB pages + 4 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000ffffffffffff 256TB user
+ ffff000000000000 ffffffffffffffff 256TB kernel
+
+
+AArch64 Linux memory layout with 64KB pages + 2 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 000003ffffffffff 4TB user
+ fffffc0000000000 ffffffffffffffff 4TB kernel
+
+
+AArch64 Linux memory layout with 64KB pages + 3 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000ffffffffffff 256TB user
+ ffff000000000000 ffffffffffffffff 256TB kernel
+
+
+For details of the virtual kernel memory layout please see the kernel
+booting log.
+
+
+Translation table lookup with 4KB pages::
+
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ | | | | | |
+ | | | | | v
+ | | | | | [11:0] in-page offset
+ | | | | +-> [20:12] L3 index
+ | | | +-----------> [29:21] L2 index
+ | | +---------------------> [38:30] L1 index
+ | +-------------------------------> [47:39] L0 index
+ +-------------------------------------------------> [63] TTBR0/1
+
+
+Translation table lookup with 64KB pages::
+
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ | | | | |
+ | | | | v
+ | | | | [15:0] in-page offset
+ | | | +----------> [28:16] L3 index
+ | | +--------------------------> [41:29] L2 index
+ | +-------------------------------> [47:42] L1 index
+ +-------------------------------------------------> [63] TTBR0/1
+
+
+When using KVM without the Virtualization Host Extensions, the
+hypervisor maps kernel pages in EL2 at a fixed (and potentially
+random) offset from the linear mapping. See the kern_hyp_va macro and
+kvm_update_va_mask function for more details. MMIO devices such as
+GICv2 gets mapped next to the HYP idmap page, as do vectors when
+ARM64_HARDEN_EL2_VECTORS is selected for particular CPUs.
+
+When using KVM with the Virtualization Host Extensions, no additional
+mappings are created, since the host kernel runs directly in EL2.
diff --git a/Documentation/arm64/memory.txt b/Documentation/arm64/memory.txt
deleted file mode 100644
index c5dab30d3389..000000000000
--- a/Documentation/arm64/memory.txt
+++ /dev/null
@@ -1,97 +0,0 @@
- Memory Layout on AArch64 Linux
- ==============================
-
-Author: Catalin Marinas <catalin.marinas@arm.com>
-
-This document describes the virtual memory layout used by the AArch64
-Linux kernel. The architecture allows up to 4 levels of translation
-tables with a 4KB page size and up to 3 levels with a 64KB page size.
-
-AArch64 Linux uses either 3 levels or 4 levels of translation tables
-with the 4KB page configuration, allowing 39-bit (512GB) or 48-bit
-(256TB) virtual addresses, respectively, for both user and kernel. With
-64KB pages, only 2 levels of translation tables, allowing 42-bit (4TB)
-virtual address, are used but the memory layout is the same.
-
-User addresses have bits 63:48 set to 0 while the kernel addresses have
-the same bits set to 1. TTBRx selection is given by bit 63 of the
-virtual address. The swapper_pg_dir contains only kernel (global)
-mappings while the user pgd contains only user (non-global) mappings.
-The swapper_pg_dir address is written to TTBR1 and never written to
-TTBR0.
-
-
-AArch64 Linux memory layout with 4KB pages + 3 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000007fffffffff 512GB user
-ffffff8000000000 ffffffffffffffff 512GB kernel
-
-
-AArch64 Linux memory layout with 4KB pages + 4 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
-
-
-AArch64 Linux memory layout with 64KB pages + 2 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 000003ffffffffff 4TB user
-fffffc0000000000 ffffffffffffffff 4TB kernel
-
-
-AArch64 Linux memory layout with 64KB pages + 3 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
-
-
-For details of the virtual kernel memory layout please see the kernel
-booting log.
-
-
-Translation table lookup with 4KB pages:
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- | | | | | |
- | | | | | v
- | | | | | [11:0] in-page offset
- | | | | +-> [20:12] L3 index
- | | | +-----------> [29:21] L2 index
- | | +---------------------> [38:30] L1 index
- | +-------------------------------> [47:39] L0 index
- +-------------------------------------------------> [63] TTBR0/1
-
-
-Translation table lookup with 64KB pages:
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- | | | | |
- | | | | v
- | | | | [15:0] in-page offset
- | | | +----------> [28:16] L3 index
- | | +--------------------------> [41:29] L2 index
- | +-------------------------------> [47:42] L1 index
- +-------------------------------------------------> [63] TTBR0/1
-
-
-When using KVM without the Virtualization Host Extensions, the
-hypervisor maps kernel pages in EL2 at a fixed (and potentially
-random) offset from the linear mapping. See the kern_hyp_va macro and
-kvm_update_va_mask function for more details. MMIO devices such as
-GICv2 gets mapped next to the HYP idmap page, as do vectors when
-ARM64_HARDEN_EL2_VECTORS is selected for particular CPUs.
-
-When using KVM with the Virtualization Host Extensions, no additional
-mappings are created, since the host kernel runs directly in EL2.
diff --git a/Documentation/arm64/pointer-authentication.txt b/Documentation/arm64/pointer-authentication.rst
similarity index 99%
rename from Documentation/arm64/pointer-authentication.txt
rename to Documentation/arm64/pointer-authentication.rst
index fc71b33de87e..30b2ab06526b 100644
--- a/Documentation/arm64/pointer-authentication.txt
+++ b/Documentation/arm64/pointer-authentication.rst
@@ -1,7 +1,9 @@
+=======================================
Pointer authentication in AArch64 Linux
=======================================
Author: Mark Rutland <mark.rutland@arm.com>
+
Date: 2017-07-19
This document briefly describes the provision of pointer authentication
diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.rst
similarity index 55%
rename from Documentation/arm64/silicon-errata.txt
rename to Documentation/arm64/silicon-errata.rst
index 2735462d5958..c792774be59e 100644
--- a/Documentation/arm64/silicon-errata.txt
+++ b/Documentation/arm64/silicon-errata.rst
@@ -1,7 +1,9 @@
- Silicon Errata and Software Workarounds
- =======================================
+=======================================
+Silicon Errata and Software Workarounds
+=======================================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 27 November 2015
It is an unfortunate fact of life that hardware is often produced with
@@ -9,11 +11,13 @@ so-called "errata", which can cause it to deviate from the architecture
under specific circumstances. For hardware produced by ARM, these
errata are broadly classified into the following categories:
- Category A: A critical error without a viable workaround.
- Category B: A significant or critical error with an acceptable
+ ========== ========================================================
+ Category A A critical error without a viable workaround.
+ Category B A significant or critical error with an acceptable
workaround.
- Category C: A minor error that is not expected to occur under normal
+ Category C A minor error that is not expected to occur under normal
operation.
+ ========== ========================================================
For more information, consult one of the "Software Developers Errata
Notice" documents available on infocenter.arm.com (registration
@@ -42,47 +46,86 @@ file acts as a registry of software workarounds in the Linux Kernel and
will be updated when new workarounds are committed and backported to
stable kernels.
++----------------+-----------------+-----------------+-----------------------------+
| Implementor | Component | Erratum ID | Kconfig |
-+----------------+-----------------+-----------------+-----------------------------+
++================+=================+=================+=============================+
| Allwinner | A64/R18 | UNKNOWN1 | SUN50I_ERRATUM_UNKNOWN1 |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #852523 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A72 | #853709 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A73 | #858921 | ARM64_ERRATUM_858921 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A55 | #1024718 | ARM64_ERRATUM_1024718 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1188873,1418040| ARM64_ERRATUM_1418040 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1165522 | ARM64_ERRATUM_1165522 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1286807 | ARM64_ERRATUM_1286807 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1463225 | ARM64_ERRATUM_1463225 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Neoverse-N1 | #1188873,1418040| ARM64_ERRATUM_1418040 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | MMU-500 | #841119,826419 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX ITS | #22375,24313 | CAVIUM_ERRATUM_22375 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX ITS | #23144 | CAVIUM_ERRATUM_23144 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX Core | #27456 | CAVIUM_ERRATUM_27456 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX Core | #30115 | CAVIUM_ERRATUM_30115 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX SMMUv2 | #27704 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX2 SMMUv3| #74 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX2 SMMUv3| #126 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip0{5,6,7} | #161010101 | HISILICON_ERRATUM_161010101 |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip0{6,7} | #161010701 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip07 | #161600802 | HISILICON_ERRATUM_161600802 |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip08 SMMU PMCG | #162001800 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Kryo/Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Falkor v1 | E1009 | QCOM_FALKOR_ERRATUM_1009 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | QDF2400 ITS | E0065 | QCOM_QDF2400_ERRATUM_0065 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Falkor v{1,2} | E1041 | QCOM_FALKOR_ERRATUM_1041 |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Fujitsu | A64FX | E#010001 | FUJITSU_ERRATUM_010001 |
++----------------+-----------------+-----------------+-----------------------------+
diff --git a/Documentation/arm64/sve.txt b/Documentation/arm64/sve.rst
similarity index 98%
rename from Documentation/arm64/sve.txt
rename to Documentation/arm64/sve.rst
index 9940e924a47e..38422ab249dd 100644
--- a/Documentation/arm64/sve.txt
+++ b/Documentation/arm64/sve.rst
@@ -1,7 +1,9 @@
- Scalable Vector Extension support for AArch64 Linux
- ===================================================
+===================================================
+Scalable Vector Extension support for AArch64 Linux
+===================================================
Author: Dave Martin <Dave.Martin@arm.com>
+
Date: 4 August 2017
This document outlines briefly the interface provided to userspace by Linux in
@@ -426,7 +428,7 @@ In A64 state, SVE adds the following:
* FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point
operations in a similar way to the way in which they interact with ARMv8
- floating-point operations.
+ floating-point operations::
8VL-1 128 0 bit index
+---- //// -----------------+
@@ -483,6 +485,8 @@ ARMv8-A defines the following floating-point / SIMD register state:
* 32 128-bit vector registers V0..V31
* 2 32-bit status/control registers FPSR, FPCR
+::
+
127 0 bit index
+---------------+
V0 | |
@@ -517,7 +521,7 @@ References
[2] arch/arm64/include/uapi/asm/ptrace.h
AArch64 Linux ptrace ABI definitions
-[3] Documentation/arm64/cpu-feature-registers.txt
+[3] Documentation/arm64/cpu-feature-registers.rst
[4] ARM IHI0055C
http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf
diff --git a/Documentation/arm64/tagged-pointers.txt b/Documentation/arm64/tagged-pointers.rst
similarity index 94%
rename from Documentation/arm64/tagged-pointers.txt
rename to Documentation/arm64/tagged-pointers.rst
index a25a99e82bb1..2acdec3ebbeb 100644
--- a/Documentation/arm64/tagged-pointers.txt
+++ b/Documentation/arm64/tagged-pointers.rst
@@ -1,7 +1,9 @@
- Tagged virtual addresses in AArch64 Linux
- =========================================
+=========================================
+Tagged virtual addresses in AArch64 Linux
+=========================================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 12 June 2013
This document briefly describes the provision of tagged virtual
diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt
index c1dd968c5ee9..3bfbf66e5a5e 100644
--- a/Documentation/translations/zh_CN/arm64/booting.txt
+++ b/Documentation/translations/zh_CN/arm64/booting.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/booting.txt
+Chinese translated version of Documentation/arm64/booting.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -10,7 +10,7 @@ M: Will Deacon <will.deacon@arm.com>
zh_CN: Fu Wei <wefu@redhat.com>
C: 55f058e7574c3615dea4615573a19bdb258696c6
---------------------------------------------------------------------
-Documentation/arm64/booting.txt 的中文翻译
+Documentation/arm64/booting.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
index 68362a1ab717..e295cf75f606 100644
--- a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
+++ b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/legacy_instructions.txt
+Chinese translated version of Documentation/arm64/legacy_instructions.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -10,7 +10,7 @@ Maintainer: Punit Agrawal <punit.agrawal@arm.com>
Suzuki K. Poulose <suzuki.poulose@arm.com>
Chinese maintainer: Fu Wei <wefu@redhat.com>
---------------------------------------------------------------------
-Documentation/arm64/legacy_instructions.txt 的中文翻译
+Documentation/arm64/legacy_instructions.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/memory.txt b/Documentation/translations/zh_CN/arm64/memory.txt
index 19b3a52d5d94..be20f8228b91 100644
--- a/Documentation/translations/zh_CN/arm64/memory.txt
+++ b/Documentation/translations/zh_CN/arm64/memory.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/memory.txt
+Chinese translated version of Documentation/arm64/memory.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
Maintainer: Catalin Marinas <catalin.marinas@arm.com>
Chinese maintainer: Fu Wei <wefu@redhat.com>
---------------------------------------------------------------------
-Documentation/arm64/memory.txt 的中文翻译
+Documentation/arm64/memory.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/silicon-errata.txt b/Documentation/translations/zh_CN/arm64/silicon-errata.txt
index 39477c75c4a4..440c59ac7dce 100644
--- a/Documentation/translations/zh_CN/arm64/silicon-errata.txt
+++ b/Documentation/translations/zh_CN/arm64/silicon-errata.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/silicon-errata.txt
+Chinese translated version of Documentation/arm64/silicon-errata.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -10,7 +10,7 @@ M: Will Deacon <will.deacon@arm.com>
zh_CN: Fu Wei <wefu@redhat.com>
C: 1926e54f115725a9248d0c4c65c22acaf94de4c4
---------------------------------------------------------------------
-Documentation/arm64/silicon-errata.txt 的中文翻译
+Documentation/arm64/silicon-errata.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
index 2664d1bd5a1c..77ac3548a16d 100644
--- a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
+++ b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/tagged-pointers.txt
+Chinese translated version of Documentation/arm64/tagged-pointers.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
Maintainer: Will Deacon <will.deacon@arm.com>
Chinese maintainer: Fu Wei <wefu@redhat.com>
---------------------------------------------------------------------
-Documentation/arm64/tagged-pointers.txt 的中文翻译
+Documentation/arm64/tagged-pointers.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index ba6c42c576dd..68984c284c40 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -2205,7 +2205,7 @@ max_vq. This is the maximum vector length available to the guest on
this vcpu, and determines which register slices are visible through
this ioctl interface.
-(See Documentation/arm64/sve.txt for an explanation of the "vq"
+(See Documentation/arm64/sve.rst for an explanation of the "vq"
nomenclature.)
KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT.
diff --git a/arch/arm64/include/asm/efi.h b/arch/arm64/include/asm/efi.h
index c9e9a6978e73..8e79ce9c3f5c 100644
--- a/arch/arm64/include/asm/efi.h
+++ b/arch/arm64/include/asm/efi.h
@@ -83,7 +83,7 @@ static inline unsigned long efi_get_max_fdt_addr(unsigned long dram_base)
* guaranteed to cover the kernel Image.
*
* Since the EFI stub is part of the kernel Image, we can relax the
- * usual requirements in Documentation/arm64/booting.txt, which still
+ * usual requirements in Documentation/arm64/booting.rst, which still
* apply to other bootloaders, and are required for some kernel
* configurations.
*/
diff --git a/arch/arm64/include/asm/image.h b/arch/arm64/include/asm/image.h
index e2c27a2278e9..c2b13213c720 100644
--- a/arch/arm64/include/asm/image.h
+++ b/arch/arm64/include/asm/image.h
@@ -27,7 +27,7 @@
/*
* struct arm64_image_header - arm64 kernel image header
- * See Documentation/arm64/booting.txt for details
+ * See Documentation/arm64/booting.rst for details
*
* @code0: Executable code, or
* @mz_header alternatively used for part of MZ header
diff --git a/arch/arm64/include/uapi/asm/sigcontext.h b/arch/arm64/include/uapi/asm/sigcontext.h
index 5f3c0cec5af9..a61f89ddbf34 100644
--- a/arch/arm64/include/uapi/asm/sigcontext.h
+++ b/arch/arm64/include/uapi/asm/sigcontext.h
@@ -137,7 +137,7 @@ struct sve_context {
* vector length beyond its initial architectural limit of 2048 bits
* (16 quadwords).
*
- * See linux/Documentation/arm64/sve.txt for a description of the VL/VQ
+ * See linux/Documentation/arm64/sve.rst for a description of the VL/VQ
* terminology.
*/
#define SVE_VQ_BYTES __SVE_VQ_BYTES /* bytes per quadword */
diff --git a/arch/arm64/kernel/kexec_image.c b/arch/arm64/kernel/kexec_image.c
index 31cc2f423aa8..2514fd6f12cb 100644
--- a/arch/arm64/kernel/kexec_image.c
+++ b/arch/arm64/kernel/kexec_image.c
@@ -53,7 +53,7 @@ static void *image_load(struct kimage *image,
/*
* We require a kernel with an unambiguous Image header. Per
- * Documentation/arm64/booting.txt, this is the case when image_size
+ * Documentation/arm64/booting.rst, this is the case when image_size
* is non-zero (practically speaking, since v3.17).
*/
h = (struct arm64_image_header *)kernel;
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 04/28] docs: cdrom: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 01/28] docs: aoe: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 06/28] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler Mauro Carvalho Chehab
` (21 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jens Axboe, Borislav Petkov, David S. Miller,
linux-ide, linux-block
The stuff there is almost already at ReST format. A
conversion for them is trivial: just add a missing titles
and fix some scape codes for them to match ReST syntax.
While here, rename the cdrom-standard.txt, with was converted
from LaTeX to ReST on the previous patch, and add it to the
index file.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...{cdrom-standard.txt => cdrom-standard.rst} | 0
Documentation/cdrom/{ide-cd => ide-cd.rst} | 178 +++++++++---------
Documentation/cdrom/index.rst | 19 ++
...{packet-writing.txt => packet-writing.rst} | 27 ++-
MAINTAINERS | 2 +-
drivers/block/Kconfig | 2 +-
drivers/cdrom/cdrom.c | 2 +-
drivers/ide/ide-cd.c | 2 +-
8 files changed, 131 insertions(+), 101 deletions(-)
rename Documentation/cdrom/{cdrom-standard.txt => cdrom-standard.rst} (100%)
rename Documentation/cdrom/{ide-cd => ide-cd.rst} (84%)
create mode 100644 Documentation/cdrom/index.rst
rename Documentation/cdrom/{packet-writing.txt => packet-writing.rst} (91%)
diff --git a/Documentation/cdrom/cdrom-standard.txt b/Documentation/cdrom/cdrom-standard.rst
similarity index 100%
rename from Documentation/cdrom/cdrom-standard.txt
rename to Documentation/cdrom/cdrom-standard.rst
diff --git a/Documentation/cdrom/ide-cd b/Documentation/cdrom/ide-cd.rst
similarity index 84%
rename from Documentation/cdrom/ide-cd
rename to Documentation/cdrom/ide-cd.rst
index a5f2a7f1ff46..dadc94ef6b6c 100644
--- a/Documentation/cdrom/ide-cd
+++ b/Documentation/cdrom/ide-cd.rst
@@ -1,18 +1,20 @@
IDE-CD driver documentation
-Originally by scott snyder <snyder@fnald0.fnal.gov> (19 May 1996)
-Carrying on the torch is: Erik Andersen <andersee@debian.org>
-New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
+===========================
+
+:Originally by: scott snyder <snyder@fnald0.fnal.gov> (19 May 1996)
+:Carrying on the torch is: Erik Andersen <andersee@debian.org>
+:New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
1. Introduction
---------------
-The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
+The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
CDROM drives which attach to an IDE interface. Note that some CDROM vendors
(including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made
both ATAPI-compliant drives and drives which use a proprietary
interface. If your drive uses one of those proprietary interfaces,
this driver will not work with it (but one of the other CDROM drivers
-probably will). This driver will not work with `ATAPI' drives which
+probably will). This driver will not work with `ATAPI` drives which
attach to the parallel port. In addition, there is at least one drive
(CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI;
this driver will not work with drives like that either (but see the
@@ -31,7 +33,7 @@ This driver provides the following features:
from audio tracks. The program cdda2wav can be used for this.
Note, however, that only some drives actually support this.
- - There is now support for CDROM changers which comply with the
+ - There is now support for CDROM changers which comply with the
ATAPI 2.6 draft standard (such as the NEC CDR-251). This additional
functionality includes a function call to query which slot is the
currently selected slot, a function call to query which slots contain
@@ -49,11 +51,11 @@ This driver provides the following features:
driver.
1. Make sure that the ide and ide-cd drivers are compiled into the
- kernel you're using. When configuring the kernel, in the section
- entitled "Floppy, IDE, and other block devices", say either `Y'
- (which will compile the support directly into the kernel) or `M'
+ kernel you're using. When configuring the kernel, in the section
+ entitled "Floppy, IDE, and other block devices", say either `Y`
+ (which will compile the support directly into the kernel) or `M`
(to compile support as a module which can be loaded and unloaded)
- to the options:
+ to the options::
ATA/ATAPI/MFM/RLL support
Include IDE/ATAPI CDROM support
@@ -72,35 +74,35 @@ This driver provides the following features:
address and an IRQ number, the standard assignments being
0x1f0 and 14 for the primary interface and 0x170 and 15 for the
secondary interface. Each interface can control up to two devices,
- where each device can be a hard drive, a CDROM drive, a floppy drive,
- or a tape drive. The two devices on an interface are called `master'
- and `slave'; this is usually selectable via a jumper on the drive.
+ where each device can be a hard drive, a CDROM drive, a floppy drive,
+ or a tape drive. The two devices on an interface are called `master`
+ and `slave`; this is usually selectable via a jumper on the drive.
Linux names these devices as follows. The master and slave devices
- on the primary IDE interface are called `hda' and `hdb',
+ on the primary IDE interface are called `hda` and `hdb`,
respectively. The drives on the secondary interface are called
- `hdc' and `hdd'. (Interfaces at other locations get other letters
+ `hdc` and `hdd`. (Interfaces at other locations get other letters
in the third position; see Documentation/ide/ide.txt.)
If you want your CDROM drive to be found automatically by the
driver, you should make sure your IDE interface uses either the
primary or secondary addresses mentioned above. In addition, if
the CDROM drive is the only device on the IDE interface, it should
- be jumpered as `master'. (If for some reason you cannot configure
+ be jumpered as `master`. (If for some reason you cannot configure
your system in this manner, you can probably still use the driver.
You may have to pass extra configuration information to the kernel
when you boot, however. See Documentation/ide/ide.txt for more
information.)
4. Boot the system. If the drive is recognized, you should see a
- message which looks like
+ message which looks like::
hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive
If you do not see this, see section 5 below.
5. You may want to create a symbolic link /dev/cdrom pointing to the
- actual device. You can do this with the command
+ actual device. You can do this with the command::
ln -s /dev/hdX /dev/cdrom
@@ -108,14 +110,14 @@ This driver provides the following features:
drive is installed.
6. You should be able to see any error messages from the driver with
- the `dmesg' command.
+ the `dmesg` command.
3. Basic usage
--------------
-An ISO 9660 CDROM can be mounted by putting the disc in the drive and
-typing (as root)
+An ISO 9660 CDROM can be mounted by putting the disc in the drive and
+typing (as root)::
mount -t iso9660 /dev/cdrom /mnt/cdrom
@@ -123,7 +125,7 @@ where it is assumed that /dev/cdrom is a link pointing to the actual
device (as described in step 5 of the last section) and /mnt/cdrom is
an empty directory. You should now be able to see the contents of the
CDROM under the /mnt/cdrom directory. If you want to eject the CDROM,
-you must first dismount it with a command like
+you must first dismount it with a command like::
umount /mnt/cdrom
@@ -148,7 +150,7 @@ such as cdda2wav. The only types of drive which I've heard support
this are Sony and Toshiba drives. You will get errors if you try to
use this function on a drive which does not support it.
-For supported changers, you can use the `cdchange' program (appended to
+For supported changers, you can use the `cdchange` program (appended to
the end of this file) to switch between changer slots. Note that the
drive should be unmounted before attempting this. The program takes
two arguments: the CDROM device, and the slot number to which you wish
@@ -165,7 +167,7 @@ Documentation/ide/ide.txt for current information about the underlying
IDE support code. Some of these items apply only to earlier versions
of the driver, but are mentioned here for completeness.
-In most cases, you should probably check with `dmesg' for any errors
+In most cases, you should probably check with `dmesg` for any errors
from the driver.
a. Drive is not detected during booting.
@@ -184,9 +186,9 @@ a. Drive is not detected during booting.
- If the autoprobing is not finding your drive, you can tell the
driver to assume that one exists by using a lilo option of the
- form `hdX=cdrom', where X is the drive letter corresponding to
- where your drive is installed. Note that if you do this and you
- see a boot message like
+ form `hdX=cdrom`, where X is the drive letter corresponding to
+ where your drive is installed. Note that if you do this and you
+ see a boot message like::
hdX: ATAPI cdrom (?)
@@ -220,7 +222,7 @@ b. Timeout/IRQ errors.
probably not making it to the host.
- IRQ problems may also be indicated by the message
- `IRQ probe failed (<n>)' while booting. If <n> is zero, that
+ `IRQ probe failed (<n>)` while booting. If <n> is zero, that
means that the system did not see an interrupt from the drive when
it was expecting one (on any feasible IRQ). If <n> is negative,
that means the system saw interrupts on multiple IRQ lines, when
@@ -240,27 +242,27 @@ b. Timeout/IRQ errors.
there are hardware problems with the interrupt setup; they
apparently don't use interrupts.
- - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
+ - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }"
The Pioneer DR-A24X CDROM drives are fairly popular these days.
Unfortunately, these drives seem to become very confused when we perform
the standard Linux ATA disk drive probe. If you own one of these drives,
- you can bypass the ATA probing which confuses these CDROM drives, by
- adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running
- lilo (again where X is the drive letter corresponding to where your drive
+ you can bypass the ATA probing which confuses these CDROM drives, by
+ adding `append="hdX=noprobe hdX=cdrom"` to your lilo.conf file and running
+ lilo (again where X is the drive letter corresponding to where your drive
is installed.)
-
+
c. System hangups.
- If the system locks up when you try to access the CDROM, the most
likely cause is that you have a buggy IDE adapter which doesn't
properly handle simultaneous transactions on multiple interfaces.
The most notorious of these is the CMD640B chip. This problem can
- be worked around by specifying the `serialize' option when
+ be worked around by specifying the `serialize` option when
booting. Recent kernels should be able to detect the need for
this automatically in most cases, but the detection is not
foolproof. See Documentation/ide/ide.txt for more information
- about the `serialize' option and the CMD640B.
+ about the `serialize` option and the CMD640B.
- Note that many MS-DOS CDROM drivers will work with such buggy
hardware, apparently because they never attempt to overlap CDROM
@@ -269,14 +271,14 @@ c. System hangups.
d. Can't mount a CDROM.
- - If you get errors from mount, it may help to check `dmesg' to see
+ - If you get errors from mount, it may help to check `dmesg` to see
if there are any more specific errors from the driver or from the
filesystem.
- Make sure there's a CDROM loaded in the drive, and that's it's an
ISO 9660 disc. You can't mount an audio CD.
- - With the CDROM in the drive and unmounted, try something like
+ - With the CDROM in the drive and unmounted, try something like::
cat /dev/cdrom | od | more
@@ -284,9 +286,9 @@ d. Can't mount a CDROM.
OK, and the problem is at the filesystem level (i.e., the CDROM is
not ISO 9660 or has errors in the filesystem structure).
- - If you see `not a block device' errors, check that the definitions
+ - If you see `not a block device` errors, check that the definitions
of the device special files are correct. They should be as
- follows:
+ follows::
brw-rw---- 1 root disk 3, 0 Nov 11 18:48 /dev/hda
brw-rw---- 1 root disk 3, 64 Nov 11 18:48 /dev/hdb
@@ -301,7 +303,7 @@ d. Can't mount a CDROM.
If you have a /dev/cdrom symbolic link, check that it is pointing
to the correct device file.
- If you hear people talking of the devices `hd1a' and `hd1b', these
+ If you hear people talking of the devices `hd1a` and `hd1b`, these
were old names for what are now called hdc and hdd. Those names
should be considered obsolete.
@@ -311,8 +313,8 @@ d. Can't mount a CDROM.
always give meaningful error messages.
-e. Directory listings are unpredictably truncated, and `dmesg' shows
- `buffer botch' error messages from the driver.
+e. Directory listings are unpredictably truncated, and `dmesg` shows
+ `buffer botch` error messages from the driver.
- There was a bug in the version of the driver in 1.2.x kernels
which could cause this. It was fixed in 1.3.0. If you can't
@@ -335,34 +337,36 @@ f. Data corruption.
5. cdchange.c
-------------
-/*
- * cdchange.c [-v] <device> [<slot>]
- *
- * This loads a CDROM from a specified slot in a changer, and displays
- * information about the changer status. The drive should be unmounted before
- * using this program.
- *
- * Changer information is displayed if either the -v flag is specified
- * or no slot was specified.
- *
- * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
- * Changer status information, and rewrite for the new Uniform CDROM driver
- * interface by Erik Andersen <andersee@debian.org>.
- */
+::
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <string.h>
-#include <unistd.h>
-#include <fcntl.h>
-#include <sys/ioctl.h>
-#include <linux/cdrom.h>
+ /*
+ * cdchange.c [-v] <device> [<slot>]
+ *
+ * This loads a CDROM from a specified slot in a changer, and displays
+ * information about the changer status. The drive should be unmounted before
+ * using this program.
+ *
+ * Changer information is displayed if either the -v flag is specified
+ * or no slot was specified.
+ *
+ * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
+ * Changer status information, and rewrite for the new Uniform CDROM driver
+ * interface by Erik Andersen <andersee@debian.org>.
+ */
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <errno.h>
+ #include <string.h>
+ #include <unistd.h>
+ #include <fcntl.h>
+ #include <sys/ioctl.h>
+ #include <linux/cdrom.h>
-int
-main (int argc, char **argv)
-{
+
+ int
+ main (int argc, char **argv)
+ {
char *program;
char *device;
int fd; /* file descriptor for CD-ROM device */
@@ -382,30 +386,30 @@ main (int argc, char **argv)
fprintf (stderr, " Slots are numbered 1 -- n.\n");
exit (1);
}
-
+
if (strcmp (argv[0], "-v") == 0) {
verbose = 1;
++argv;
--argc;
}
-
+
device = argv[0];
-
+
if (argc == 2)
slot = atoi (argv[1]) - 1;
- /* open device */
+ /* open device */
fd = open(device, O_RDONLY | O_NONBLOCK);
if (fd < 0) {
- fprintf (stderr, "%s: open failed for `%s': %s\n",
+ fprintf (stderr, "%s: open failed for `%s`: %s\n",
program, device, strerror (errno));
exit (1);
}
- /* Check CD player status */
+ /* Check CD player status */
total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS);
if (total_slots_available <= 1 ) {
- fprintf (stderr, "%s: Device `%s' is not an ATAPI "
+ fprintf (stderr, "%s: Device `%s` is not an ATAPI "
"compliant CD changer.\n", program, device);
exit (1);
}
@@ -418,7 +422,7 @@ main (int argc, char **argv)
exit (1);
}
- /* load */
+ /* load */
slot=ioctl (fd, CDROM_SELECT_DISC, slot);
if (slot<0) {
fflush(stdout);
@@ -462,14 +466,14 @@ main (int argc, char **argv)
for (x_slot=0; x_slot<total_slots_available; x_slot++) {
printf ("Slot %2d: ", x_slot+1);
- status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
- if (status<0) {
- perror(" CDROM_DRIVE_STATUS");
- } else switch(status) {
+ status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
+ if (status<0) {
+ perror(" CDROM_DRIVE_STATUS");
+ } else switch(status) {
case CDS_DISC_OK:
printf ("Disc present.");
break;
- case CDS_NO_DISC:
+ case CDS_NO_DISC:
printf ("Empty slot.");
break;
case CDS_TRAY_OPEN:
@@ -507,11 +511,11 @@ main (int argc, char **argv)
break;
}
}
- status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
- if (status<0) {
+ status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
+ if (status<0) {
perror(" CDROM_MEDIA_CHANGED");
- }
- switch (status) {
+ }
+ switch (status) {
case 1:
printf ("Changed.\n");
break;
@@ -525,10 +529,10 @@ main (int argc, char **argv)
/* close device */
status = close (fd);
if (status != 0) {
- fprintf (stderr, "%s: close failed for `%s': %s\n",
+ fprintf (stderr, "%s: close failed for `%s`: %s\n",
program, device, strerror (errno));
exit (1);
}
-
+
exit (0);
-}
+ }
diff --git a/Documentation/cdrom/index.rst b/Documentation/cdrom/index.rst
new file mode 100644
index 000000000000..efbd5d111825
--- /dev/null
+++ b/Documentation/cdrom/index.rst
@@ -0,0 +1,19 @@
+:orphan:
+
+=====
+cdrom
+=====
+
+.. toctree::
+ :maxdepth: 1
+
+ cdrom-standard
+ ide-cd
+ packet-writing
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.rst
similarity index 91%
rename from Documentation/cdrom/packet-writing.txt
rename to Documentation/cdrom/packet-writing.rst
index 2834170d821e..c5c957195a5a 100644
--- a/Documentation/cdrom/packet-writing.txt
+++ b/Documentation/cdrom/packet-writing.rst
@@ -1,3 +1,7 @@
+==============
+Packet writing
+==============
+
Getting started quick
---------------------
@@ -10,13 +14,16 @@ Getting started quick
Download from http://sourceforge.net/projects/linux-udf/
- Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute
- as appropriate):
+ as appropriate)::
+
# cdrwtool -d /dev/hdc -q
-- Setup your writer
+- Setup your writer::
+
# pktsetup dev_name /dev/hdc
-- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy!
+- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy::
+
# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -25,11 +32,11 @@ Packet writing for DVD-RW media
DVD-RW discs can be written to much like CD-RW discs if they are in
the so called "restricted overwrite" mode. To put a disc in restricted
-overwrite mode, run:
+overwrite mode, run::
# dvd+rw-format /dev/hdc
-You can then use the disc the same way you would use a CD-RW disc:
+You can then use the disc the same way you would use a CD-RW disc::
# pktsetup dev_name /dev/hdc
# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -41,7 +48,7 @@ Packet writing for DVD+RW media
According to the DVD+RW specification, a drive supporting DVD+RW discs
shall implement "true random writes with 2KB granularity", which means
that it should be possible to put any filesystem with a block size >=
-2KB on such a disc. For example, it should be possible to do:
+2KB on such a disc. For example, it should be possible to do::
# dvd+rw-format /dev/hdc (only needed if the disc has never
been formatted)
@@ -54,7 +61,7 @@ follow the specification, but suffer bad performance problems if the
writes are not 32KB aligned.
Both problems can be solved by using the pktcdvd driver, which always
-generates aligned writes.
+generates aligned writes::
# dvd+rw-format /dev/hdc
# pktsetup dev_name /dev/hdc
@@ -83,7 +90,7 @@ Notes
- Since the pktcdvd driver makes the disc appear as a regular block
device with a 2KB block size, you can put any filesystem you like on
- the disc. For example, run:
+ the disc. For example, run::
# /sbin/mke2fs /dev/pktcdvd/dev_name
@@ -97,7 +104,7 @@ Since Linux 2.6.20, the pktcdvd module has a sysfs interface
and can be controlled by it. For example the "pktcdvd" tool uses
this interface. (see http://tom.ist-im-web.de/download/pktcdvd )
-"pktcdvd" works similar to "pktsetup", e.g.:
+"pktcdvd" works similar to "pktsetup", e.g.::
# pktcdvd -a dev_name /dev/hdc
# mkudffs /dev/pktcdvd/dev_name
@@ -115,7 +122,7 @@ For a description of the sysfs interface look into the file:
Using the pktcdvd debugfs interface
-----------------------------------
-To read pktcdvd device infos in human readable form, do:
+To read pktcdvd device infos in human readable form, do::
# cat /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/info
diff --git a/MAINTAINERS b/MAINTAINERS
index 8bec064bb353..1f73ef8c25f5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7644,7 +7644,7 @@ IDE/ATAPI DRIVERS
M: Borislav Petkov <bp@alien8.de>
L: linux-ide@vger.kernel.org
S: Maintained
-F: Documentation/cdrom/ide-cd
+F: Documentation/cdrom/ide-cd.rst
F: drivers/ide/ide-cd*
IDEAPAD LAPTOP EXTRAS DRIVER
diff --git a/drivers/block/Kconfig b/drivers/block/Kconfig
index 20bb4bfa4be6..96ec7e0fc1ea 100644
--- a/drivers/block/Kconfig
+++ b/drivers/block/Kconfig
@@ -347,7 +347,7 @@ config CDROM_PKTCDVD
is possible.
DVD-RW disks must be in restricted overwrite mode.
- See the file <file:Documentation/cdrom/packet-writing.txt>
+ See the file <file:Documentation/cdrom/packet-writing.rst>
for further information on the use of this driver.
To compile this driver as a module, choose M here: the
diff --git a/drivers/cdrom/cdrom.c b/drivers/cdrom/cdrom.c
index 5d1e0a4a7d84..ac42ae4651ce 100644
--- a/drivers/cdrom/cdrom.c
+++ b/drivers/cdrom/cdrom.c
@@ -7,7 +7,7 @@
License. See linux/COPYING for more information.
Uniform CD-ROM driver for Linux.
- See Documentation/cdrom/cdrom-standard.txt for usage information.
+ See Documentation/cdrom/cdrom-standard.rst for usage information.
The routines in the file provide a uniform interface between the
software that uses CD-ROMs and the various low-level drivers that
diff --git a/drivers/ide/ide-cd.c b/drivers/ide/ide-cd.c
index 3b15adc6ce98..9d117936bee1 100644
--- a/drivers/ide/ide-cd.c
+++ b/drivers/ide/ide-cd.c
@@ -9,7 +9,7 @@
* May be copied or modified under the terms of the GNU General Public
* License. See linux/COPYING for more information.
*
- * See Documentation/cdrom/ide-cd for usage information.
+ * See Documentation/cdrom/ide-cd.rst for usage information.
*
* Suggestions are welcome. Patches that work are more welcome though. ;-)
*
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 06/28] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (2 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 04/28] docs: cdrom: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 08/28] docs: fault-injection: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (20 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The CFQ scheduler was removed on this changeset:
commit f382fb0bcef4c37dc049e9f6963e3baf204d815c
Author: Jens Axboe <axboe@kernel.dk>
Date: Fri Oct 12 10:14:46 2018 -0600
block: remove legacy IO schedulers
Retain the deadline documentation, as that carries over to mq-deadline
as well.
Tested-by: Ming Lei <ming.lei@redhat.com>
Reviewed-by: Omar Sandoval <osandov@fb.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>
However, the cgroups-v1 documentation still mentions it and points
to a removed file that used to belong to such scheduler.
Add a note about that, as someone needs to fix the document pointing
to another scheduler, if cgroups-v1 blockio is not dependent of
CFQ scheduler.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cgroup-v1/blkio-controller.rst | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/Documentation/cgroup-v1/blkio-controller.rst b/Documentation/cgroup-v1/blkio-controller.rst
index 2c1b907afc14..2836c2c31e63 100644
--- a/Documentation/cgroup-v1/blkio-controller.rst
+++ b/Documentation/cgroup-v1/blkio-controller.rst
@@ -17,6 +17,13 @@ one is throttling policy which can be used to specify upper IO rate limits
on devices. This policy is implemented in generic block layer and can be
used on leaf nodes as well as higher level logical devices like device mapper.
+.. note::
+
+ While this document mentions the CFQ scheduler, it got removed at
+ Kernel 4.20, as there are other schedulers that are more efficient.
+
+ Someone needs to update this file in order to reflect such change.
+
HOWTO
=====
Proportional Weight division of bandwidth
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 08/28] docs: fault-injection: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (3 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 06/28] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 10/28] docs: fpga: " Mauro Carvalho Chehab
` (19 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Akinobu Mita, Federico Vaga, Harry Wei, Alex Shi,
Kees Cook, Arnd Bergmann, Greg Kroah-Hartman
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
...ault-injection.txt => fault-injection.rst} | 265 +++++++++---------
Documentation/fault-injection/index.rst | 20 ++
...r-inject.txt => notifier-error-inject.rst} | 18 +-
.../fault-injection/nvme-fault-injection.rst | 120 ++++++++
.../fault-injection/nvme-fault-injection.txt | 116 --------
.../fault-injection/provoke-crashes.rst | 48 ++++
.../fault-injection/provoke-crashes.txt | 38 ---
Documentation/process/4.Coding.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
include/linux/fault-inject.h | 2 +-
lib/Kconfig.debug | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
14 files changed, 344 insertions(+), 295 deletions(-)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
create mode 100644 Documentation/fault-injection/nvme-fault-injection.rst
delete mode 100644 Documentation/fault-injection/nvme-fault-injection.txt
create mode 100644 Documentation/fault-injection/provoke-crashes.rst
delete mode 100644 Documentation/fault-injection/provoke-crashes.txt
diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.rst
similarity index 68%
rename from Documentation/fault-injection/fault-injection.txt
rename to Documentation/fault-injection/fault-injection.rst
index a17517a083c3..f51bb21d20e4 100644
--- a/Documentation/fault-injection/fault-injection.txt
+++ b/Documentation/fault-injection/fault-injection.rst
@@ -1,3 +1,4 @@
+===========================================
Fault injection capabilities infrastructure
===========================================
@@ -7,36 +8,36 @@ See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug.
Available fault injection capabilities
--------------------------------------
-o failslab
+- failslab
injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
-o fail_page_alloc
+- fail_page_alloc
injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
-o fail_futex
+- fail_futex
injects futex deadlock and uaddr fault errors.
-o fail_make_request
+- fail_make_request
injects disk IO errors on devices permitted by setting
/sys/block/<device>/make-it-fail or
/sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
-o fail_mmc_request
+- fail_mmc_request
injects MMC data errors on devices permitted by setting
debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
-o fail_function
+- fail_function
injects error return on specific functions, which are marked by
ALLOW_ERROR_INJECTION() macro, by setting debugfs entries
under /sys/kernel/debug/fail_function. No boot option supported.
-o NVMe fault injection
+- NVMe fault injection
inject NVMe status code and retry flag on devices permitted by setting
debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default
@@ -47,7 +48,8 @@ o NVMe fault injection
Configure fault-injection capabilities behavior
-----------------------------------------------
-o debugfs entries
+debugfs entries
+^^^^^^^^^^^^^^^
fault-inject-debugfs kernel module provides some debugfs entries for runtime
configuration of fault-injection capabilities.
@@ -55,6 +57,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/probability:
likelihood of failure injection, in percent.
+
Format: <percent>
Note that one-failure-per-hundred is a very high error rate
@@ -83,6 +86,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/verbose
Format: { 0 | 1 | 2 }
+
specifies the verbosity of the messages when failure is
injected. '0' means no messages; '1' will print only a single
log line per failure; '2' will print a call trace too -- useful
@@ -91,14 +95,15 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/task-filter:
Format: { 'Y' | 'N' }
+
A value of 'N' disables filtering by process (default).
Any positive value limits failures to only processes indicated by
/proc/<pid>/make-it-fail==1.
-- /sys/kernel/debug/fail*/require-start:
-- /sys/kernel/debug/fail*/require-end:
-- /sys/kernel/debug/fail*/reject-start:
-- /sys/kernel/debug/fail*/reject-end:
+- /sys/kernel/debug/fail*/require-start,
+ /sys/kernel/debug/fail*/require-end,
+ /sys/kernel/debug/fail*/reject-start,
+ /sys/kernel/debug/fail*/reject-end:
specifies the range of virtual addresses tested during
stacktrace walking. Failure is injected only if some caller
@@ -116,6 +121,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' won't inject failures into
highmem/user allocations.
@@ -123,6 +129,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will inject failures
only into non-sleep allocations (GFP_ATOMIC allocations).
@@ -134,12 +141,14 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_futex/ignore-private:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will disable failure injections
when dealing with private (address space) futexes.
- /sys/kernel/debug/fail_function/inject:
Format: { 'function-name' | '!function-name' | '' }
+
specifies the target function of error injection by name.
If the function name leads '!' prefix, given function is
removed from injection list. If nothing specified ('')
@@ -160,10 +169,11 @@ configuration of fault-injection capabilities.
function for given function. This will be created when
user specifies new injection entry.
-o Boot option
+Boot option
+^^^^^^^^^^^
In order to inject faults while debugfs is not available (early boot time),
-use the boot option:
+use the boot option::
failslab=
fail_page_alloc=
@@ -171,10 +181,11 @@ use the boot option:
fail_futex=
mmc_core.fail_request=<interval>,<probability>,<space>,<times>
-o proc entries
+proc entries
+^^^^^^^^^^^^
-- /proc/<pid>/fail-nth:
-- /proc/self/task/<tid>/fail-nth:
+- /proc/<pid>/fail-nth,
+ /proc/self/task/<tid>/fail-nth:
Write to this file of integer N makes N-th call in the task fail.
Read from this file returns a integer value. A value of '0' indicates
@@ -191,16 +202,16 @@ o proc entries
How to add new fault injection capability
-----------------------------------------
-o #include <linux/fault-inject.h>
+- #include <linux/fault-inject.h>
-o define the fault attributes
+- define the fault attributes
DECLARE_FAULT_ATTR(name);
Please see the definition of struct fault_attr in fault-inject.h
for details.
-o provide a way to configure fault attributes
+- provide a way to configure fault attributes
- boot option
@@ -222,126 +233,126 @@ o provide a way to configure fault attributes
single kernel module, it is better to provide module parameters to
configure the fault attributes.
-o add a hook to insert failures
+- add a hook to insert failures
- Upon should_fail() returning true, client code should inject a failure.
+ Upon should_fail() returning true, client code should inject a failure:
should_fail(attr, size);
Application Examples
--------------------
-o Inject slab allocation failures into module init/exit code
+- Inject slab allocation failures into module init/exit code::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=failslab
-echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ FAILTYPE=failslab
+ echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-faulty_system()
-{
+ faulty_system()
+ {
bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
-}
+ }
-if [ $# -eq 0 ]
-then
+ if [ $# -eq 0 ]
+ then
echo "Usage: $0 modulename [ modulename ... ]"
exit 1
-fi
+ fi
-for m in $*
-do
+ for m in $*
+ do
echo inserting $m...
faulty_system modprobe $m
echo removing $m...
faulty_system modprobe -r $m
-done
+ done
------------------------------------------------------------------------------
-o Inject page allocation failures only for a specific module
+- Inject page allocation failures only for a specific module::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=fail_page_alloc
-module=$1
+ FAILTYPE=fail_page_alloc
+ module=$1
-if [ -z $module ]
-then
+ if [ -z $module ]
+ then
echo "Usage: $0 <modulename>"
exit 1
-fi
+ fi
-modprobe $module
+ modprobe $module
-if [ ! -d /sys/module/$module/sections ]
-then
+ if [ ! -d /sys/module/$module/sections ]
+ then
echo Module $module is not loaded
exit 1
-fi
+ fi
-cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
-cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
+ cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
+ cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
-echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
+ echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
-trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
+ trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
-echo "Injecting errors into the module $module... (interrupt to stop)"
-sleep 1000000
+ echo "Injecting errors into the module $module... (interrupt to stop)"
+ sleep 1000000
------------------------------------------------------------------------------
-o Inject open_ctree error while btrfs mount
+- Inject open_ctree error while btrfs mount::
-#!/bin/bash
+ #!/bin/bash
-rm -f testfile.img
-dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
-DEVICE=$(losetup --show -f testfile.img)
-mkfs.btrfs -f $DEVICE
-mkdir -p tmpmnt
+ rm -f testfile.img
+ dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
+ DEVICE=$(losetup --show -f testfile.img)
+ mkfs.btrfs -f $DEVICE
+ mkdir -p tmpmnt
-FAILTYPE=fail_function
-FAILFUNC=open_ctree
-echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
-echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 100 > /sys/kernel/debug/$FAILTYPE/probability
-echo 0 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
+ FAILTYPE=fail_function
+ FAILFUNC=open_ctree
+ echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
+ echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 100 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 0 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
-mount -t btrfs $DEVICE tmpmnt
-if [ $? -ne 0 ]
-then
+ mount -t btrfs $DEVICE tmpmnt
+ if [ $? -ne 0 ]
+ then
echo "SUCCESS!"
-else
+ else
echo "FAILED!"
umount tmpmnt
-fi
+ fi
-echo > /sys/kernel/debug/$FAILTYPE/inject
+ echo > /sys/kernel/debug/$FAILTYPE/inject
-rmdir tmpmnt
-losetup -d $DEVICE
-rm testfile.img
+ rmdir tmpmnt
+ losetup -d $DEVICE
+ rm testfile.img
Tool to run command with failslab or fail_page_alloc
@@ -354,43 +365,43 @@ see the following examples.
Examples:
Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
-allocation failure.
+allocation failure::
# ./tools/testing/fault-injection/failcmd.sh \
-- make -C tools/testing/selftests/ run_tests
Same as above except to specify 100 times failures at most instead of one time
-at most by default.
+at most by default::
# ./tools/testing/fault-injection/failcmd.sh --times=100 \
-- make -C tools/testing/selftests/ run_tests
Same as above except to inject page allocation failure instead of slab
-allocation failure.
+allocation failure::
# env FAILCMD_TYPE=fail_page_alloc \
./tools/testing/fault-injection/failcmd.sh --times=100 \
- -- make -C tools/testing/selftests/ run_tests
+ -- make -C tools/testing/selftests/ run_tests
Systematic faults using fail-nth
---------------------------------
The following code systematically faults 0-th, 1-st, 2-nd and so on
-capabilities in the socketpair() system call.
+capabilities in the socketpair() system call::
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/socket.h>
-#include <sys/syscall.h>
-#include <fcntl.h>
-#include <unistd.h>
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-#include <errno.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <sys/socket.h>
+ #include <sys/syscall.h>
+ #include <fcntl.h>
+ #include <unistd.h>
+ #include <string.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <errno.h>
-int main()
-{
+ int main()
+ {
int i, err, res, fail_nth, fds[2];
char buf[128];
@@ -413,23 +424,23 @@ int main()
break;
}
return 0;
-}
+ }
-An example output:
+An example output::
-1-th fault Y: res=-1/23
-2-th fault Y: res=-1/23
-3-th fault Y: res=-1/12
-4-th fault Y: res=-1/12
-5-th fault Y: res=-1/23
-6-th fault Y: res=-1/23
-7-th fault Y: res=-1/23
-8-th fault Y: res=-1/12
-9-th fault Y: res=-1/12
-10-th fault Y: res=-1/12
-11-th fault Y: res=-1/12
-12-th fault Y: res=-1/12
-13-th fault Y: res=-1/12
-14-th fault Y: res=-1/12
-15-th fault Y: res=-1/12
-16-th fault N: res=0/12
+ 1-th fault Y: res=-1/23
+ 2-th fault Y: res=-1/23
+ 3-th fault Y: res=-1/12
+ 4-th fault Y: res=-1/12
+ 5-th fault Y: res=-1/23
+ 6-th fault Y: res=-1/23
+ 7-th fault Y: res=-1/23
+ 8-th fault Y: res=-1/12
+ 9-th fault Y: res=-1/12
+ 10-th fault Y: res=-1/12
+ 11-th fault Y: res=-1/12
+ 12-th fault Y: res=-1/12
+ 13-th fault Y: res=-1/12
+ 14-th fault Y: res=-1/12
+ 15-th fault Y: res=-1/12
+ 16-th fault N: res=0/12
diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst
new file mode 100644
index 000000000000..92b5639ed07a
--- /dev/null
+++ b/Documentation/fault-injection/index.rst
@@ -0,0 +1,20 @@
+:orphan:
+
+===============
+fault-injection
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ fault-injection
+ notifier-error-inject
+ nvme-fault-injection
+ provoke-crashes
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/fault-injection/notifier-error-inject.txt b/Documentation/fault-injection/notifier-error-inject.rst
similarity index 83%
rename from Documentation/fault-injection/notifier-error-inject.txt
rename to Documentation/fault-injection/notifier-error-inject.rst
index e861d761de24..1668b6e48d3a 100644
--- a/Documentation/fault-injection/notifier-error-inject.txt
+++ b/Documentation/fault-injection/notifier-error-inject.rst
@@ -14,7 +14,8 @@ modules that can be used to test the following notifiers.
PM notifier error injection module
----------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
Possible PM notifier events to be failed are:
@@ -22,7 +23,7 @@ Possible PM notifier events to be failed are:
* PM_SUSPEND_PREPARE
* PM_RESTORE_PREPARE
-Example: Inject PM suspend error (-12 = -ENOMEM)
+Example: Inject PM suspend error (-12 = -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/pm/
# echo -12 > actions/PM_SUSPEND_PREPARE/error
@@ -32,14 +33,15 @@ Example: Inject PM suspend error (-12 = -ENOMEM)
Memory hotplug notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
Possible memory notifier events to be failed are:
* MEM_GOING_ONLINE
* MEM_GOING_OFFLINE
-Example: Inject memory hotplug offline error (-12 == -ENOMEM)
+Example: Inject memory hotplug offline error (-12 == -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/memory
# echo -12 > actions/MEM_GOING_OFFLINE/error
@@ -49,7 +51,8 @@ Example: Inject memory hotplug offline error (-12 == -ENOMEM)
powerpc pSeries reconfig notifier error injection module
--------------------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
Possible pSeries reconfig notifier events to be failed are:
@@ -61,7 +64,8 @@ Possible pSeries reconfig notifier events to be failed are:
Netdevice notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
Netdevice notifier events which can be failed are:
@@ -75,7 +79,7 @@ Netdevice notifier events which can be failed are:
* NETDEV_PRECHANGEUPPER
* NETDEV_CHANGEUPPER
-Example: Inject netdevice mtu change error (-22 == -EINVAL)
+Example: Inject netdevice mtu change error (-22 == -EINVAL)::
# cd /sys/kernel/debug/notifier-error-inject/netdev
# echo -22 > actions/NETDEV_CHANGEMTU/error
diff --git a/Documentation/fault-injection/nvme-fault-injection.rst b/Documentation/fault-injection/nvme-fault-injection.rst
new file mode 100644
index 000000000000..bbb1bf3e8650
--- /dev/null
+++ b/Documentation/fault-injection/nvme-fault-injection.rst
@@ -0,0 +1,120 @@
+NVMe Fault Injection
+====================
+Linux's fault injection framework provides a systematic way to support
+error injection via debugfs in the /sys/kernel/debug directory. When
+enabled, the default NVME_SC_INVALID_OPCODE with no retry will be
+injected into the nvme_end_request. Users can change the default status
+code and no retry flag via the debugfs. The list of Generic Command
+Status can be found in include/linux/nvme.h
+
+Following examples show how to inject an error into the nvme.
+
+First, enable CONFIG_FAULT_INJECTION_DEBUG_FS kernel config,
+recompile the kernel. After booting up the kernel, do the
+following.
+
+Example 1: Inject default status code with no retry
+---------------------------------------------------
+
+::
+
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ cp a.file /mnt
+
+Expected Result::
+
+ cp: cannot stat ‘/mnt/a.file’: Input/output error
+
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
+ Hardware name: innotek GmbH VirtualBox/VirtualBox,
+ BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x2f/0x50 [nvme_core]
+ nvme_process_cq+0xe7/0x1d0 [nvme]
+ nvme_irq+0x1e/0x40 [nvme]
+ __handle_irq_event_percpu+0x3a/0x190
+ handle_irq_event_percpu+0x30/0x70
+ handle_irq_event+0x36/0x60
+ handle_fasteoi_irq+0x78/0x120
+ handle_irq+0xa7/0x130
+ ? tick_irq_enter+0xa8/0xc0
+ do_IRQ+0x43/0xc0
+ common_interrupt+0xa2/0xa2
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
+ RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
+ R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_kernel+0x4c4/0x4e4
+ ? set_init_arg+0x55/0x55
+ secondary_startup_64+0xa5/0xb0
+ print_req_error: I/O error, dev nvme0n1, sector 9240
+ EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
+ inode #2: comm cp: reading directory lblock 0
+
+Example 2: Inject default status code with retry
+------------------------------------------------
+
+::
+
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
+ echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
+
+ cp a.file /mnt
+
+Expected Result::
+
+ command success without error
+
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
+ Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x30/0x60 [nvme_core]
+ nvme_loop_queue_response+0x84/0x110 [nvme_loop]
+ nvmet_req_complete+0x11/0x40 [nvmet]
+ nvmet_bio_done+0x28/0x40 [nvmet]
+ blk_update_request+0xb0/0x310
+ blk_mq_end_request+0x18/0x60
+ flush_smp_call_function_queue+0x3d/0xf0
+ smp_call_function_single_interrupt+0x2c/0xc0
+ call_function_single_interrupt+0xa2/0xb0
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
+ RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
+ R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_secondary+0x187/0x1e0
+ secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/nvme-fault-injection.txt b/Documentation/fault-injection/nvme-fault-injection.txt
deleted file mode 100644
index 8fbf3bf60b62..000000000000
--- a/Documentation/fault-injection/nvme-fault-injection.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-NVMe Fault Injection
-====================
-Linux's fault injection framework provides a systematic way to support
-error injection via debugfs in the /sys/kernel/debug directory. When
-enabled, the default NVME_SC_INVALID_OPCODE with no retry will be
-injected into the nvme_end_request. Users can change the default status
-code and no retry flag via the debugfs. The list of Generic Command
-Status can be found in include/linux/nvme.h
-
-Following examples show how to inject an error into the nvme.
-
-First, enable CONFIG_FAULT_INJECTION_DEBUG_FS kernel config,
-recompile the kernel. After booting up the kernel, do the
-following.
-
-Example 1: Inject default status code with no retry
----------------------------------------------------
-
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-cp a.file /mnt
-
-Expected Result:
-
-cp: cannot stat ‘/mnt/a.file’: Input/output error
-
-Message from dmesg:
-
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
-Hardware name: innotek GmbH VirtualBox/VirtualBox,
-BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x2f/0x50 [nvme_core]
- nvme_process_cq+0xe7/0x1d0 [nvme]
- nvme_irq+0x1e/0x40 [nvme]
- __handle_irq_event_percpu+0x3a/0x190
- handle_irq_event_percpu+0x30/0x70
- handle_irq_event+0x36/0x60
- handle_fasteoi_irq+0x78/0x120
- handle_irq+0xa7/0x130
- ? tick_irq_enter+0xa8/0xc0
- do_IRQ+0x43/0xc0
- common_interrupt+0xa2/0xa2
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
-RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
-R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_kernel+0x4c4/0x4e4
- ? set_init_arg+0x55/0x55
- secondary_startup_64+0xa5/0xb0
- print_req_error: I/O error, dev nvme0n1, sector 9240
-EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
-inode #2: comm cp: reading directory lblock 0
-
-Example 2: Inject default status code with retry
-------------------------------------------------
-
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
-echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
-
-cp a.file /mnt
-
-Expected Result:
-
-command success without error
-
-Message from dmesg:
-
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
-Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x30/0x60 [nvme_core]
- nvme_loop_queue_response+0x84/0x110 [nvme_loop]
- nvmet_req_complete+0x11/0x40 [nvmet]
- nvmet_bio_done+0x28/0x40 [nvmet]
- blk_update_request+0xb0/0x310
- blk_mq_end_request+0x18/0x60
- flush_smp_call_function_queue+0x3d/0xf0
- smp_call_function_single_interrupt+0x2c/0xc0
- call_function_single_interrupt+0xa2/0xb0
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
-RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
-R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_secondary+0x187/0x1e0
- secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/provoke-crashes.rst b/Documentation/fault-injection/provoke-crashes.rst
new file mode 100644
index 000000000000..9279a3e12278
--- /dev/null
+++ b/Documentation/fault-injection/provoke-crashes.rst
@@ -0,0 +1,48 @@
+===============
+Provoke crashes
+===============
+
+The lkdtm module provides an interface to crash or injure the kernel at
+predefined crashpoints to evaluate the reliability of crash dumps obtained
+using different dumping solutions. The module uses KPROBEs to instrument
+crashing points, but can also crash the kernel directly without KRPOBE
+support.
+
+
+You can provide the way either through module arguments when inserting
+the module, or through a debugfs interface.
+
+Usage::
+
+ insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
+ [cpoint_count={>0}]
+
+recur_count
+ Recursion level for the stack overflow test. Default is 10.
+
+cpoint_name
+ Crash point where the kernel is to be crashed. It can be
+ one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
+ FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
+ IDE_CORE_CP, DIRECT
+
+cpoint_type
+ Indicates the action to be taken on hitting the crash point.
+ It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
+ CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
+ WRITE_AFTER_FREE,
+
+cpoint_count
+ Indicates the number of times the crash point is to be hit
+ to trigger an action. The default is 10.
+
+You can also induce failures by mounting debugfs and writing the type to
+<mountpoint>/provoke-crash/<crashpoint>. E.g.::
+
+ mount -t debugfs debugfs /mnt
+ echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
+
+
+A special file is `DIRECT` which will induce the crash directly without
+KPROBE instrumentation. This mode is the only one available when the module
+is built on a kernel without KPROBEs support.
diff --git a/Documentation/fault-injection/provoke-crashes.txt b/Documentation/fault-injection/provoke-crashes.txt
deleted file mode 100644
index 7a9d3d81525b..000000000000
--- a/Documentation/fault-injection/provoke-crashes.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-The lkdtm module provides an interface to crash or injure the kernel at
-predefined crashpoints to evaluate the reliability of crash dumps obtained
-using different dumping solutions. The module uses KPROBEs to instrument
-crashing points, but can also crash the kernel directly without KRPOBE
-support.
-
-
-You can provide the way either through module arguments when inserting
-the module, or through a debugfs interface.
-
-Usage: insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
- [cpoint_count={>0}]
-
- recur_count : Recursion level for the stack overflow test. Default is 10.
-
- cpoint_name : Crash point where the kernel is to be crashed. It can be
- one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
- FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
- IDE_CORE_CP, DIRECT
-
- cpoint_type : Indicates the action to be taken on hitting the crash point.
- It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
- CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
- WRITE_AFTER_FREE,
-
- cpoint_count : Indicates the number of times the crash point is to be hit
- to trigger an action. The default is 10.
-
-You can also induce failures by mounting debugfs and writing the type to
-<mountpoint>/provoke-crash/<crashpoint>. E.g.,
-
- mount -t debugfs debugfs /mnt
- echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
-
-
-A special file is `DIRECT' which will induce the crash directly without
-KPROBE instrumentation. This mode is the only one available when the module
-is built on a kernel without KPROBEs support.
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 4b7a5ab3cec1..13dd893c9f88 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -298,7 +298,7 @@ enabled, a configurable percentage of memory allocations will be made to
fail; these failures can be restricted to a specific range of code.
Running with fault injection enabled allows the programmer to see how the
code responds when things go badly. See
-Documentation/fault-injection/fault-injection.txt for more information on
+Documentation/fault-injection/fault-injection.rst for more information on
how to use this facility.
Other kinds of errors can be found with the "sparse" static analysis tool.
diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst
index c05b89e616dd..a5e36aa60448 100644
--- a/Documentation/translations/it_IT/process/4.Coding.rst
+++ b/Documentation/translations/it_IT/process/4.Coding.rst
@@ -314,7 +314,7 @@ di allocazione di memoria sarà destinata al fallimento; questi fallimenti
possono essere ridotti ad uno specifico pezzo di codice. Procedere con
l'inserimento dei fallimenti attivo permette al programmatore di verificare
come il codice risponde quando le cose vanno male. Consultate:
-Documentation/fault-injection/fault-injection.txt per avere maggiori
+Documentation/fault-injection/fault-injection.rst per avere maggiori
informazioni su come utilizzare questo strumento.
Altre tipologie di errori possono essere riscontrati con lo strumento di
diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
index 8bb777941394..b82b1dde3122 100644
--- a/Documentation/translations/zh_CN/process/4.Coding.rst
+++ b/Documentation/translations/zh_CN/process/4.Coding.rst
@@ -205,7 +205,7 @@ Linus对这个问题给出了最佳答案:
启用故障注入后，内存分配的可配置百分比将失败；这些失败可以限制在特定的代码
范围内。在启用了故障注入的情况下运行，程序员可以看到当情况恶化时代码如何响
应。有关如何使用此工具的详细信息，请参阅
-Documentation/fault-injection/fault-injection.txt。
+Documentation/fault-injection/fault-injection.rst。
使用“sparse”静态分析工具可以发现其他类型的错误。对于sparse，可以警告程序员
用户空间和内核空间地址之间的混淆、big endian和small endian数量的混合、在需
diff --git a/drivers/misc/lkdtm/core.c b/drivers/misc/lkdtm/core.c
index df9429e3fd3a..c7a507482051 100644
--- a/drivers/misc/lkdtm/core.c
+++ b/drivers/misc/lkdtm/core.c
@@ -15,7 +15,7 @@
*
* Debugfs support added by Simon Kagstrom <simon.kagstrom@netinsight.net>
*
- * See Documentation/fault-injection/provoke-crashes.txt for instructions
+ * See Documentation/fault-injection/provoke-crashes.rst for instructions
*/
#include "lkdtm.h"
#include <linux/fs.h>
diff --git a/include/linux/fault-inject.h b/include/linux/fault-inject.h
index 7e6c77740413..e525f6957c49 100644
--- a/include/linux/fault-inject.h
+++ b/include/linux/fault-inject.h
@@ -11,7 +11,7 @@
/*
* For explanation of the elements of this struct, see
- * Documentation/fault-injection/fault-injection.txt
+ * Documentation/fault-injection/fault-injection.rst
*/
struct fault_attr {
unsigned long probability;
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index d08f5848958e..3a3554e8ca0f 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1701,7 +1701,7 @@ config LKDTM
called lkdtm.
Documentation on how to use the module can be found in
- Documentation/fault-injection/provoke-crashes.txt
+ Documentation/fault-injection/provoke-crashes.rst
config TEST_LIST_SORT
tristate "Linked list sorting test"
diff --git a/tools/testing/fault-injection/failcmd.sh b/tools/testing/fault-injection/failcmd.sh
index 29a6c63c5a15..78dac34264be 100644
--- a/tools/testing/fault-injection/failcmd.sh
+++ b/tools/testing/fault-injection/failcmd.sh
@@ -42,7 +42,7 @@ OPTIONS
--interval=value, --space=value, --verbose=value, --task-filter=value,
--stacktrace-depth=value, --require-start=value, --require-end=value,
--reject-start=value, --reject-end=value, --ignore-gfp-wait=value
- See Documentation/fault-injection/fault-injection.txt for more
+ See Documentation/fault-injection/fault-injection.rst for more
information
failslab options:
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 10/28] docs: fpga: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (4 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 08/28] docs: fault-injection: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 11/28] docs: ide: " Mauro Carvalho Chehab
` (18 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Wu Hao, Alan Tull, Moritz Fischer, linux-fpga
The dfl.txt file is almost there. It needs just a few
adjustments to be properly parsed.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/fpga/{dfl.txt => dfl.rst} | 58 ++++++++++++++-----------
Documentation/fpga/index.rst | 17 ++++++++
MAINTAINERS | 2 +-
3 files changed, 50 insertions(+), 27 deletions(-)
rename Documentation/fpga/{dfl.txt => dfl.rst} (89%)
create mode 100644 Documentation/fpga/index.rst
diff --git a/Documentation/fpga/dfl.txt b/Documentation/fpga/dfl.rst
similarity index 89%
rename from Documentation/fpga/dfl.txt
rename to Documentation/fpga/dfl.rst
index 6df4621c3f2a..2f125abd777f 100644
--- a/Documentation/fpga/dfl.txt
+++ b/Documentation/fpga/dfl.rst
@@ -1,9 +1,12 @@
-===============================================================================
- FPGA Device Feature List (DFL) Framework Overview
--------------------------------------------------------------------------------
- Enno Luebbers <enno.luebbers@intel.com>
- Xiao Guangrong <guangrong.xiao@linux.intel.com>
- Wu Hao <hao.wu@intel.com>
+=================================================
+FPGA Device Feature List (DFL) Framework Overview
+=================================================
+
+Authors:
+
+- Enno Luebbers <enno.luebbers@intel.com>
+- Xiao Guangrong <guangrong.xiao@linux.intel.com>
+- Wu Hao <hao.wu@intel.com>
The Device Feature List (DFL) FPGA framework (and drivers according to this
this framework) hides the very details of low layer hardwares and provides
@@ -19,7 +22,7 @@ Device Feature List (DFL) defines a linked list of feature headers within the
device MMIO space to provide an extensible way of adding features. Software can
walk through these predefined data structures to enumerate FPGA features:
FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features,
-as illustrated below:
+as illustrated below::
Header Header Header Header
+----------+ +-->+----------+ +-->+----------+ +-->+----------+
@@ -81,9 +84,9 @@ and release it using close().
The following functions are exposed through ioctls:
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Program bitstream (DFL_FPGA_FME_PORT_PR)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Program bitstream (DFL_FPGA_FME_PORT_PR)
More functions are exposed through sysfs
(/sys/class/fpga_region/regionX/dfl-fme.n/):
@@ -118,18 +121,19 @@ port by using open() on the port device node and release it using close().
The following functions are exposed through ioctls:
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Get port info (DFL_FPGA_PORT_GET_INFO)
- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
- Reset AFU (*DFL_FPGA_PORT_RESET)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Get port info (DFL_FPGA_PORT_GET_INFO)
+- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
+- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
+- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
+- Reset AFU (DFL_FPGA_PORT_RESET)
-*DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port
-reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
-never cause any system level issue, only functional failure (e.g. DMA or PR
-operation failure) and be recoverable from the failure.
+DFL_FPGA_PORT_RESET:
+ reset the FPGA Port and its AFU. Userspace can do Port
+ reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
+ never cause any system level issue, only functional failure (e.g. DMA or PR
+ operation failure) and be recoverable from the failure.
User-space applications can also mmap() accelerator MMIO regions.
@@ -143,6 +147,8 @@ More functions are exposed through sysfs:
DFL Framework Overview
======================
+::
+
+----------+ +--------+ +--------+ +--------+
| FME | | AFU | | AFU | | AFU |
| Module | | Module | | Module | | Module |
@@ -151,7 +157,7 @@ DFL Framework Overview
| FPGA Container Device | Device Feature List
| (FPGA Base Region) | Framework
+-----------------------+
---------------------------------------------------------------------
+ ------------------------------------------------------------------
+----------------------------+
| FPGA DFL Device Module |
| (e.g. PCIE/Platform Device)|
@@ -220,7 +226,7 @@ the sysfs hierarchy under /sys/class/fpga_region.
In the example below, two DFL based FPGA devices are installed in the host. Each
fpga device has one FME and two ports (AFUs).
-FPGA regions are created under /sys/class/fpga_region/
+FPGA regions are created under /sys/class/fpga_region/::
/sys/class/fpga_region/region0
/sys/class/fpga_region/region1
@@ -231,7 +237,7 @@ Application needs to search each regionX folder, if feature device is found,
(e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base
fpga region which represents the FPGA device.
-Each base region has one FME and two ports (AFUs) as child devices:
+Each base region has one FME and two ports (AFUs) as child devices::
/sys/class/fpga_region/region0/dfl-fme.0
/sys/class/fpga_region/region0/dfl-port.0
@@ -243,7 +249,7 @@ Each base region has one FME and two ports (AFUs) as child devices:
/sys/class/fpga_region/region3/dfl-port.3
...
-In general, the FME/AFU sysfs interfaces are named as follows:
+In general, the FME/AFU sysfs interfaces are named as follows::
/sys/class/fpga_region/<regionX>/<dfl-fme.n>/
/sys/class/fpga_region/<regionX>/<dfl-port.m>/
@@ -251,7 +257,7 @@ In general, the FME/AFU sysfs interfaces are named as follows:
with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all
ports.
-The device nodes used for ioctl() or mmap() can be referenced through:
+The device nodes used for ioctl() or mmap() can be referenced through::
/sys/class/fpga_region/<regionX>/<dfl-fme.n>/dev
/sys/class/fpga_region/<regionX>/<dfl-port.n>/dev
diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst
new file mode 100644
index 000000000000..2c87d1ea084f
--- /dev/null
+++ b/Documentation/fpga/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+====
+fpga
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ dfl
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/MAINTAINERS b/MAINTAINERS
index 5ed1fc93969a..5fdbf6e78d46 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6283,7 +6283,7 @@ FPGA DFL DRIVERS
M: Wu Hao <hao.wu@intel.com>
L: linux-fpga@vger.kernel.org
S: Maintained
-F: Documentation/fpga/dfl.txt
+F: Documentation/fpga/dfl.rst
F: include/uapi/linux/fpga-dfl.h
F: drivers/fpga/dfl*
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 11/28] docs: ide: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (5 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 10/28] docs: fpga: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 13/28] docs: kdump: " Mauro Carvalho Chehab
` (17 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Borislav Petkov, Jens Axboe, David S. Miller,
Geert Uytterhoeven, linux-ide, linux-m68k
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Geert Uytterhoeven <geert@linux-m68k.org>
---
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/cdrom/ide-cd.rst | 18 +--
Documentation/ide/changelogs.rst | 17 ++
.../ide/{ide-tape.txt => ide-tape.rst} | 23 +--
Documentation/ide/{ide.txt => ide.rst} | 147 ++++++++++--------
Documentation/ide/index.rst | 21 +++
...arm-plug-howto.txt => warm-plug-howto.rst} | 10 +-
arch/m68k/q40/README | 2 +-
drivers/ide/Kconfig | 20 +--
9 files changed, 155 insertions(+), 105 deletions(-)
create mode 100644 Documentation/ide/changelogs.rst
rename Documentation/ide/{ide-tape.txt => ide-tape.rst} (83%)
rename Documentation/ide/{ide.txt => ide.rst} (72%)
create mode 100644 Documentation/ide/index.rst
rename Documentation/ide/{warm-plug-howto.txt => warm-plug-howto.rst} (61%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 581d8888e829..affed5d447de 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1502,7 +1502,7 @@
Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc
.vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr
.cdrom .chs .ignore_cable are additional options
- See Documentation/ide/ide.txt.
+ See Documentation/ide/ide.rst.
ide-generic.probe-mask= [HW] (E)IDE subsystem
Format: <int>
diff --git a/Documentation/cdrom/ide-cd.rst b/Documentation/cdrom/ide-cd.rst
index dadc94ef6b6c..bdccb74fc92d 100644
--- a/Documentation/cdrom/ide-cd.rst
+++ b/Documentation/cdrom/ide-cd.rst
@@ -47,7 +47,7 @@ This driver provides the following features:
---------------
0. The ide-cd relies on the ide disk driver. See
- Documentation/ide/ide.txt for up-to-date information on the ide
+ Documentation/ide/ide.rst for up-to-date information on the ide
driver.
1. Make sure that the ide and ide-cd drivers are compiled into the
@@ -62,7 +62,7 @@ This driver provides the following features:
Depending on what type of IDE interface you have, you may need to
specify additional configuration options. See
- Documentation/ide/ide.txt.
+ Documentation/ide/ide.rst.
2. You should also ensure that the iso9660 filesystem is either
compiled into the kernel or available as a loadable module. You
@@ -82,7 +82,7 @@ This driver provides the following features:
on the primary IDE interface are called `hda` and `hdb`,
respectively. The drives on the secondary interface are called
`hdc` and `hdd`. (Interfaces at other locations get other letters
- in the third position; see Documentation/ide/ide.txt.)
+ in the third position; see Documentation/ide/ide.rst.)
If you want your CDROM drive to be found automatically by the
driver, you should make sure your IDE interface uses either the
@@ -91,7 +91,7 @@ This driver provides the following features:
be jumpered as `master`. (If for some reason you cannot configure
your system in this manner, you can probably still use the driver.
You may have to pass extra configuration information to the kernel
- when you boot, however. See Documentation/ide/ide.txt for more
+ when you boot, however. See Documentation/ide/ide.rst for more
information.)
4. Boot the system. If the drive is recognized, you should see a
@@ -163,7 +163,7 @@ to change. If the slot number is -1, the drive is unloaded.
This section discusses some common problems encountered when trying to
use the driver, and some possible solutions. Note that if you are
experiencing problems, you should probably also review
-Documentation/ide/ide.txt for current information about the underlying
+Documentation/ide/ide.rst for current information about the underlying
IDE support code. Some of these items apply only to earlier versions
of the driver, but are mentioned here for completeness.
@@ -173,7 +173,7 @@ from the driver.
a. Drive is not detected during booting.
- Review the configuration instructions above and in
- Documentation/ide/ide.txt, and check how your hardware is
+ Documentation/ide/ide.rst, and check how your hardware is
configured.
- If your drive is the only device on an IDE interface, it should
@@ -181,7 +181,7 @@ a. Drive is not detected during booting.
- If your IDE interface is not at the standard addresses of 0x170
or 0x1f0, you'll need to explicitly inform the driver using a
- lilo option. See Documentation/ide/ide.txt. (This feature was
+ lilo option. See Documentation/ide/ide.rst. (This feature was
added around kernel version 1.3.30.)
- If the autoprobing is not finding your drive, you can tell the
@@ -207,7 +207,7 @@ a. Drive is not detected during booting.
Support for some interfaces needing extra initialization is
provided in later 1.3.x kernels. You may need to turn on
additional kernel configuration options to get them to work;
- see Documentation/ide/ide.txt.
+ see Documentation/ide/ide.rst.
Even if support is not available for your interface, you may be
able to get it to work with the following procedure. First boot
@@ -261,7 +261,7 @@ c. System hangups.
be worked around by specifying the `serialize` option when
booting. Recent kernels should be able to detect the need for
this automatically in most cases, but the detection is not
- foolproof. See Documentation/ide/ide.txt for more information
+ foolproof. See Documentation/ide/ide.rst for more information
about the `serialize` option and the CMD640B.
- Note that many MS-DOS CDROM drivers will work with such buggy
diff --git a/Documentation/ide/changelogs.rst b/Documentation/ide/changelogs.rst
new file mode 100644
index 000000000000..fdf9d0fb8027
--- /dev/null
+++ b/Documentation/ide/changelogs.rst
@@ -0,0 +1,17 @@
+Changelog for ide cd
+--------------------
+
+ .. include:: ChangeLog.ide-cd.1994-2004
+ :literal:
+
+Changelog for ide floppy
+------------------------
+
+ .. include:: ChangeLog.ide-floppy.1996-2002
+ :literal:
+
+Changelog for ide tape
+----------------------
+
+ .. include:: ChangeLog.ide-tape.1995-2002
+ :literal:
diff --git a/Documentation/ide/ide-tape.txt b/Documentation/ide/ide-tape.rst
similarity index 83%
rename from Documentation/ide/ide-tape.txt
rename to Documentation/ide/ide-tape.rst
index 3f348a0b21d8..3e061d9c0e38 100644
--- a/Documentation/ide/ide-tape.txt
+++ b/Documentation/ide/ide-tape.rst
@@ -1,4 +1,6 @@
-IDE ATAPI streaming tape driver.
+===============================
+IDE ATAPI streaming tape driver
+===============================
This driver is a part of the Linux ide driver.
@@ -10,14 +12,14 @@ to the request-list of the block device, and waits for their completion.
The block device major and minor numbers are determined from the
tape's relative position in the ide interfaces, as explained in ide.c.
-The character device interface consists of the following devices:
+The character device interface consists of the following devices::
-ht0 major 37, minor 0 first IDE tape, rewind on close.
-ht1 major 37, minor 1 second IDE tape, rewind on close.
-...
-nht0 major 37, minor 128 first IDE tape, no rewind on close.
-nht1 major 37, minor 129 second IDE tape, no rewind on close.
-...
+ ht0 major 37, minor 0 first IDE tape, rewind on close.
+ ht1 major 37, minor 1 second IDE tape, rewind on close.
+ ...
+ nht0 major 37, minor 128 first IDE tape, no rewind on close.
+ nht1 major 37, minor 129 second IDE tape, no rewind on close.
+ ...
The general magnetic tape commands compatible interface, as defined by
include/linux/mtio.h, is accessible through the character device.
@@ -40,9 +42,10 @@ Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
Here are some words from the first releases of hd.c, which are quoted
in ide.c and apply here as well:
-| Special care is recommended. Have Fun!
+* Special care is recommended. Have Fun!
-Possible improvements:
+Possible improvements
+=====================
1. Support for the ATAPI overlap protocol.
diff --git a/Documentation/ide/ide.txt b/Documentation/ide/ide.rst
similarity index 72%
rename from Documentation/ide/ide.txt
rename to Documentation/ide/ide.rst
index 7aca987c23d9..88bdcba92f7d 100644
--- a/Documentation/ide/ide.txt
+++ b/Documentation/ide/ide.rst
@@ -1,41 +1,43 @@
-
- Information regarding the Enhanced IDE drive in Linux 2.6
-
-==============================================================================
-
+============================================
+Information regarding the Enhanced IDE drive
+============================================
The hdparm utility can be used to control various IDE features on a
running system. It is packaged separately. Please Look for it on popular
linux FTP sites.
+-------------------------------------------------------------------------------
+.. important::
-*** IMPORTANT NOTICES: BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
-*** =================
-*** PCI versions of the CMD640 and RZ1000 interfaces are now detected
-*** automatically at startup when PCI BIOS support is configured.
-***
-*** Linux disables the "prefetch" ("readahead") mode of the RZ1000
-*** to prevent data corruption possible due to hardware design flaws.
-***
-*** For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
-*** drive for which the "prefetch" mode of the CMD640 is turned on.
-*** If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
-*** used again.
-***
-*** For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
-*** for which the "prefetch" mode of the CMD640 is turned off.
-*** If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
-*** used again.
-***
-*** The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
-*** automatically detected by Linux. For safe, reliable operation with such
-*** interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
-***
-*** Use of the "serialize" option is no longer necessary.
-
-================================================================================
-Common pitfalls:
+ BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
+
+ PCI versions of the CMD640 and RZ1000 interfaces are now detected
+ automatically at startup when PCI BIOS support is configured.
+
+ Linux disables the "prefetch" ("readahead") mode of the RZ1000
+ to prevent data corruption possible due to hardware design flaws.
+
+ For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
+ drive for which the "prefetch" mode of the CMD640 is turned on.
+ If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
+ used again.
+
+ For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
+ for which the "prefetch" mode of the CMD640 is turned off.
+ If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
+ used again.
+
+ The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
+ automatically detected by Linux. For safe, reliable operation with such
+ interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
+
+ Use of the "serialize" option is no longer necessary.
+
+-------------------------------------------------------------------------------
+
+Common pitfalls
+===============
- 40-conductor IDE cables are capable of transferring data in DMA modes up to
udma2, but no faster.
@@ -49,19 +51,18 @@ Common pitfalls:
- Even better try to stick to the same vendor and device type on the same
cable.
-================================================================================
-
-This is the multiple IDE interface driver, as evolved from hd.c.
+This is the multiple IDE interface driver, as evolved from hd.c
+===============================================================
It supports up to 9 IDE interfaces per default, on one or more IRQs (usually
-14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.
+14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.::
-Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
-Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
-Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
-Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
-fifth.. ide4, usually PCI, probed
-sixth.. ide5, usually PCI, probed
+ Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
+ Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
+ Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
+ Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
+ fifth.. ide4, usually PCI, probed
+ sixth.. ide5, usually PCI, probed
To access devices on interfaces > ide0, device entries please make sure that
device files for them are present in /dev. If not, please create such
@@ -80,12 +81,15 @@ seldom occurs. Be careful, and if in doubt, don't do it!
Drives are normally found by auto-probing and/or examining the CMOS/BIOS data.
For really weird situations, the apparent (fdisk) geometry can also be specified
-on the kernel "command line" using LILO. The format of such lines is:
+on the kernel "command line" using LILO. The format of such lines is::
ide_core.chs=[interface_number.device_number]:cyls,heads,sects
-or ide_core.cdrom=[interface_number.device_number]
-For example:
+or::
+
+ ide_core.cdrom=[interface_number.device_number]
+
+For example::
ide_core.chs=1.0:1050,32,64 ide_core.cdrom=1.1
@@ -96,10 +100,12 @@ geometry for partitioning purposes (fdisk).
If the auto-probing during boot time confuses a drive (ie. the drive works
with hd.c but not with ide.c), then an command line option may be specified
for each drive for which you'd like the drive to skip the hardware
-probe/identification sequence. For example:
+probe/identification sequence. For example::
ide_core.noprobe=0.1
-or
+
+or::
+
ide_core.chs=1.0:768,16,32
ide_core.noprobe=1.0
@@ -115,22 +121,24 @@ Such drives will be identified at boot time, just like a hard disk.
If for some reason your cdrom drive is *not* found at boot time, you can force
the probe to look harder by supplying a kernel command line parameter
-via LILO, such as:
+via LILO, such as:::
ide_core.cdrom=1.0 /* "master" on second interface (hdc) */
-or
+
+or::
+
ide_core.cdrom=1.1 /* "slave" on second interface (hdd) */
For example, a GW2000 system might have a hard drive on the primary
interface (/dev/hda) and an IDE cdrom drive on the secondary interface
-(/dev/hdc). To mount a CD in the cdrom drive, one would use something like:
+(/dev/hdc). To mount a CD in the cdrom drive, one would use something like::
ln -sf /dev/hdc /dev/cdrom
mkdir /mnt/cdrom
mount /dev/cdrom /mnt/cdrom -t iso9660 -o ro
If, after doing all of the above, mount doesn't work and you see
-errors from the driver (with dmesg) complaining about `status=0xff',
+errors from the driver (with dmesg) complaining about `status=0xff`,
this means that the hardware is not responding to the driver's attempts
to read it. One of the following is probably the problem:
@@ -165,7 +173,7 @@ drivers can always be compiled as loadable modules, the chipset drivers
can only be compiled into the kernel, and the core code (ide.c) can be
compiled as a loadable module provided no chipset support is needed.
-When using ide.c as a module in combination with kmod, add:
+When using ide.c as a module in combination with kmod, add::
alias block-major-3 ide-probe
@@ -176,10 +184,8 @@ driver using the "options=" keyword to insmod, while replacing any ',' with
';'.
-================================================================================
-
Summary of ide driver parameters for kernel command line
---------------------------------------------------------
+========================================================
For legacy IDE VLB host drivers (ali14xx/dtc2278/ht6560b/qd65xx/umc8672)
you need to explicitly enable probing by using "probe" kernel parameter,
@@ -226,28 +232,31 @@ Other kernel parameters for ide_core are:
* "chs=[interface_number.device_number]" to force device as a disk (using CHS)
-================================================================================
Some Terminology
-----------------
-IDE = Integrated Drive Electronics, meaning that each drive has a built-in
-controller, which is why an "IDE interface card" is not a "controller card".
+================
-ATA = AT (the old IBM 286 computer) Attachment Interface, a draft American
-National Standard for connecting hard drives to PCs. This is the official
-name for "IDE".
+IDE
+ Integrated Drive Electronics, meaning that each drive has a built-in
+ controller, which is why an "IDE interface card" is not a "controller card".
-The latest standards define some enhancements, known as the ATA-6 spec,
-which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+ATA
+ AT (the old IBM 286 computer) Attachment Interface, a draft American
+ National Standard for connecting hard drives to PCs. This is the official
+ name for "IDE".
-ATAPI = ATA Packet Interface, a new protocol for controlling the drives,
-similar to SCSI protocols, created at the same time as the ATA2 standard.
-ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
-LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
-drives.
+ The latest standards define some enhancements, known as the ATA-6 spec,
+ which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+
+ATAPI
+ ATA Packet Interface, a new protocol for controlling the drives,
+ similar to SCSI protocols, created at the same time as the ATA2 standard.
+ ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
+ LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
+ drives.
mlord@pobox.com
---
+
Wed Apr 17 22:52:44 CEST 2002 edited by Marcin Dalecki, the current
maintainer.
diff --git a/Documentation/ide/index.rst b/Documentation/ide/index.rst
new file mode 100644
index 000000000000..45bc12d3957f
--- /dev/null
+++ b/Documentation/ide/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+==================================
+Integrated Drive Electronics (IDE)
+==================================
+
+.. toctree::
+ :maxdepth: 1
+
+ ide
+ ide-tape
+ warm-plug-howto
+
+ changelogs
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/ide/warm-plug-howto.txt b/Documentation/ide/warm-plug-howto.rst
similarity index 61%
rename from Documentation/ide/warm-plug-howto.txt
rename to Documentation/ide/warm-plug-howto.rst
index 98152bcd515a..c245242ef2f1 100644
--- a/Documentation/ide/warm-plug-howto.txt
+++ b/Documentation/ide/warm-plug-howto.rst
@@ -1,14 +1,14 @@
-
+===================
IDE warm-plug HOWTO
===================
-To warm-plug devices on a port 'idex':
+To warm-plug devices on a port 'idex'::
-# echo -n "1" > /sys/class/ide_port/idex/delete_devices
+ # echo -n "1" > /sys/class/ide_port/idex/delete_devices
-unplug old device(s) and plug new device(s)
+unplug old device(s) and plug new device(s)::
-# echo -n "1" > /sys/class/ide_port/idex/scan
+ # echo -n "1" > /sys/class/ide_port/idex/scan
done
diff --git a/arch/m68k/q40/README b/arch/m68k/q40/README
index 93f4c4cd3c45..a4991d2d8af6 100644
--- a/arch/m68k/q40/README
+++ b/arch/m68k/q40/README
@@ -31,7 +31,7 @@ drivers used by the Q40, apart from the very obvious (console etc.):
char/joystick/* # most of this should work, not
# in default config.in
block/q40ide.c # startup for ide
- ide* # see Documentation/ide/ide.txt
+ ide* # see Documentation/ide/ide.rst
floppy.c # normal PC driver, DMA emu in asm/floppy.h
# and arch/m68k/kernel/entry.S
# see drivers/block/README.fd
diff --git a/drivers/ide/Kconfig b/drivers/ide/Kconfig
index fdd2a62f9d52..9eada392df15 100644
--- a/drivers/ide/Kconfig
+++ b/drivers/ide/Kconfig
@@ -25,13 +25,13 @@ menuconfig IDE
To compile this driver as a module, choose M here: the
module will be called ide-core.
- For further information, please read <file:Documentation/ide/ide.txt>.
+ For further information, please read <file:Documentation/ide/ide.rst>.
If unsure, say N.
if IDE
-comment "Please see Documentation/ide/ide.txt for help/info on IDE drives"
+comment "Please see Documentation/ide/ide.rst for help/info on IDE drives"
config IDE_XFER_MODE
bool
@@ -163,7 +163,7 @@ config BLK_DEV_IDETAPE
along with other IDE devices, as "hdb" or "hdc", or something
similar, and will be mapped to a character device such as "ht0"
(check the boot messages with dmesg). Be sure to consult the
- <file:drivers/ide/ide-tape.c> and <file:Documentation/ide/ide.txt>
+ <file:drivers/ide/ide-tape.c> and <file:Documentation/ide/ide.rst>
files for usage information.
To compile this driver as a module, choose M here: the
@@ -251,7 +251,7 @@ config BLK_DEV_CMD640
The CMD640 chip is also used on add-in cards by Acculogic, and on
the "CSA-6400E PCI to IDE controller" that some people have. For
- details, read <file:Documentation/ide/ide.txt>.
+ details, read <file:Documentation/ide/ide.rst>.
config BLK_DEV_CMD640_ENHANCED
bool "CMD640 enhanced support"
@@ -259,7 +259,7 @@ config BLK_DEV_CMD640_ENHANCED
help
This option includes support for setting/autotuning PIO modes and
prefetch on CMD640 IDE interfaces. For details, read
- <file:Documentation/ide/ide.txt>. If you have a CMD640 IDE interface
+ <file:Documentation/ide/ide.rst>. If you have a CMD640 IDE interface
and your BIOS does not already do this for you, then say Y here.
Otherwise say N.
@@ -819,7 +819,7 @@ config BLK_DEV_ALI14XX
boot parameter. It enables support for the secondary IDE interface
of the ALI M1439/1443/1445/1487/1489 chipsets, and permits faster
I/O speeds to be set as well.
- See the files <file:Documentation/ide/ide.txt> and
+ See the files <file:Documentation/ide/ide.rst> and
<file:drivers/ide/ali14xx.c> for more info.
config BLK_DEV_DTC2278
@@ -830,7 +830,7 @@ config BLK_DEV_DTC2278
This driver is enabled at runtime using the "dtc2278.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the DTC-2278 card, and permits faster I/O speeds to be set as
- well. See the <file:Documentation/ide/ide.txt> and
+ well. See the <file:Documentation/ide/ide.rst> and
<file:drivers/ide/dtc2278.c> files for more info.
config BLK_DEV_HT6560B
@@ -841,7 +841,7 @@ config BLK_DEV_HT6560B
This driver is enabled at runtime using the "ht6560b.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the Holtek card, and permits faster I/O speeds to be set as well.
- See the <file:Documentation/ide/ide.txt> and
+ See the <file:Documentation/ide/ide.rst> and
<file:drivers/ide/ht6560b.c> files for more info.
config BLK_DEV_QD65XX
@@ -851,7 +851,7 @@ config BLK_DEV_QD65XX
help
This driver is enabled at runtime using the "qd65xx.probe" kernel
boot parameter. It permits faster I/O speeds to be set. See the
- <file:Documentation/ide/ide.txt> and <file:drivers/ide/qd65xx.c>
+ <file:Documentation/ide/ide.rst> and <file:drivers/ide/qd65xx.c>
for more info.
config BLK_DEV_UMC8672
@@ -862,7 +862,7 @@ config BLK_DEV_UMC8672
This driver is enabled at runtime using the "umc8672.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the UMC-8672, and permits faster I/O speeds to be set as well.
- See the files <file:Documentation/ide/ide.txt> and
+ See the files <file:Documentation/ide/ide.rst> and
<file:drivers/ide/umc8672.c> for more info.
endif
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 13/28] docs: kdump: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (6 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 11/28] docs: ide: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 14/28] docs: locking: " Mauro Carvalho Chehab
` (16 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Dave Young, Baoquan He, Vivek Goyal,
Benjamin Herrenschmidt, Paul Mackerras, Michael Ellerman,
Harry Wei, Alex Shi, Wim Van Sebroeck, Guenter Roeck,
Russell King, Catalin Marinas, Will Deacon, Yoshinori Sato,
Rich Felker, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
H. Peter Anvin, x86, kexec, linuxppc-dev, linux-watchdog,
linux-arm-kernel, linux-sh
Convert kdump documentation to ReST and add it to the
user faced manual, as the documents are mainly focused on
sysadmins that would be enabling kdump.
Note: the vmcoreinfo.rst has one very long title on one of its
sub-sections:
PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision|PG_head_mask|PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
I opted to break this one, into two entries with the same content,
in order to make it easier to display after being parsed in html and PDF.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/bug-hunting.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 6 +-
Documentation/kdump/index.rst | 21 +++
Documentation/kdump/{kdump.txt => kdump.rst} | 131 +++++++++++-------
.../kdump/{vmcoreinfo.txt => vmcoreinfo.rst} | 59 ++++----
.../powerpc/firmware-assisted-dump.txt | 2 +-
.../translations/zh_CN/oops-tracing.txt | 2 +-
Documentation/watchdog/hpwdt.txt | 2 +-
arch/arm/Kconfig | 2 +-
arch/arm64/Kconfig | 2 +-
arch/sh/Kconfig | 2 +-
arch/x86/Kconfig | 4 +-
12 files changed, 137 insertions(+), 98 deletions(-)
create mode 100644 Documentation/kdump/index.rst
rename Documentation/kdump/{kdump.txt => kdump.rst} (91%)
rename Documentation/kdump/{vmcoreinfo.txt => vmcoreinfo.rst} (95%)
diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
index f278b289e260..b761aa2a51d2 100644
--- a/Documentation/admin-guide/bug-hunting.rst
+++ b/Documentation/admin-guide/bug-hunting.rst
@@ -90,7 +90,7 @@ the disk is not available then you have three options:
run a null modem to a second machine and capture the output there
using your favourite communication program. Minicom works well.
-(3) Use Kdump (see Documentation/kdump/kdump.txt),
+(3) Use Kdump (see Documentation/kdump/kdump.rst),
extract the kernel ring buffer from old memory with using dmesg
gdbmacro in Documentation/kdump/gdbmacros.txt.
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index affed5d447de..c31373f39240 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -708,14 +708,14 @@
[KNL, x86_64] select a region under 4G first, and
fall back to reserve region above 4G when '@offset'
hasn't been specified.
- See Documentation/kdump/kdump.txt for further details.
+ See Documentation/kdump/kdump.rst for further details.
crashkernel=range1:size1[,range2:size2,...][@offset]
[KNL] Same as above, but depends on the memory
in the running system. The syntax of range is
start-[end] where start and end are both
a memory unit (amount[KMG]). See also
- Documentation/kdump/kdump.txt for an example.
+ Documentation/kdump/kdump.rst for an example.
crashkernel=size[KMG],high
[KNL, x86_64] range could be above 4G. Allow kernel
@@ -1207,7 +1207,7 @@
Specifies physical address of start of kernel core
image elf header and optionally the size. Generally
kexec loader will pass this option to capture kernel.
- See Documentation/kdump/kdump.txt for details.
+ See Documentation/kdump/kdump.rst for details.
enable_mtrr_cleanup [X86]
The kernel tries to adjust MTRR layout from continuous
diff --git a/Documentation/kdump/index.rst b/Documentation/kdump/index.rst
new file mode 100644
index 000000000000..2b17fcf6867a
--- /dev/null
+++ b/Documentation/kdump/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+================================================================
+Documentation for Kdump - The kexec-based Crash Dumping Solution
+================================================================
+
+This document includes overview, setup and installation, and analysis
+information.
+
+.. toctree::
+ :maxdepth: 1
+
+ kdump
+ vmcoreinfo
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.rst
similarity index 91%
rename from Documentation/kdump/kdump.txt
rename to Documentation/kdump/kdump.rst
index 3162eeb8c262..ac7e131d2935 100644
--- a/Documentation/kdump/kdump.txt
+++ b/Documentation/kdump/kdump.rst
@@ -71,9 +71,8 @@ This is a symlink to the latest version.
The latest kexec-tools git tree is available at:
-git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
-and
-http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
There is also a gitweb interface available at
http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
@@ -81,25 +80,25 @@ http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
More information about kexec-tools can be found at
http://horms.net/projects/kexec/
-3) Unpack the tarball with the tar command, as follows:
+3) Unpack the tarball with the tar command, as follows::
- tar xvpzf kexec-tools.tar.gz
+ tar xvpzf kexec-tools.tar.gz
-4) Change to the kexec-tools directory, as follows:
+4) Change to the kexec-tools directory, as follows::
- cd kexec-tools-VERSION
+ cd kexec-tools-VERSION
-5) Configure the package, as follows:
+5) Configure the package, as follows::
- ./configure
+ ./configure
-6) Compile the package, as follows:
+6) Compile the package, as follows::
- make
+ make
-7) Install the package, as follows:
+7) Install the package, as follows::
- make install
+ make install
Build the system and dump-capture kernels
@@ -126,25 +125,25 @@ dump-capture kernels for enabling kdump support.
System kernel config options
----------------------------
-1) Enable "kexec system call" in "Processor type and features."
+1) Enable "kexec system call" in "Processor type and features."::
- CONFIG_KEXEC=y
+ CONFIG_KEXEC=y
2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
- filesystems." This is usually enabled by default.
+ filesystems." This is usually enabled by default::
- CONFIG_SYSFS=y
+ CONFIG_SYSFS=y
Note that "sysfs file system support" might not appear in the "Pseudo
filesystems" menu if "Configure standard kernel features (for small
systems)" is not enabled in "General Setup." In this case, check the
- .config file itself to ensure that sysfs is turned on, as follows:
+ .config file itself to ensure that sysfs is turned on, as follows::
- grep 'CONFIG_SYSFS' .config
+ grep 'CONFIG_SYSFS' .config
-3) Enable "Compile the kernel with debug info" in "Kernel hacking."
+3) Enable "Compile the kernel with debug info" in "Kernel hacking."::
- CONFIG_DEBUG_INFO=Y
+ CONFIG_DEBUG_INFO=Y
This causes the kernel to be built with debug symbols. The dump
analysis tools require a vmlinux with debug symbols in order to read
@@ -154,29 +153,32 @@ Dump-capture kernel config options (Arch Independent)
-----------------------------------------------------
1) Enable "kernel crash dumps" support under "Processor type and
- features":
+ features"::
- CONFIG_CRASH_DUMP=y
+ CONFIG_CRASH_DUMP=y
-2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems".
+2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems"::
+
+ CONFIG_PROC_VMCORE=y
- CONFIG_PROC_VMCORE=y
(CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.)
Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
--------------------------------------------------------------------
1) On i386, enable high memory support under "Processor type and
- features":
+ features"::
- CONFIG_HIGHMEM64G=y
- or
- CONFIG_HIGHMEM4G
+ CONFIG_HIGHMEM64G=y
+
+ or::
+
+ CONFIG_HIGHMEM4G
2) On i386 and x86_64, disable symmetric multi-processing support
- under "Processor type and features":
+ under "Processor type and features"::
- CONFIG_SMP=n
+ CONFIG_SMP=n
(If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line
when loading the dump-capture kernel, see section "Load the Dump-capture
@@ -184,9 +186,9 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
3) If one wants to build and use a relocatable kernel,
Enable "Build a relocatable kernel" support under "Processor type and
- features"
+ features"::
- CONFIG_RELOCATABLE=y
+ CONFIG_RELOCATABLE=y
4) Use a suitable value for "Physical address where the kernel is
loaded" (under "Processor type and features"). This only appears when
@@ -211,13 +213,13 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
Dump-capture kernel config options (Arch Dependent, ppc64)
----------------------------------------------------------
-1) Enable "Build a kdump crash kernel" support under "Kernel" options:
+1) Enable "Build a kdump crash kernel" support under "Kernel" options::
- CONFIG_CRASH_DUMP=y
+ CONFIG_CRASH_DUMP=y
-2) Enable "Build a relocatable kernel" support
+2) Enable "Build a relocatable kernel" support::
- CONFIG_RELOCATABLE=y
+ CONFIG_RELOCATABLE=y
Make and install the kernel and its modules.
@@ -231,11 +233,13 @@ Dump-capture kernel config options (Arch Dependent, ia64)
The crashkernel region can be automatically placed by the system
kernel at run time. This is done by specifying the base address as 0,
- or omitting it all together.
+ or omitting it all together::
- crashkernel=256M@0
- or
- crashkernel=256M
+ crashkernel=256M@0
+
+ or::
+
+ crashkernel=256M
If the start address is specified, note that the start address of the
kernel will be aligned to 64Mb, so if the start address is not then
@@ -245,9 +249,9 @@ Dump-capture kernel config options (Arch Dependent, arm)
----------------------------------------------------------
- To use a relocatable kernel,
- Enable "AUTO_ZRELADDR" support under "Boot" options:
+ Enable "AUTO_ZRELADDR" support under "Boot" options::
- AUTO_ZRELADDR=y
+ AUTO_ZRELADDR=y
Dump-capture kernel config options (Arch Dependent, arm64)
----------------------------------------------------------
@@ -265,12 +269,12 @@ on the value of System RAM -- that's mostly for distributors that pre-setup
the kernel command line to avoid a unbootable system after some memory has
been removed from the machine.
-The syntax is:
+The syntax is::
crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset]
range=start-[end]
-For example:
+For example::
crashkernel=512M-2G:64M,2G-:128M
@@ -326,35 +330,46 @@ can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz
of dump-capture kernel. Following is the summary.
For i386 and x86_64:
+
- Use vmlinux if kernel is not relocatable.
- Use bzImage/vmlinuz if kernel is relocatable.
+
For ppc64:
+
- Use vmlinux
+
For ia64:
+
- Use vmlinux or vmlinuz.gz
+
For s390x:
+
- Use image or bzImage
+
For arm:
+
- Use zImage
+
For arm64:
+
- Use vmlinux or Image
If you are using an uncompressed vmlinux image then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-vmlinux-image> \
--initrd=<initrd-for-dump-capture-kernel> --args-linux \
--append="root=<root-dev> <arch-specific-options>"
If you are using a compressed bzImage/vmlinuz, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-bzImage> \
--initrd=<initrd-for-dump-capture-kernel> \
--append="root=<root-dev> <arch-specific-options>"
If you are using a compressed zImage, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec --type zImage -p <dump-capture-kernel-bzImage> \
--initrd=<initrd-for-dump-capture-kernel> \
@@ -362,7 +377,7 @@ to load dump-capture kernel.
--append="root=<root-dev> <arch-specific-options>"
If you are using an uncompressed Image, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-Image> \
--initrd=<initrd-for-dump-capture-kernel> \
@@ -376,18 +391,23 @@ Following are the arch specific command line options to be used while
loading dump-capture kernel.
For i386, x86_64 and ia64:
+
"1 irqpoll maxcpus=1 reset_devices"
For ppc64:
+
"1 maxcpus=1 noirqdistrib reset_devices"
For s390x:
+
"1 maxcpus=1 cgroup_disable=memory"
For arm:
+
"1 maxcpus=1 reset_devices"
For arm64:
+
"1 maxcpus=1 reset_devices"
Notes on loading the dump-capture kernel:
@@ -464,7 +484,7 @@ Write Out the Dump File
=======================
After the dump-capture kernel is booted, write out the dump file with
-the following command:
+the following command::
cp /proc/vmcore <dump-file>
@@ -476,7 +496,7 @@ Before analyzing the dump image, you should reboot into a stable kernel.
You can do limited analysis using GDB on the dump file copied out of
/proc/vmcore. Use the debug vmlinux built with -g and run the following
-command:
+command::
gdb vmlinux <dump-file>
@@ -504,6 +524,11 @@ to achieve the same behaviour.
Contact
=======
-Vivek Goyal (vgoyal@redhat.com)
-Maneesh Soni (maneesh@in.ibm.com)
+- Vivek Goyal (vgoyal@redhat.com)
+- Maneesh Soni (maneesh@in.ibm.com)
+GDB macros
+==========
+
+.. include:: gdbmacros.txt
+ :literal:
diff --git a/Documentation/kdump/vmcoreinfo.txt b/Documentation/kdump/vmcoreinfo.rst
similarity index 95%
rename from Documentation/kdump/vmcoreinfo.txt
rename to Documentation/kdump/vmcoreinfo.rst
index bb94a4bd597a..007a6b86e0ee 100644
--- a/Documentation/kdump/vmcoreinfo.txt
+++ b/Documentation/kdump/vmcoreinfo.rst
@@ -1,8 +1,7 @@
-================================================================
- VMCOREINFO
-================================================================
+==========
+VMCOREINFO
+==========
-===========
What is it?
===========
@@ -12,7 +11,6 @@ values, field offsets, etc. These data are packed into an ELF note
section and used by user-space tools like crash and makedumpfile to
analyze a kernel's memory layout.
-================
Common variables
================
@@ -49,7 +47,7 @@ in a system, one bit position per node number. Used to keep track of
which nodes are in the system and online.
swapper_pg_dir
--------------
+--------------
The global page directory pointer of the kernel. Used to translate
virtual to physical addresses.
@@ -132,16 +130,14 @@ nodemask_t
The size of a nodemask_t type. Used to compute the number of online
nodes.
-(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor|
- compound_order|compound_head)
--------------------------------------------------------------------
+(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor|compound_order|compound_head)
+-------------------------------------------------------------------------------------------------
User-space tools compute their values based on the offset of these
variables. The variables are used when excluding unnecessary pages.
-(pglist_data, node_zones|nr_zones|node_mem_map|node_start_pfn|node_
- spanned_pages|node_id)
--------------------------------------------------------------------
+(pglist_data, node_zones|nr_zones|node_mem_map|node_start_pfn|node_spanned_pages|node_id)
+-----------------------------------------------------------------------------------------
On NUMA machines, each NUMA node has a pg_data_t to describe its memory
layout. On UMA machines there is a single pglist_data which describes the
@@ -245,21 +241,25 @@ NR_FREE_PAGES
On linux-2.6.21 or later, the number of free pages is in
vm_stat[NR_FREE_PAGES]. Used to get the number of free pages.
-PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision
-|PG_head_mask|PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)
-|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
------------------------------------------------------------------
+PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision|PG_head_mask
+------------------------------------------------------------------------------
Page attributes. These flags are used to filter various unnecessary for
dumping pages.
+PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
+-----------------------------------------------------------------------------
+
+More page attributes. These flags are used to filter various unnecessary for
+dumping pages.
+
+
HUGETLB_PAGE_DTOR
-----------------
The HUGETLB_PAGE_DTOR flag denotes hugetlbfs pages. Makedumpfile
excludes these pages.
-======
x86_64
======
@@ -318,12 +318,12 @@ address.
Currently, sme_mask stores the value of the C-bit position. If needed,
additional SME-relevant info can be placed in that variable.
-For example:
-[ misc ][ enc bit ][ other misc SME info ]
-0000_0000_0000_0000_1000_0000_0000_0000_0000_0000_..._0000
-63 59 55 51 47 43 39 35 31 27 ... 3
+For example::
+
+ [ misc ][ enc bit ][ other misc SME info ]
+ 0000_0000_0000_0000_1000_0000_0000_0000_0000_0000_..._0000
+ 63 59 55 51 47 43 39 35 31 27 ... 3
-======
x86_32
======
@@ -335,7 +335,6 @@ of a higher page table lookup overhead, and also consumes more page
table space per process. Used to check whether PAE was enabled in the
crash kernel when converting virtual addresses to physical addresses.
-====
ia64
====
@@ -366,7 +365,6 @@ PGTABLE_3|PGTABLE_4
User-space tools need to know whether the crash kernel was in 3-level or
4-level paging mode. Used to distinguish the page table.
-=====
ARM64
=====
@@ -395,9 +393,8 @@ KERNELOFFSET
The kernel randomization offset. Used to compute the page offset. If
KASLR is disabled, this value is zero.
-====
arm
-====
+===
ARM_LPAE
--------
@@ -405,12 +402,11 @@ ARM_LPAE
It indicates whether the crash kernel supports large physical address
extensions. Used to translate virtual to physical addresses.
-====
s390
====
lowcore_ptr
-----------
+-----------
An array with a pointer to the lowcore of every CPU. Used to print the
psw and all registers information.
@@ -425,7 +421,6 @@ Used to get the vmalloc_start address from the high_memory symbol.
The maximum number of CPUs.
-=======
powerpc
=======
@@ -460,9 +455,8 @@ Page size definitions, i.e. 4k, 64k, or 16M.
Used to make vtop translations.
-vmemmap_backing|(vmemmap_backing, list)|(vmemmap_backing, phys)|
-(vmemmap_backing, virt_addr)
-----------------------------------------------------------------
+vmemmap_backing|(vmemmap_backing, list)|(vmemmap_backing, phys)|(vmemmap_backing, virt_addr)
+--------------------------------------------------------------------------------------------
The vmemmap virtual address space management does not have a traditional
page table to track which virtual struct pages are backed by a physical
@@ -480,7 +474,6 @@ member.
Used in vtop translations.
-==
sh
==
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt
index 18c5feef2577..0c41d6d463f3 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.txt
@@ -59,7 +59,7 @@ as follows:
the default calculated size. Use this option if default
boot memory size is not sufficient for second kernel to
boot successfully. For syntax of crashkernel= parameter,
- refer to Documentation/kdump/kdump.txt. If any offset is
+ refer to Documentation/kdump/kdump.rst. If any offset is
provided in crashkernel= parameter, it will be ignored
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt
index 93fa061cf9e4..368ddd05b304 100644
--- a/Documentation/translations/zh_CN/oops-tracing.txt
+++ b/Documentation/translations/zh_CN/oops-tracing.txt
@@ -53,7 +53,7 @@ cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“
（2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null
modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。
-（3）使用Kdump（请参看Documentation/kdump/kdump.txt），
+（3）使用Kdump（请参看Documentation/kdump/kdump.rst），
使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
环形缓冲区。
diff --git a/Documentation/watchdog/hpwdt.txt b/Documentation/watchdog/hpwdt.txt
index 55df692c5595..aaa9e4b4bdcd 100644
--- a/Documentation/watchdog/hpwdt.txt
+++ b/Documentation/watchdog/hpwdt.txt
@@ -51,7 +51,7 @@ Last reviewed: 08/20/2018
and loop forever. This is generally not what a watchdog user wants.
For those wishing to learn more please see:
- Documentation/kdump/kdump.txt
+ Documentation/kdump/kdump.rst
Documentation/admin-guide/kernel-parameters.txt (panic=)
Your Linux Distribution specific documentation.
diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index 204cbc6bf234..af58d31ee4e1 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -2006,7 +2006,7 @@ config CRASH_DUMP
kdump/kexec. The crash dump kernel must be compiled to a
memory address not used by the main kernel
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config AUTO_ZRELADDR
bool "Auto calculation of the decompressed kernel image address"
diff --git a/arch/arm64/Kconfig b/arch/arm64/Kconfig
index c2afcea9b19b..ac33b4bd1624 100644
--- a/arch/arm64/Kconfig
+++ b/arch/arm64/Kconfig
@@ -996,7 +996,7 @@ config CRASH_DUMP
reserved region and then later executed after a crash by
kdump/kexec.
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config XEN_DOM0
def_bool y
diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
index b77f512bb176..ce1a28654507 100644
--- a/arch/sh/Kconfig
+++ b/arch/sh/Kconfig
@@ -623,7 +623,7 @@ config CRASH_DUMP
to a memory address not used by the main kernel using
PHYSICAL_START.
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config KEXEC_JUMP
bool "kexec jump (EXPERIMENTAL)"
diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
index 4b37664e7471..a109141a8d3b 100644
--- a/arch/x86/Kconfig
+++ b/arch/x86/Kconfig
@@ -2038,7 +2038,7 @@ config CRASH_DUMP
to a memory address not used by the main kernel or BIOS using
PHYSICAL_START, or it must be built as a relocatable image
(CONFIG_RELOCATABLE=y).
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config KEXEC_JUMP
bool "kexec jump"
@@ -2075,7 +2075,7 @@ config PHYSICAL_START
the reserved region. In other words, it can be set based on
the "X" value as specified in the "crashkernel=YM@XM"
command line boot parameter passed to the panic-ed
- kernel. Please take a look at Documentation/kdump/kdump.txt
+ kernel. Please take a look at Documentation/kdump/kdump.rst
for more details about crash dumps.
Usage of bzImage for capturing the crash dump is recommended as
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 14/28] docs: locking: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (7 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 13/28] docs: kdump: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-14 20:36 ` Jonathan Corbet
2019-06-12 17:52 ` [PATCH v4 15/28] docs: mic: " Mauro Carvalho Chehab
` (15 subsequent siblings)
24 siblings, 1 reply; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Zijlstra, Ingo Molnar, Will Deacon,
Federico Vaga, Maarten Lankhorst, Maxime Ripard, Sean Paul,
David Airlie, Daniel Vetter, dri-devel
Convert the locking documents to ReST and add them to the
kernel development book where it belongs.
Most of the stuff here is just to make Sphinx to properly
parse the text file, as they're already in good shape,
not requiring massive changes in order to be parsed.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/locking/index.rst | 24 +++
...{lockdep-design.txt => lockdep-design.rst} | 51 +++--
Documentation/locking/lockstat.rst | 204 ++++++++++++++++++
Documentation/locking/lockstat.txt | 183 ----------------
.../{locktorture.txt => locktorture.rst} | 105 +++++----
.../{mutex-design.txt => mutex-design.rst} | 26 ++-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++++++------
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +--
.../locking/{spinlocks.txt => spinlocks.rst} | 32 ++-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +++----
Documentation/pi-futex.txt | 2 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/rwsem.h | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
lib/Kconfig.debug | 4 +-
20 files changed, 511 insertions(+), 387 deletions(-)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
create mode 100644 Documentation/locking/lockstat.rst
delete mode 100644 Documentation/locking/lockstat.txt
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index 519673df0e82..71a843464ec2 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -1364,7 +1364,7 @@ Futex API reference
Further reading
===============
-- ``Documentation/locking/spinlocks.txt``: Linus Torvalds' spinlocking
+- ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking
tutorial in the kernel sources.
- Unix Systems for Modern Architectures: Symmetric Multiprocessing and
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
new file mode 100644
index 000000000000..ef5da7fe9aac
--- /dev/null
+++ b/Documentation/locking/index.rst
@@ -0,0 +1,24 @@
+:orphan:
+
+=======
+locking
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ lockdep-design
+ lockstat
+ locktorture
+ mutex-design
+ rt-mutex-design
+ rt-mutex
+ spinlocks
+ ww-mutex-design
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.rst
similarity index 93%
rename from Documentation/locking/lockdep-design.txt
rename to Documentation/locking/lockdep-design.rst
index f189d130e543..23fcbc4d3fc0 100644
--- a/Documentation/locking/lockdep-design.txt
+++ b/Documentation/locking/lockdep-design.rst
@@ -2,6 +2,7 @@ Runtime locking correctness validator
=====================================
started by Ingo Molnar <mingo@redhat.com>
+
additions by Arjan van de Ven <arjan@linux.intel.com>
Lock-class
@@ -56,7 +57,7 @@ where the last 1 category is:
When locking rules are violated, these usage bits are presented in the
locking error messages, inside curlies, with a total of 2 * n STATEs bits.
-A contrived example:
+A contrived example::
modprobe/2287 is trying to acquire lock:
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
@@ -70,12 +71,14 @@ of the lock and readlock (if exists), for each of the n STATEs listed
above respectively, and the character displayed at each bit position
indicates:
+ === ===================================================
'.' acquired while irqs disabled and not in irq context
'-' acquired in irq context
'+' acquired with irqs enabled
'?' acquired in irq context with irqs enabled.
+ === ===================================================
-The bits are illustrated with an example:
+The bits are illustrated with an example::
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
||||
@@ -90,13 +93,13 @@ context and whether that STATE is enabled yields four possible cases as
shown in the table below. The bit character is able to indicate which
exact case is for the lock as of the reporting time.
- -------------------------------------------
+ +--------------+-------------+--------------+
| | irq enabled | irq disabled |
- |-------------------------------------------|
+ +--------------+-------------+--------------+
| ever in irq | ? | - |
- |-------------------------------------------|
+ +--------------+-------------+--------------+
| never in irq | + | . |
- -------------------------------------------
+ +--------------+-------------+--------------+
The character '-' suggests irq is disabled because if otherwise the
charactor '?' would have been shown instead. Similar deduction can be
@@ -113,7 +116,7 @@ is irq-unsafe means it was ever acquired with irq enabled.
A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The
following states must be exclusive: only one of them is allowed to be set
-for any lock-class based on its usage:
+for any lock-class based on its usage::
<hardirq-safe> or <hardirq-unsafe>
<softirq-safe> or <softirq-unsafe>
@@ -134,7 +137,7 @@ Multi-lock dependency rules:
The same lock-class must not be acquired twice, because this could lead
to lock recursion deadlocks.
-Furthermore, two locks can not be taken in inverse order:
+Furthermore, two locks can not be taken in inverse order::
<L1> -> <L2>
<L2> -> <L1>
@@ -148,7 +151,7 @@ operations; the validator will still find whether these locks can be
acquired in a circular fashion.
Furthermore, the following usage based lock dependencies are not allowed
-between any two lock-classes:
+between any two lock-classes::
<hardirq-safe> -> <hardirq-unsafe>
<softirq-safe> -> <softirq-unsafe>
@@ -204,16 +207,16 @@ the ordering is not static.
In order to teach the validator about this correct usage model, new
versions of the various locking primitives were added that allow you to
specify a "nesting level". An example call, for the block device mutex,
-looks like this:
+looks like this::
-enum bdev_bd_mutex_lock_class
-{
+ enum bdev_bd_mutex_lock_class
+ {
BD_MUTEX_NORMAL,
BD_MUTEX_WHOLE,
BD_MUTEX_PARTITION
-};
+ };
- mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
In this case the locking is done on a bdev object that is known to be a
partition.
@@ -234,7 +237,7 @@ must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock).
As the name suggests, lockdep_assert_held* family of macros assert that a
particular lock is held at a certain time (and generate a WARN() otherwise).
This annotation is largely used all over the kernel, e.g. kernel/sched/
-core.c
+core.c::
void update_rq_clock(struct rq *rq)
{
@@ -253,7 +256,7 @@ out to be especially helpful to debug code with callbacks, where an upper
layer assumes a lock remains taken, but a lower layer thinks it can maybe drop
and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock()
returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check
-that nobody tampered with the lock, e.g. kernel/sched/sched.h
+that nobody tampered with the lock, e.g. kernel/sched/sched.h::
static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf)
{
@@ -280,7 +283,7 @@ correctness) in the sense that for every simple, standalone single-task
locking sequence that occurred at least once during the lifetime of the
kernel, the validator proves it with a 100% certainty that no
combination and timing of these locking sequences can cause any class of
-lock related deadlock. [*]
+lock related deadlock. [1]_
I.e. complex multi-CPU and multi-task locking scenarios do not have to
occur in practice to prove a deadlock: only the simple 'component'
@@ -299,7 +302,9 @@ possible combination of locking interaction between CPUs, combined with
every possible hardirq and softirq nesting scenario (which is impossible
to do in practice).
-[*] assuming that the validator itself is 100% correct, and no other
+.. [1]
+
+ assuming that the validator itself is 100% correct, and no other
part of the system corrupts the state of the validator in any way.
We also assume that all NMI/SMM paths [which could interrupt
even hardirq-disabled codepaths] are correct and do not interfere
@@ -310,7 +315,7 @@ to do in practice).
Performance:
------------
-The above rules require _massive_ amounts of runtime checking. If we did
+The above rules require **massive** amounts of runtime checking. If we did
that for every lock taken and for every irqs-enable event, it would
render the system practically unusably slow. The complexity of checking
is O(N^2), so even with just a few hundred lock-classes we'd have to do
@@ -369,17 +374,17 @@ be harder to do than to say.
Of course, if you do run out of lock classes, the next thing to do is
to find the offending lock classes. First, the following command gives
-you the number of lock classes currently in use along with the maximum:
+you the number of lock classes currently in use along with the maximum::
grep "lock-classes" /proc/lockdep_stats
-This command produces the following output on a modest system:
+This command produces the following output on a modest system::
- lock-classes: 748 [max: 8191]
+ lock-classes: 748 [max: 8191]
If the number allocated (748 above) increases continually over time,
then there is likely a leak. The following command can be used to
-identify the leaking lock classes:
+identify the leaking lock classes::
grep "BD" /proc/lockdep
diff --git a/Documentation/locking/lockstat.rst b/Documentation/locking/lockstat.rst
new file mode 100644
index 000000000000..536eab8dbd99
--- /dev/null
+++ b/Documentation/locking/lockstat.rst
@@ -0,0 +1,204 @@
+===============
+Lock Statistics
+===============
+
+What
+====
+
+As the name suggests, it provides statistics on locks.
+
+
+Why
+===
+
+Because things like lock contention can severely impact performance.
+
+How
+===
+
+Lockdep already has hooks in the lock functions and maps lock instances to
+lock classes. We build on that (see Documentation/locking/lockdep-design.rst).
+The graph below shows the relation between the lock functions and the various
+hooks therein::
+
+ __acquire
+ |
+ lock _____
+ | \
+ | __contended
+ | |
+ | <wait>
+ | _______/
+ |/
+ |
+ __acquired
+ |
+ .
+ <hold>
+ .
+ |
+ __release
+ |
+ unlock
+
+ lock, unlock - the regular lock functions
+ __* - the hooks
+ <> - states
+
+With these hooks we provide the following statistics:
+
+ con-bounces
+ - number of lock contention that involved x-cpu data
+ contentions
+ - number of lock acquisitions that had to wait
+ wait time
+ min
+ - shortest (non-0) time we ever had to wait for a lock
+ max
+ - longest time we ever had to wait for a lock
+ total
+ - total time we spend waiting on this lock
+ avg
+ - average time spent waiting on this lock
+ acq-bounces
+ - number of lock acquisitions that involved x-cpu data
+ acquisitions
+ - number of times we took the lock
+ hold time
+ min
+ - shortest (non-0) time we ever held the lock
+ max
+ - longest time we ever held the lock
+ total
+ - total time this lock was held
+ avg
+ - average time this lock was held
+
+These numbers are gathered per lock class, per read/write state (when
+applicable).
+
+It also tracks 4 contention points per class. A contention point is a call site
+that had to wait on lock acquisition.
+
+Configuration
+-------------
+
+Lock statistics are enabled via CONFIG_LOCK_STAT.
+
+Usage
+-----
+
+Enable collection of statistics::
+
+ # echo 1 >/proc/sys/kernel/lock_stat
+
+Disable collection of statistics::
+
+ # echo 0 >/proc/sys/kernel/lock_stat
+
+Look at the current lock statistics::
+
+ ( line numbers not part of actual output, done for clarity in the explanation
+ below )
+
+ # less /proc/lock_stat
+
+ 01 lock_stat version 0.4
+ 02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
+ 04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 05
+ 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
+ 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
+ 08 ---------------
+ 09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
+ 10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
+ 13 ---------------
+ 14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
+ 15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
+ 16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 18
+ 19.............................................................................................................................................................................................................................
+ 20
+ 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
+ 22 ---------------
+ 23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+ 27 ---------------
+ 28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+
+
+This excerpt shows the first two lock class statistics. Line 01 shows the
+output version - each time the format changes this will be updated. Line 02-04
+show the header with column descriptions. Lines 05-18 and 20-31 show the actual
+statistics. These statistics come in two parts; the actual stats separated by a
+short separator (line 08, 13) from the contention points.
+
+Lines 09-12 show the first 4 recorded contention points (the code
+which tries to get the lock) and lines 14-17 show the first 4 recorded
+contended points (the lock holder). It is possible that the max
+con-bounces point is missing in the statistics.
+
+The first lock (05-18) is a read/write lock, and shows two lines above the
+short separator. The contention points don't match the column descriptors,
+they have two: contentions and [<IP>] symbol. The second set of contention
+points are the points we're contending with.
+
+The integer part of the time values is in us.
+
+Dealing with nested locks, subclasses may appear::
+
+ 32...........................................................................................................................................................................................................................
+ 33
+ 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
+ 35 ---------
+ 36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
+ 39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
+ 40 ---------
+ 41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 45
+ 46...........................................................................................................................................................................................................................
+ 47
+ 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
+ 49 -----------
+ 50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 51 -----------
+ 52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+
+Line 48 shows statistics for the second subclass (/1) of &rq->lock class
+(subclass starts from 0), since in this case, as line 50 suggests,
+double_rq_lock actually acquires a nested lock of two spinlocks.
+
+View the top contending locks::
+
+ # grep : /proc/lock_stat | head
+ clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
+ tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
+ &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
+ &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
+ &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
+ tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
+ tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
+ rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
+ &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
+ rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
+
+Clear the statistics::
+
+ # echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt
deleted file mode 100644
index fdbeb0c45ef3..000000000000
--- a/Documentation/locking/lockstat.txt
+++ /dev/null
@@ -1,183 +0,0 @@
-
-LOCK STATISTICS
-
-- WHAT
-
-As the name suggests, it provides statistics on locks.
-
-- WHY
-
-Because things like lock contention can severely impact performance.
-
-- HOW
-
-Lockdep already has hooks in the lock functions and maps lock instances to
-lock classes. We build on that (see Documentation/locking/lockdep-design.txt).
-The graph below shows the relation between the lock functions and the various
-hooks therein.
-
- __acquire
- |
- lock _____
- | \
- | __contended
- | |
- | <wait>
- | _______/
- |/
- |
- __acquired
- |
- .
- <hold>
- .
- |
- __release
- |
- unlock
-
-lock, unlock - the regular lock functions
-__* - the hooks
-<> - states
-
-With these hooks we provide the following statistics:
-
- con-bounces - number of lock contention that involved x-cpu data
- contentions - number of lock acquisitions that had to wait
- wait time min - shortest (non-0) time we ever had to wait for a lock
- max - longest time we ever had to wait for a lock
- total - total time we spend waiting on this lock
- avg - average time spent waiting on this lock
- acq-bounces - number of lock acquisitions that involved x-cpu data
- acquisitions - number of times we took the lock
- hold time min - shortest (non-0) time we ever held the lock
- max - longest time we ever held the lock
- total - total time this lock was held
- avg - average time this lock was held
-
-These numbers are gathered per lock class, per read/write state (when
-applicable).
-
-It also tracks 4 contention points per class. A contention point is a call site
-that had to wait on lock acquisition.
-
- - CONFIGURATION
-
-Lock statistics are enabled via CONFIG_LOCK_STAT.
-
- - USAGE
-
-Enable collection of statistics:
-
-# echo 1 >/proc/sys/kernel/lock_stat
-
-Disable collection of statistics:
-
-# echo 0 >/proc/sys/kernel/lock_stat
-
-Look at the current lock statistics:
-
-( line numbers not part of actual output, done for clarity in the explanation
- below )
-
-# less /proc/lock_stat
-
-01 lock_stat version 0.4
-02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
-04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-05
-06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
-07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
-08 ---------------
-09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
-10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
-13 ---------------
-14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
-15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
-16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-18
-19.............................................................................................................................................................................................................................
-20
-21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
-22 ---------------
-23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-27 ---------------
-28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-
-
-This excerpt shows the first two lock class statistics. Line 01 shows the
-output version - each time the format changes this will be updated. Line 02-04
-show the header with column descriptions. Lines 05-18 and 20-31 show the actual
-statistics. These statistics come in two parts; the actual stats separated by a
-short separator (line 08, 13) from the contention points.
-
-Lines 09-12 show the first 4 recorded contention points (the code
-which tries to get the lock) and lines 14-17 show the first 4 recorded
-contended points (the lock holder). It is possible that the max
-con-bounces point is missing in the statistics.
-
-The first lock (05-18) is a read/write lock, and shows two lines above the
-short separator. The contention points don't match the column descriptors,
-they have two: contentions and [<IP>] symbol. The second set of contention
-points are the points we're contending with.
-
-The integer part of the time values is in us.
-
-Dealing with nested locks, subclasses may appear:
-
-32...........................................................................................................................................................................................................................
-33
-34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
-35 ---------
-36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
-39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
-40 ---------
-41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
-45
-46...........................................................................................................................................................................................................................
-47
-48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
-49 -----------
-50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-51 -----------
-52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
-54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-
-Line 48 shows statistics for the second subclass (/1) of &rq->lock class
-(subclass starts from 0), since in this case, as line 50 suggests,
-double_rq_lock actually acquires a nested lock of two spinlocks.
-
-View the top contending locks:
-
-# grep : /proc/lock_stat | head
- clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
- tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
- &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
- &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
- &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
- tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
- tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
- rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
- &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
- rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
-
-Clear the statistics:
-
-# echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.rst
similarity index 57%
rename from Documentation/locking/locktorture.txt
rename to Documentation/locking/locktorture.rst
index 6a8df4cd19bf..e79eeeca3ac6 100644
--- a/Documentation/locking/locktorture.txt
+++ b/Documentation/locking/locktorture.rst
@@ -1,6 +1,9 @@
+==================================
Kernel Lock Torture Test Operation
+==================================
CONFIG_LOCK_TORTURE_TEST
+========================
The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
that runs torture tests on core kernel locking primitives. The kernel
@@ -18,61 +21,77 @@ can be simulated by either enlarging this critical region hold time and/or
creating more kthreads.
-MODULE PARAMETERS
+Module Parameters
+=================
This module has the following parameters:
- ** Locktorture-specific **
+Locktorture-specific
+--------------------
-nwriters_stress Number of kernel threads that will stress exclusive lock
+nwriters_stress
+ Number of kernel threads that will stress exclusive lock
ownership (writers). The default value is twice the number
of online CPUs.
-nreaders_stress Number of kernel threads that will stress shared lock
+nreaders_stress
+ Number of kernel threads that will stress shared lock
ownership (readers). The default is the same amount of writer
locks. If the user did not specify nwriters_stress, then
both readers and writers be the amount of online CPUs.
-torture_type Type of lock to torture. By default, only spinlocks will
+torture_type
+ Type of lock to torture. By default, only spinlocks will
be tortured. This module can torture the following locks,
with string values as follows:
- o "lock_busted": Simulates a buggy lock implementation.
+ - "lock_busted":
+ Simulates a buggy lock implementation.
- o "spin_lock": spin_lock() and spin_unlock() pairs.
+ - "spin_lock":
+ spin_lock() and spin_unlock() pairs.
- o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq()
- pairs.
+ - "spin_lock_irq":
+ spin_lock_irq() and spin_unlock_irq() pairs.
- o "rw_lock": read/write lock() and unlock() rwlock pairs.
+ - "rw_lock":
+ read/write lock() and unlock() rwlock pairs.
- o "rw_lock_irq": read/write lock_irq() and unlock_irq()
- rwlock pairs.
+ - "rw_lock_irq":
+ read/write lock_irq() and unlock_irq()
+ rwlock pairs.
- o "mutex_lock": mutex_lock() and mutex_unlock() pairs.
+ - "mutex_lock":
+ mutex_lock() and mutex_unlock() pairs.
- o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock()
- pairs. Kernel must have CONFIG_RT_MUTEX=y.
+ - "rtmutex_lock":
+ rtmutex_lock() and rtmutex_unlock() pairs.
+ Kernel must have CONFIG_RT_MUTEX=y.
- o "rwsem_lock": read/write down() and up() semaphore pairs.
+ - "rwsem_lock":
+ read/write down() and up() semaphore pairs.
- ** Torture-framework (RCU + locking) **
+Torture-framework (RCU + locking)
+---------------------------------
-shutdown_secs The number of seconds to run the test before terminating
+shutdown_secs
+ The number of seconds to run the test before terminating
the test and powering off the system. The default is
zero, which disables test termination and system shutdown.
This capability is useful for automated testing.
-onoff_interval The number of seconds between each attempt to execute a
+onoff_interval
+ The number of seconds between each attempt to execute a
randomly selected CPU-hotplug operation. Defaults
to zero, which disables CPU hotplugging. In
CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
refuse to do any CPU-hotplug operations regardless of
what value is specified for onoff_interval.
-onoff_holdoff The number of seconds to wait until starting CPU-hotplug
+onoff_holdoff
+ The number of seconds to wait until starting CPU-hotplug
operations. This would normally only be used when
locktorture was built into the kernel and started
automatically at boot time, in which case it is useful
@@ -80,53 +99,59 @@ onoff_holdoff The number of seconds to wait until starting CPU-hotplug
coming and going. This parameter is only useful if
CONFIG_HOTPLUG_CPU is enabled.
-stat_interval Number of seconds between statistics-related printk()s.
+stat_interval
+ Number of seconds between statistics-related printk()s.
By default, locktorture will report stats every 60 seconds.
Setting the interval to zero causes the statistics to
be printed -only- when the module is unloaded, and this
is the default.
-stutter The length of time to run the test before pausing for this
+stutter
+ The length of time to run the test before pausing for this
same period of time. Defaults to "stutter=5", so as
to run and pause for (roughly) five-second intervals.
Specifying "stutter=0" causes the test to run continuously
without pausing, which is the old default behavior.
-shuffle_interval The number of seconds to keep the test threads affinitied
+shuffle_interval
+ The number of seconds to keep the test threads affinitied
to a particular subset of the CPUs, defaults to 3 seconds.
Used in conjunction with test_no_idle_hz.
-verbose Enable verbose debugging printing, via printk(). Enabled
+verbose
+ Enable verbose debugging printing, via printk(). Enabled
by default. This extra information is mostly related to
high-level errors and reports from the main 'torture'
framework.
-STATISTICS
+Statistics
+==========
-Statistics are printed in the following format:
+Statistics are printed in the following format::
-spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
- (A) (B) (C) (D) (E)
+ spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
+ (A) (B) (C) (D) (E)
-(A): Lock type that is being tortured -- torture_type parameter.
+ (A): Lock type that is being tortured -- torture_type parameter.
-(B): Number of writer lock acquisitions. If dealing with a read/write primitive
- a second "Reads" statistics line is printed.
+ (B): Number of writer lock acquisitions. If dealing with a read/write
+ primitive a second "Reads" statistics line is printed.
-(C): Number of times the lock was acquired.
+ (C): Number of times the lock was acquired.
-(D): Min and max number of times threads failed to acquire the lock.
+ (D): Min and max number of times threads failed to acquire the lock.
-(E): true/false values if there were errors acquiring the lock. This should
- -only- be positive if there is a bug in the locking primitive's
- implementation. Otherwise a lock should never fail (i.e., spin_lock()).
- Of course, the same applies for (C), above. A dummy example of this is
- the "lock_busted" type.
+ (E): true/false values if there were errors acquiring the lock. This should
+ -only- be positive if there is a bug in the locking primitive's
+ implementation. Otherwise a lock should never fail (i.e., spin_lock()).
+ Of course, the same applies for (C), above. A dummy example of this is
+ the "lock_busted" type.
-USAGE
+Usage
+=====
-The following script may be used to torture locks:
+The following script may be used to torture locks::
#!/bin/sh
diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.rst
similarity index 94%
rename from Documentation/locking/mutex-design.txt
rename to Documentation/locking/mutex-design.rst
index 818aca19612f..4d8236b81fa5 100644
--- a/Documentation/locking/mutex-design.txt
+++ b/Documentation/locking/mutex-design.rst
@@ -1,6 +1,9 @@
+=======================
Generic Mutex Subsystem
+=======================
started by Ingo Molnar <mingo@redhat.com>
+
updated by Davidlohr Bueso <davidlohr@hp.com>
What are mutexes?
@@ -23,7 +26,7 @@ Implementation
Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h
and implemented in kernel/locking/mutex.c. These locks use an atomic variable
(->owner) to keep track of the lock state during its lifetime. Field owner
-actually contains 'struct task_struct *' to the current lock owner and it is
+actually contains `struct task_struct *` to the current lock owner and it is
therefore NULL if not currently owned. Since task_struct pointers are aligned
at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
if waiter list is non-empty). In its most basic form it also includes a
@@ -101,29 +104,36 @@ features that make lock debugging easier and faster:
Interfaces
----------
-Statically define the mutex:
+Statically define the mutex::
+
DEFINE_MUTEX(name);
-Dynamically initialize the mutex:
+Dynamically initialize the mutex::
+
mutex_init(mutex);
-Acquire the mutex, uninterruptible:
+Acquire the mutex, uninterruptible::
+
void mutex_lock(struct mutex *lock);
void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
int mutex_trylock(struct mutex *lock);
-Acquire the mutex, interruptible:
+Acquire the mutex, interruptible::
+
int mutex_lock_interruptible_nested(struct mutex *lock,
unsigned int subclass);
int mutex_lock_interruptible(struct mutex *lock);
-Acquire the mutex, interruptible, if dec to 0:
+Acquire the mutex, interruptible, if dec to 0::
+
int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
-Unlock the mutex:
+Unlock the mutex::
+
void mutex_unlock(struct mutex *lock);
-Test if the mutex is taken:
+Test if the mutex is taken::
+
int mutex_is_locked(struct mutex *lock);
Disadvantages
diff --git a/Documentation/locking/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.rst
similarity index 91%
rename from Documentation/locking/rt-mutex-design.txt
rename to Documentation/locking/rt-mutex-design.rst
index 3d7b865539cc..59c2a64efb21 100644
--- a/Documentation/locking/rt-mutex-design.txt
+++ b/Documentation/locking/rt-mutex-design.rst
@@ -1,14 +1,15 @@
-#
-# Copyright (c) 2006 Steven Rostedt
-# Licensed under the GNU Free Documentation License, Version 1.2
-#
-
+==============================
RT-mutex implementation design
-------------------------------
+==============================
+
+Copyright (c) 2006 Steven Rostedt
+
+Licensed under the GNU Free Documentation License, Version 1.2
+
This document tries to describe the design of the rtmutex.c implementation.
It doesn't describe the reasons why rtmutex.c exists. For that please see
-Documentation/locking/rt-mutex.txt. Although this document does explain problems
+Documentation/locking/rt-mutex.rst. Although this document does explain problems
that happen without this code, but that is in the concept to understand
what the code actually is doing.
@@ -41,17 +42,17 @@ to release the lock, because for all we know, B is a CPU hog and will
never give C a chance to release the lock. This is called unbounded priority
inversion.
-Here's a little ASCII art to show the problem.
+Here's a little ASCII art to show the problem::
- grab lock L1 (owned by C)
- |
-A ---+
- C preempted by B
- |
-C +----+
+ grab lock L1 (owned by C)
+ |
+ A ---+
+ C preempted by B
+ |
+ C +----+
-B +-------->
- B now keeps A from running.
+ B +-------->
+ B now keeps A from running.
Priority Inheritance (PI)
@@ -75,24 +76,29 @@ Terminology
Here I explain some terminology that is used in this document to help describe
the design that is used to implement PI.
-PI chain - The PI chain is an ordered series of locks and processes that cause
+PI chain
+ - The PI chain is an ordered series of locks and processes that cause
processes to inherit priorities from a previous process that is
blocked on one of its locks. This is described in more detail
later in this document.
-mutex - In this document, to differentiate from locks that implement
+mutex
+ - In this document, to differentiate from locks that implement
PI and spin locks that are used in the PI code, from now on
the PI locks will be called a mutex.
-lock - In this document from now on, I will use the term lock when
+lock
+ - In this document from now on, I will use the term lock when
referring to spin locks that are used to protect parts of the PI
algorithm. These locks disable preemption for UP (when
CONFIG_PREEMPT is enabled) and on SMP prevents multiple CPUs from
entering critical sections simultaneously.
-spin lock - Same as lock above.
+spin lock
+ - Same as lock above.
-waiter - A waiter is a struct that is stored on the stack of a blocked
+waiter
+ - A waiter is a struct that is stored on the stack of a blocked
process. Since the scope of the waiter is within the code for
a process being blocked on the mutex, it is fine to allocate
the waiter on the process's stack (local variable). This
@@ -104,14 +110,18 @@ waiter - A waiter is a struct that is stored on the stack of a blocked
waiter is sometimes used in reference to the task that is waiting
on a mutex. This is the same as waiter->task.
-waiters - A list of processes that are blocked on a mutex.
+waiters
+ - A list of processes that are blocked on a mutex.
-top waiter - The highest priority process waiting on a specific mutex.
+top waiter
+ - The highest priority process waiting on a specific mutex.
-top pi waiter - The highest priority process waiting on one of the mutexes
+top pi waiter
+ - The highest priority process waiting on one of the mutexes
that a specific process owns.
-Note: task and process are used interchangeably in this document, mostly to
+Note:
+ task and process are used interchangeably in this document, mostly to
differentiate between two processes that are being described together.
@@ -123,7 +133,7 @@ inheritance to take place. Multiple chains may converge, but a chain
would never diverge, since a process can't be blocked on more than one
mutex at a time.
-Example:
+Example::
Process: A, B, C, D, E
Mutexes: L1, L2, L3, L4
@@ -137,21 +147,21 @@ Example:
D owns L4
E blocked on L4
-The chain would be:
+The chain would be::
E->L4->D->L3->C->L2->B->L1->A
To show where two chains merge, we could add another process F and
another mutex L5 where B owns L5 and F is blocked on mutex L5.
-The chain for F would be:
+The chain for F would be::
F->L5->B->L1->A
Since a process may own more than one mutex, but never be blocked on more than
one, the chains merge.
-Here we show both chains:
+Here we show both chains::
E->L4->D->L3->C->L2-+
|
@@ -165,12 +175,12 @@ than the processes to the left or below in the chain.
Also since a mutex may have more than one process blocked on it, we can
have multiple chains merge at mutexes. If we add another process G that is
-blocked on mutex L2:
+blocked on mutex L2::
G->L2->B->L1->A
And once again, to show how this can grow I will show the merging chains
-again.
+again::
E->L4->D->L3->C-+
+->L2-+
@@ -184,7 +194,7 @@ the chain (A and B in this example), must have their priorities increased
to that of G.
Mutex Waiters Tree
------------------
+------------------
Every mutex keeps track of all the waiters that are blocked on itself. The
mutex has a rbtree to store these waiters by priority. This tree is protected
@@ -219,19 +229,19 @@ defined. But is very complex to figure it out, since it depends on all
the nesting of mutexes. Let's look at the example where we have 3 mutexes,
L1, L2, and L3, and four separate functions func1, func2, func3 and func4.
The following shows a locking order of L1->L2->L3, but may not actually
-be directly nested that way.
+be directly nested that way::
-void func1(void)
-{
+ void func1(void)
+ {
mutex_lock(L1);
/* do anything */
mutex_unlock(L1);
-}
+ }
-void func2(void)
-{
+ void func2(void)
+ {
mutex_lock(L1);
mutex_lock(L2);
@@ -239,10 +249,10 @@ void func2(void)
mutex_unlock(L2);
mutex_unlock(L1);
-}
+ }
-void func3(void)
-{
+ void func3(void)
+ {
mutex_lock(L2);
mutex_lock(L3);
@@ -250,30 +260,30 @@ void func3(void)
mutex_unlock(L3);
mutex_unlock(L2);
-}
+ }
-void func4(void)
-{
+ void func4(void)
+ {
mutex_lock(L3);
/* do something again */
mutex_unlock(L3);
-}
+ }
Now we add 4 processes that run each of these functions separately.
Processes A, B, C, and D which run functions func1, func2, func3 and func4
respectively, and such that D runs first and A last. With D being preempted
-in func4 in the "do something again" area, we have a locking that follows:
+in func4 in the "do something again" area, we have a locking that follows::
-D owns L3
- C blocked on L3
- C owns L2
- B blocked on L2
- B owns L1
- A blocked on L1
+ D owns L3
+ C blocked on L3
+ C owns L2
+ B blocked on L2
+ B owns L1
+ A blocked on L1
-And thus we have the chain A->L1->B->L2->C->L3->D.
+ And thus we have the chain A->L1->B->L2->C->L3->D.
This gives us a PI depth of 4 (four processes), but looking at any of the
functions individually, it seems as though they only have at most a locking
@@ -298,7 +308,7 @@ not true, the rtmutex.c code will be broken!), this allows for the least
significant bit to be used as a flag. Bit 0 is used as the "Has Waiters"
flag. It's set whenever there are waiters on a mutex.
-See Documentation/locking/rt-mutex.txt for further details.
+See Documentation/locking/rt-mutex.rst for further details.
cmpxchg Tricks
--------------
@@ -307,17 +317,17 @@ Some architectures implement an atomic cmpxchg (Compare and Exchange). This
is used (when applicable) to keep the fast path of grabbing and releasing
mutexes short.
-cmpxchg is basically the following function performed atomically:
+cmpxchg is basically the following function performed atomically::
-unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
-{
+ unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
+ {
unsigned long T = *A;
if (*A == *B) {
*A = *C;
}
return T;
-}
-#define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
+ }
+ #define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
This is really nice to have, since it allows you to only update a variable
if the variable is what you expect it to be. You know if it succeeded if
@@ -352,9 +362,10 @@ Then rt_mutex_setprio is called to adjust the priority of the task to the
new priority. Note that rt_mutex_setprio is defined in kernel/sched/core.c
to implement the actual change in priority.
-(Note: For the "prio" field in task_struct, the lower the number, the
+Note:
+ For the "prio" field in task_struct, the lower the number, the
higher the priority. A "prio" of 5 is of higher priority than a
- "prio" of 10.)
+ "prio" of 10.
It is interesting to note that rt_mutex_adjust_prio can either increase
or decrease the priority of the task. In the case that a higher priority
@@ -439,6 +450,7 @@ wait_lock, which this code currently holds. So setting the "Has Waiters" flag
forces the current owner to synchronize with this code.
The lock is taken if the following are true:
+
1) The lock has no owner
2) The current task is the highest priority against all other
waiters of the lock
@@ -546,10 +558,13 @@ Credits
-------
Author: Steven Rostedt <rostedt@goodmis.org>
+
Updated: Alex Shi <alex.shi@linaro.org> - 7/6/2017
-Original Reviewers: Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
+Original Reviewers:
+ Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
Randy Dunlap
+
Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior
Updates
diff --git a/Documentation/locking/rt-mutex.txt b/Documentation/locking/rt-mutex.rst
similarity index 71%
rename from Documentation/locking/rt-mutex.txt
rename to Documentation/locking/rt-mutex.rst
index 35793e003041..c365dc302081 100644
--- a/Documentation/locking/rt-mutex.txt
+++ b/Documentation/locking/rt-mutex.rst
@@ -1,5 +1,6 @@
+==================================
RT-mutex subsystem with PI support
-----------------------------------
+==================================
RT-mutexes with priority inheritance are used to support PI-futexes,
which enable pthread_mutex_t priority inheritance attributes
@@ -46,27 +47,30 @@ The state of the rt-mutex is tracked via the owner field of the rt-mutex
structure:
lock->owner holds the task_struct pointer of the owner. Bit 0 is used to
-keep track of the "lock has waiters" state.
+keep track of the "lock has waiters" state:
- owner bit0
+ ============ ======= ================================================
+ owner bit0 Notes
+ ============ ======= ================================================
NULL 0 lock is free (fast acquire possible)
NULL 1 lock is free and has waiters and the top waiter
- is going to take the lock*
+ is going to take the lock [1]_
taskpointer 0 lock is held (fast release possible)
- taskpointer 1 lock is held and has waiters**
+ taskpointer 1 lock is held and has waiters [2]_
+ ============ ======= ================================================
The fast atomic compare exchange based acquire and release is only
possible when bit 0 of lock->owner is 0.
-(*) It also can be a transitional state when grabbing the lock
-with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
-we need to set the bit0 before looking at the lock, and the owner may be
-NULL in this small time, hence this can be a transitional state.
+.. [1] It also can be a transitional state when grabbing the lock
+ with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
+ we need to set the bit0 before looking at the lock, and the owner may
+ be NULL in this small time, hence this can be a transitional state.
-(**) There is a small time when bit 0 is set but there are no
-waiters. This can happen when grabbing the lock in the slow path.
-To prevent a cmpxchg of the owner releasing the lock, we need to
-set this bit before looking at the lock.
+.. [2] There is a small time when bit 0 is set but there are no
+ waiters. This can happen when grabbing the lock in the slow path.
+ To prevent a cmpxchg of the owner releasing the lock, we need to
+ set this bit before looking at the lock.
BTW, there is still technically a "Pending Owner", it's just not called
that anymore. The pending owner happens to be the top_waiter of a lock
diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.rst
similarity index 89%
rename from Documentation/locking/spinlocks.txt
rename to Documentation/locking/spinlocks.rst
index ff35e40bdf5b..098107fb7d86 100644
--- a/Documentation/locking/spinlocks.txt
+++ b/Documentation/locking/spinlocks.rst
@@ -1,8 +1,13 @@
+===============
+Locking lessons
+===============
+
Lesson 1: Spin locks
+====================
-The most basic primitive for locking is spinlock.
+The most basic primitive for locking is spinlock::
-static DEFINE_SPINLOCK(xxx_lock);
+ static DEFINE_SPINLOCK(xxx_lock);
unsigned long flags;
@@ -19,23 +24,25 @@ worry about UP vs SMP issues: the spinlocks work correctly under both.
NOTE! Implications of spin_locks for memory are further described in:
Documentation/memory-barriers.txt
+
(5) LOCK operations.
+
(6) UNLOCK operations.
The above is usually pretty simple (you usually need and want only one
spinlock for most things - using more than one spinlock can make things a
lot more complex and even slower and is usually worth it only for
-sequences that you _know_ need to be split up: avoid it at all cost if you
+sequences that you **know** need to be split up: avoid it at all cost if you
aren't sure).
This is really the only really hard part about spinlocks: once you start
using spinlocks they tend to expand to areas you might not have noticed
before, because you have to make sure the spinlocks correctly protect the
-shared data structures _everywhere_ they are used. The spinlocks are most
+shared data structures **everywhere** they are used. The spinlocks are most
easily added to places that are completely independent of other code (for
example, internal driver data structures that nobody else ever touches).
- NOTE! The spin-lock is safe only when you _also_ use the lock itself
+ NOTE! The spin-lock is safe only when you **also** use the lock itself
to do locking across CPU's, which implies that EVERYTHING that
touches a shared variable has to agree about the spinlock they want
to use.
@@ -43,6 +50,7 @@ example, internal driver data structures that nobody else ever touches).
----
Lesson 2: reader-writer spinlocks.
+==================================
If your data accesses have a very natural pattern where you usually tend
to mostly read from the shared variables, the reader-writer locks
@@ -54,7 +62,7 @@ to change the variables it has to get an exclusive write lock.
simple spinlocks. Unless the reader critical section is long, you
are better off just using spinlocks.
-The routines look the same as above:
+The routines look the same as above::
rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock);
@@ -71,7 +79,7 @@ The routines look the same as above:
The above kind of lock may be useful for complex data structures like
linked lists, especially searching for entries without changing the list
itself. The read lock allows many concurrent readers. Anything that
-_changes_ the list will have to get the write lock.
+**changes** the list will have to get the write lock.
NOTE! RCU is better for list traversal, but requires careful
attention to design detail (see Documentation/RCU/listRCU.txt).
@@ -87,10 +95,11 @@ to get the write-lock at the very beginning.
----
Lesson 3: spinlocks revisited.
+==============================
The single spin-lock primitives above are by no means the only ones. They
are the most safe ones, and the ones that work under all circumstances,
-but partly _because_ they are safe they are also fairly slow. They are slower
+but partly **because** they are safe they are also fairly slow. They are slower
than they'd need to be, because they do have to disable interrupts
(which is just a single instruction on a x86, but it's an expensive one -
and on other architectures it can be worse).
@@ -98,7 +107,7 @@ and on other architectures it can be worse).
If you have a case where you have to protect a data structure across
several CPU's and you want to use spinlocks you can potentially use
cheaper versions of the spinlocks. IFF you know that the spinlocks are
-never used in interrupt handlers, you can use the non-irq versions:
+never used in interrupt handlers, you can use the non-irq versions::
spin_lock(&lock);
...
@@ -110,7 +119,7 @@ This is useful if you know that the data in question is only ever
manipulated from a "process context", ie no interrupts involved.
The reasons you mustn't use these versions if you have interrupts that
-play with the spinlock is that you can get deadlocks:
+play with the spinlock is that you can get deadlocks::
spin_lock(&lock);
...
@@ -147,9 +156,10 @@ indeed), while write-locks need to protect themselves against interrupts.
----
Reference information:
+======================
For dynamic initialization, use spin_lock_init() or rwlock_init() as
-appropriate:
+appropriate::
spinlock_t xxx_lock;
rwlock_t xxx_rw_lock;
diff --git a/Documentation/locking/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.rst
similarity index 93%
rename from Documentation/locking/ww-mutex-design.txt
rename to Documentation/locking/ww-mutex-design.rst
index f0ed7c30e695..1846c199da23 100644
--- a/Documentation/locking/ww-mutex-design.txt
+++ b/Documentation/locking/ww-mutex-design.rst
@@ -1,3 +1,4 @@
+======================================
Wound/Wait Deadlock-Proof Mutex Design
======================================
@@ -85,6 +86,7 @@ Furthermore there are three different class of w/w lock acquire functions:
no deadlock potential and hence the ww_mutex_lock call will block and not
prematurely return -EDEADLK. The advantage of the _slow functions is in
interface safety:
+
- ww_mutex_lock has a __must_check int return type, whereas ww_mutex_lock_slow
has a void return type. Note that since ww mutex code needs loops/retries
anyway the __must_check doesn't result in spurious warnings, even though the
@@ -115,36 +117,36 @@ expect the number of simultaneous competing transactions to be typically small,
and you want to reduce the number of rollbacks.
Three different ways to acquire locks within the same w/w class. Common
-definitions for methods #1 and #2:
+definitions for methods #1 and #2::
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-struct obj {
+ struct obj {
struct ww_mutex lock;
/* obj data */
-};
+ };
-struct obj_entry {
+ struct obj_entry {
struct list_head head;
struct obj *obj;
-};
+ };
Method 1, using a list in execbuf->buffers that's not allowed to be reordered.
This is useful if a list of required objects is already tracked somewhere.
Furthermore the lock helper can use propagate the -EALREADY return code back to
the caller as a signal that an object is twice on the list. This is useful if
the list is constructed from userspace input and the ABI requires userspace to
-not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl).
+not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl)::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *res_obj = NULL;
struct obj_entry *contended_entry = NULL;
struct obj_entry *entry;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
list_for_each_entry (entry, list, head) {
if (entry->obj == res_obj) {
res_obj = NULL;
@@ -160,7 +162,7 @@ retry:
ww_acquire_done(ctx);
return 0;
-err:
+ err:
list_for_each_entry_continue_reverse (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
@@ -176,14 +178,14 @@ err:
ww_acquire_fini(ctx);
return ret;
-}
+ }
Method 2, using a list in execbuf->buffers that can be reordered. Same semantics
of duplicate entry detection using -EALREADY as method 1 above. But the
-list-reordering allows for a bit more idiomatic code.
+list-reordering allows for a bit more idiomatic code::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry, *entry2;
ww_acquire_init(ctx, &ww_class);
@@ -216,24 +218,25 @@ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
ww_acquire_done(ctx);
return 0;
-}
+ }
-Unlocking works the same way for both methods #1 and #2:
+Unlocking works the same way for both methods #1 and #2::
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry;
list_for_each_entry (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
ww_acquire_fini(ctx);
-}
+ }
Method 3 is useful if the list of objects is constructed ad-hoc and not upfront,
e.g. when adjusting edges in a graph where each node has its own ww_mutex lock,
and edges can only be changed when holding the locks of all involved nodes. w/w
mutexes are a natural fit for such a case for two reasons:
+
- They can handle lock-acquisition in any order which allows us to start walking
a graph from a starting point and then iteratively discovering new edges and
locking down the nodes those edges connect to.
@@ -243,6 +246,7 @@ mutexes are a natural fit for such a case for two reasons:
as a starting point).
Note that this approach differs in two important ways from the above methods:
+
- Since the list of objects is dynamically constructed (and might very well be
different when retrying due to hitting the -EDEADLK die condition) there's
no need to keep any object on a persistent list when it's not locked. We can
@@ -260,17 +264,17 @@ any interface misuse for these cases.
Also, method 3 can't fail the lock acquisition step since it doesn't return
-EALREADY. Of course this would be different when using the _interruptible
-variants, but that's outside of the scope of these examples here.
+variants, but that's outside of the scope of these examples here::
-struct obj {
+ struct obj {
struct ww_mutex ww_mutex;
struct list_head locked_list;
-};
+ };
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-void __unlock_objs(struct list_head *list)
-{
+ void __unlock_objs(struct list_head *list)
+ {
struct obj *entry, *temp;
list_for_each_entry_safe (entry, temp, list, locked_list) {
@@ -279,15 +283,15 @@ void __unlock_objs(struct list_head *list)
list_del(&entry->locked_list);
ww_mutex_unlock(entry->ww_mutex)
}
-}
+ }
-void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *obj;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
/* re-init loop start state */
loop {
/* magic code which walks over a graph and decides which objects
@@ -312,13 +316,13 @@ retry:
ww_acquire_done(ctx);
return 0;
-}
+ }
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
__unlock_objs(list);
ww_acquire_fini(ctx);
-}
+ }
Method 4: Only lock one single objects. In that case deadlock detection and
prevention is obviously overkill, since with grabbing just one lock you can't
@@ -329,11 +333,14 @@ Implementation Details
----------------------
Design:
+^^^^^^^
+
ww_mutex currently encapsulates a struct mutex, this means no extra overhead for
normal mutex locks, which are far more common. As such there is only a small
increase in code size if wait/wound mutexes are not used.
We maintain the following invariants for the wait list:
+
(1) Waiters with an acquire context are sorted by stamp order; waiters
without an acquire context are interspersed in FIFO order.
(2) For Wait-Die, among waiters with contexts, only the first one can have
@@ -355,6 +362,8 @@ Design:
therefore be directed towards the uncontended cases.
Lockdep:
+^^^^^^^^
+
Special care has been taken to warn for as many cases of api abuse
as possible. Some common api abuses will be caught with
CONFIG_DEBUG_MUTEXES, but CONFIG_PROVE_LOCKING is recommended.
@@ -379,5 +388,6 @@ Lockdep:
having called ww_acquire_fini on the first.
- 'normal' deadlocks that can occur.
-FIXME: Update this section once we have the TASK_DEADLOCK task state flag magic
-implemented.
+FIXME:
+ Update this section once we have the TASK_DEADLOCK task state flag magic
+ implemented.
diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.txt
index b154f6c0c36e..c33ba2befbf8 100644
--- a/Documentation/pi-futex.txt
+++ b/Documentation/pi-futex.txt
@@ -119,4 +119,4 @@ properties of futexes, and all four combinations are possible: futex,
robust-futex, PI-futex, robust+PI-futex.
More details about priority inheritance can be found in
-Documentation/locking/rt-mutex.txt.
+Documentation/locking/rt-mutex.rst.
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 0ef31666663b..75d9b86fcc50 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -1404,7 +1404,7 @@ Riferimento per l'API dei Futex
Approfondimenti
===============
-- ``Documentation/locking/spinlocks.txt``: la guida di Linus Torvalds agli
+- ``Documentation/locking/spinlocks.rst``: la guida di Linus Torvalds agli
spinlock del kernel.
- Unix Systems for Modern Architectures: Symmetric Multiprocessing and
diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c
index 53187821df01..fcfe1a03c4a1 100644
--- a/drivers/gpu/drm/drm_modeset_lock.c
+++ b/drivers/gpu/drm/drm_modeset_lock.c
@@ -36,7 +36,7 @@
* of extra utility/tracking out of our acquire-ctx. This is provided
* by &struct drm_modeset_lock and &struct drm_modeset_acquire_ctx.
*
- * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt
+ * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.rst
*
* The basic usage pattern is to::
*
diff --git a/include/linux/lockdep.h b/include/linux/lockdep.h
index 30a0f81aa130..ebeedee924f6 100644
--- a/include/linux/lockdep.h
+++ b/include/linux/lockdep.h
@@ -5,7 +5,7 @@
* Copyright (C) 2006,2007 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
* Copyright (C) 2007 Red Hat, Inc., Peter Zijlstra
*
- * see Documentation/locking/lockdep-design.txt for more details.
+ * see Documentation/locking/lockdep-design.rst for more details.
*/
#ifndef __LINUX_LOCKDEP_H
#define __LINUX_LOCKDEP_H
diff --git a/include/linux/mutex.h b/include/linux/mutex.h
index 3093dd162424..dcd03fee6e01 100644
--- a/include/linux/mutex.h
+++ b/include/linux/mutex.h
@@ -151,7 +151,7 @@ static inline bool mutex_is_locked(struct mutex *lock)
/*
* See kernel/locking/mutex.c for detailed documentation of these APIs.
- * Also see Documentation/locking/mutex-design.txt.
+ * Also see Documentation/locking/mutex-design.rst.
*/
#ifdef CONFIG_DEBUG_LOCK_ALLOC
extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
diff --git a/include/linux/rwsem.h b/include/linux/rwsem.h
index 2ea18a3def04..61a084ae17ac 100644
--- a/include/linux/rwsem.h
+++ b/include/linux/rwsem.h
@@ -158,7 +158,7 @@ extern void downgrade_write(struct rw_semaphore *sem);
* static then another method for expressing nested locking is
* the explicit definition of lock class keys and the use of
* lockdep_set_class() at lock initialization time.
- * See Documentation/locking/lockdep-design.txt for more details.)
+ * See Documentation/locking/lockdep-design.rst for more details.)
*/
extern void down_read_nested(struct rw_semaphore *sem, int subclass);
extern void down_write_nested(struct rw_semaphore *sem, int subclass);
diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
index 0c601ae072b3..edd1c082dbf5 100644
--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -16,7 +16,7 @@
* by Steven Rostedt, based on work by Gregory Haskins, Peter Morreale
* and Sven Dietrich.
*
- * Also see Documentation/locking/mutex-design.txt.
+ * Also see Documentation/locking/mutex-design.rst.
*/
#include <linux/mutex.h>
#include <linux/ww_mutex.h>
diff --git a/kernel/locking/rtmutex.c b/kernel/locking/rtmutex.c
index 38fbf9fa7f1b..fa83d36e30c6 100644
--- a/kernel/locking/rtmutex.c
+++ b/kernel/locking/rtmutex.c
@@ -9,7 +9,7 @@
* Copyright (C) 2005 Kihon Technologies Inc., Steven Rostedt
* Copyright (C) 2006 Esben Nielsen
*
- * See Documentation/locking/rt-mutex-design.txt for details.
+ * See Documentation/locking/rt-mutex-design.rst for details.
*/
#include <linux/spinlock.h>
#include <linux/export.h>
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index 3a3554e8ca0f..0a3abf806ae8 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1132,7 +1132,7 @@ config PROVE_LOCKING
the proof of observed correctness is also maintained for an
arbitrary combination of these separate locking variants.
- For more details, see Documentation/locking/lockdep-design.txt.
+ For more details, see Documentation/locking/lockdep-design.rst.
config LOCK_STAT
bool "Lock usage statistics"
@@ -1146,7 +1146,7 @@ config LOCK_STAT
help
This feature enables tracking lock contention points
- For more details, see Documentation/locking/lockstat.txt
+ For more details, see Documentation/locking/lockstat.rst
This also enables lock events required by "perf lock",
subcommand of perf.
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 15/28] docs: mic: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (8 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 14/28] docs: locking: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 16/28] docs: netlabel: " Mauro Carvalho Chehab
` (14 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sudeep Dutt, Ashutosh Dixit
Convert Intel Many Integrated Core architecture docs to ReST.
The conversion is trivial: just add title and literal block
markups, and adjust some identation.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/mic/index.rst | 18 ++++++
.../{mic_overview.txt => mic_overview.rst} | 6 +-
.../{scif_overview.txt => scif_overview.rst} | 58 +++++++++++--------
3 files changed, 57 insertions(+), 25 deletions(-)
create mode 100644 Documentation/mic/index.rst
rename Documentation/mic/{mic_overview.txt => mic_overview.rst} (96%)
rename Documentation/mic/{scif_overview.txt => scif_overview.rst} (76%)
diff --git a/Documentation/mic/index.rst b/Documentation/mic/index.rst
new file mode 100644
index 000000000000..082fa8f6a260
--- /dev/null
+++ b/Documentation/mic/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=============================================
+Intel Many Integrated Core (MIC) architecture
+=============================================
+
+.. toctree::
+ :maxdepth: 1
+
+ mic_overview
+ scif_overview
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/mic/mic_overview.txt b/Documentation/mic/mic_overview.rst
similarity index 96%
rename from Documentation/mic/mic_overview.txt
rename to Documentation/mic/mic_overview.rst
index 074adbdf83a4..17d956bdaf7c 100644
--- a/Documentation/mic/mic_overview.txt
+++ b/Documentation/mic/mic_overview.rst
@@ -1,3 +1,7 @@
+======================================================
+Intel Many Integrated Core (MIC) architecture overview
+======================================================
+
An Intel MIC X100 device is a PCIe form factor add-in coprocessor
card based on the Intel Many Integrated Core (MIC) architecture
that runs a Linux OS. It is a PCIe endpoint in a platform and therefore
@@ -45,7 +49,7 @@ Here is a block diagram of the various components described above. The
virtio backends are situated on the host rather than the card given better
single threaded performance for the host compared to MIC, the ability of
the host to initiate DMA's to/from the card using the MIC DMA engine and
-the fact that the virtio block storage backend can only be on the host.
+the fact that the virtio block storage backend can only be on the host::
+----------+ | +----------+
| Card OS | | | Host OS |
diff --git a/Documentation/mic/scif_overview.txt b/Documentation/mic/scif_overview.rst
similarity index 76%
rename from Documentation/mic/scif_overview.txt
rename to Documentation/mic/scif_overview.rst
index 0a280d986731..4c8ad9e43706 100644
--- a/Documentation/mic/scif_overview.txt
+++ b/Documentation/mic/scif_overview.rst
@@ -1,3 +1,7 @@
+========================================
+Symmetric Communication Interface (SCIF)
+========================================
+
The Symmetric Communication Interface (SCIF (pronounced as skiff)) is a low
level communications API across PCIe currently implemented for MIC. Currently
SCIF provides inter-node communication within a single host platform, where a
@@ -8,8 +12,11 @@ is to deliver the maximum possible performance given the communication
abilities of the hardware. SCIF has been used to implement an offload compiler
runtime and OFED support for MPI implementations for MIC coprocessors.
-==== SCIF API Components ====
+SCIF API Components
+===================
+
The SCIF API has the following parts:
+
1. Connection establishment using a client server model
2. Byte stream messaging intended for short messages
3. Node enumeration to determine online nodes
@@ -28,9 +35,12 @@ can also register local memory which is followed by data transfer using either
DMA, CPU copies or remote memory mapping via mmap. SCIF supports both user and
kernel mode clients which are functionally equivalent.
-==== SCIF Performance for MIC ====
+SCIF Performance for MIC
+========================
+
DMA bandwidth comparison between the TCP (over ethernet over PCIe) stack versus
-SCIF shows the performance advantages of SCIF for HPC applications and runtimes.
+SCIF shows the performance advantages of SCIF for HPC applications and
+runtimes::
Comparison of TCP and SCIF based BW
@@ -66,33 +76,33 @@ space API similar to the kernel API in scif.h. The SCIF user space library
is distributed @ https://software.intel.com/en-us/mic-developer
Here is some pseudo code for an example of how two applications on two PCIe
-nodes would typically use the SCIF API:
+nodes would typically use the SCIF API::
-Process A (on node A) Process B (on node B)
+ Process A (on node A) Process B (on node B)
-/* get online node information */
-scif_get_node_ids(..) scif_get_node_ids(..)
-scif_open(..) scif_open(..)
-scif_bind(..) scif_bind(..)
-scif_listen(..)
-scif_accept(..) scif_connect(..)
-/* SCIF connection established */
+ /* get online node information */
+ scif_get_node_ids(..) scif_get_node_ids(..)
+ scif_open(..) scif_open(..)
+ scif_bind(..) scif_bind(..)
+ scif_listen(..)
+ scif_accept(..) scif_connect(..)
+ /* SCIF connection established */
-/* Send and receive short messages */
-scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
+ /* Send and receive short messages */
+ scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
-/* Register memory */
-scif_register(..) scif_register(..)
+ /* Register memory */
+ scif_register(..) scif_register(..)
-/* RDMA */
-scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
+ /* RDMA */
+ scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
-/* Fence DMAs */
-scif_fence_signal(..) scif_fence_signal(..)
+ /* Fence DMAs */
+ scif_fence_signal(..) scif_fence_signal(..)
-mmap(..) mmap(..)
+ mmap(..) mmap(..)
-/* Access remote registered memory */
+ /* Access remote registered memory */
-/* Close the endpoints */
-scif_close(..) scif_close(..)
+ /* Close the endpoints */
+ scif_close(..) scif_close(..)
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 16/28] docs: netlabel: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (9 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 15/28] docs: mic: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 17/28] docs: pcmcia: " Mauro Carvalho Chehab
` (13 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Paul Moore, netdev, linux-security-module
Convert netlabel documentation to ReST.
This was trivial: just add proper title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Paul Moore <paul@paul-moore.com>
---
.../{cipso_ipv4.txt => cipso_ipv4.rst} | 19 +++++++++++------
Documentation/netlabel/draft_ietf.rst | 5 +++++
Documentation/netlabel/index.rst | 21 +++++++++++++++++++
.../{introduction.txt => introduction.rst} | 16 +++++++++-----
.../{lsm_interface.txt => lsm_interface.rst} | 16 +++++++++-----
5 files changed, 61 insertions(+), 16 deletions(-)
rename Documentation/netlabel/{cipso_ipv4.txt => cipso_ipv4.rst} (87%)
create mode 100644 Documentation/netlabel/draft_ietf.rst
create mode 100644 Documentation/netlabel/index.rst
rename Documentation/netlabel/{introduction.txt => introduction.rst} (91%)
rename Documentation/netlabel/{lsm_interface.txt => lsm_interface.rst} (88%)
diff --git a/Documentation/netlabel/cipso_ipv4.txt b/Documentation/netlabel/cipso_ipv4.rst
similarity index 87%
rename from Documentation/netlabel/cipso_ipv4.txt
rename to Documentation/netlabel/cipso_ipv4.rst
index a6075481fd60..cbd3f3231221 100644
--- a/Documentation/netlabel/cipso_ipv4.txt
+++ b/Documentation/netlabel/cipso_ipv4.rst
@@ -1,10 +1,13 @@
+===================================
NetLabel CIPSO/IPv4 Protocol Engine
-==============================================================================
+===================================
+
Paul Moore, paul.moore@hp.com
May 17, 2006
- * Overview
+Overview
+========
The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial
IP Security Option (CIPSO) draft from July 16, 1992. A copy of this
@@ -13,7 +16,8 @@ draft can be found in this directory
it to an RFC standard it has become a de-facto standard for labeled
networking and is used in many trusted operating systems.
- * Outbound Packet Processing
+Outbound Packet Processing
+==========================
The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by
adding the CIPSO label to the socket. This causes all packets leaving the
@@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is
configured to use CIPSO for packet labeling then a CIPSO IP option will be
generated and attached to the socket.
- * Inbound Packet Processing
+Inbound Packet Processing
+=========================
The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the
IP layer without any special handling required by the LSM. However, in order
@@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet.
This is typically done at the socket layer using the 'socket_sock_rcv_skb()'
LSM hook.
- * Label Translation
+Label Translation
+=================
The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security
attributes such as sensitivity level and category to values which are
@@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the
NetLabel user space communication layer. Each DOI definition can have a
different security attribute mapping table.
- * Label Translation Cache
+Label Translation Cache
+=======================
The NetLabel system provides a framework for caching security attribute
mappings from the network labels to the corresponding LSM identifiers. The
diff --git a/Documentation/netlabel/draft_ietf.rst b/Documentation/netlabel/draft_ietf.rst
new file mode 100644
index 000000000000..5ed39ab8234b
--- /dev/null
+++ b/Documentation/netlabel/draft_ietf.rst
@@ -0,0 +1,5 @@
+Draft IETF CIPSO IP Security
+----------------------------
+
+ .. include:: draft-ietf-cipso-ipsecurity-01.txt
+ :literal:
diff --git a/Documentation/netlabel/index.rst b/Documentation/netlabel/index.rst
new file mode 100644
index 000000000000..47f1e0e5acd1
--- /dev/null
+++ b/Documentation/netlabel/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+========
+NetLabel
+========
+
+.. toctree::
+ :maxdepth: 1
+
+ introduction
+ cipso_ipv4
+ lsm_interface
+
+ draft_ietf
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/netlabel/introduction.txt b/Documentation/netlabel/introduction.rst
similarity index 91%
rename from Documentation/netlabel/introduction.txt
rename to Documentation/netlabel/introduction.rst
index 3caf77bcff0f..9333bbb0adc1 100644
--- a/Documentation/netlabel/introduction.txt
+++ b/Documentation/netlabel/introduction.rst
@@ -1,10 +1,13 @@
+=====================
NetLabel Introduction
-==============================================================================
+=====================
+
Paul Moore, paul.moore@hp.com
August 2, 2006
- * Overview
+Overview
+========
NetLabel is a mechanism which can be used by kernel security modules to attach
security attributes to outgoing network packets generated from user space
@@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets. It
is composed of three main components, the protocol engines, the communication
layer, and the kernel security module API.
- * Protocol Engines
+Protocol Engines
+================
The protocol engines are responsible for both applying and retrieving the
network packet's security attributes. If any translation between the network
@@ -24,7 +28,8 @@ the NetLabel kernel security module API described below.
Detailed information about each NetLabel protocol engine can be found in this
directory.
- * Communication Layer
+Communication Layer
+===================
The communication layer exists to allow NetLabel configuration and monitoring
from user space. The NetLabel communication layer uses a message based
@@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family
names can be found in the 'net/netlabel/' directory as comments in the
header files as well as in 'include/net/netlabel.h'.
- * Security Module API
+Security Module API
+===================
The purpose of the NetLabel security module API is to provide a protocol
independent interface to the underlying NetLabel protocol engines. In addition
diff --git a/Documentation/netlabel/lsm_interface.txt b/Documentation/netlabel/lsm_interface.rst
similarity index 88%
rename from Documentation/netlabel/lsm_interface.txt
rename to Documentation/netlabel/lsm_interface.rst
index 638c74f7de7f..026fc267f798 100644
--- a/Documentation/netlabel/lsm_interface.txt
+++ b/Documentation/netlabel/lsm_interface.rst
@@ -1,10 +1,13 @@
+========================================
NetLabel Linux Security Module Interface
-==============================================================================
+========================================
+
Paul Moore, paul.moore@hp.com
May 17, 2006
- * Overview
+Overview
+========
NetLabel is a mechanism which can set and retrieve security attributes from
network packets. It is intended to be used by LSM developers who want to make
@@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols.
The NetLabel security module API is defined in 'include/net/netlabel.h' but a
brief overview is given below.
- * NetLabel Security Attributes
+NetLabel Security Attributes
+============================
Since NetLabel supports multiple different packet labeling protocols and LSMs
it uses the concept of security attributes to refer to the packet's security
@@ -24,7 +28,8 @@ configuration. It is up to the LSM developer to translate the NetLabel
security attributes into whatever security identifiers are in use for their
particular LSM.
- * NetLabel LSM Protocol Operations
+NetLabel LSM Protocol Operations
+================================
These are the functions which allow the LSM developer to manipulate the labels
on outgoing packets as well as read the labels on incoming packets. Functions
@@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly. These high
level functions are translated into low level protocol operations based on how
the administrator has configured the NetLabel subsystem.
- * NetLabel Label Mapping Cache Operations
+NetLabel Label Mapping Cache Operations
+=======================================
Depending on the exact configuration, translation between the network packet
label and the internal LSM security identifier can be time consuming. The
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 17/28] docs: pcmcia: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (10 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 16/28] docs: netlabel: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 19/28] docs: powerpc: " Mauro Carvalho Chehab
` (12 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Dominik Brodowski
Convert the pcmcia docs to ReST format. Most of the changes here
are trivial.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Dominik Brodowski <linux@dominikbrodowski.net>
---
.../{devicetable.txt => devicetable.rst} | 4 ++
...{driver-changes.txt => driver-changes.rst} | 35 +++++++++++------
.../pcmcia/{driver.txt => driver.rst} | 18 ++++-----
Documentation/pcmcia/index.rst | 20 ++++++++++
.../pcmcia/{locking.txt => locking.rst} | 39 +++++++++++++------
drivers/pcmcia/ds.c | 2 +-
include/pcmcia/ds.h | 2 +-
include/pcmcia/ss.h | 2 +-
8 files changed, 86 insertions(+), 36 deletions(-)
rename Documentation/pcmcia/{devicetable.txt => devicetable.rst} (97%)
rename Documentation/pcmcia/{driver-changes.txt => driver-changes.rst} (90%)
rename Documentation/pcmcia/{driver.txt => driver.rst} (66%)
create mode 100644 Documentation/pcmcia/index.rst
rename Documentation/pcmcia/{locking.txt => locking.rst} (81%)
diff --git a/Documentation/pcmcia/devicetable.txt b/Documentation/pcmcia/devicetable.rst
similarity index 97%
rename from Documentation/pcmcia/devicetable.txt
rename to Documentation/pcmcia/devicetable.rst
index 5f3e00ab54c4..fd1d60d12ca1 100644
--- a/Documentation/pcmcia/devicetable.txt
+++ b/Documentation/pcmcia/devicetable.rst
@@ -1,3 +1,7 @@
+============
+Device table
+============
+
Matching of PCMCIA devices to drivers is done using one or more of the
following criteria:
diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.rst
similarity index 90%
rename from Documentation/pcmcia/driver-changes.txt
rename to Documentation/pcmcia/driver-changes.rst
index 78355c4c268a..33fe9ebec049 100644
--- a/Documentation/pcmcia/driver-changes.txt
+++ b/Documentation/pcmcia/driver-changes.rst
@@ -1,15 +1,21 @@
+==============
+Driver changes
+==============
+
This file details changes in 2.6 which affect PCMCIA card driver authors:
+
* pcmcia_loop_config() and autoconfiguration (as of 2.6.36)
- If struct pcmcia_device *p_dev->config_flags is set accordingly,
+ If `struct pcmcia_device *p_dev->config_flags` is set accordingly,
pcmcia_loop_config() now sets up certain configuration values
automatically, though the driver may still override the settings
in the callback function. The following autoconfiguration options
are provided at the moment:
- CONF_AUTO_CHECK_VCC : check for matching Vcc
- CONF_AUTO_SET_VPP : set Vpp
- CONF_AUTO_AUDIO : auto-enable audio line, if required
- CONF_AUTO_SET_IO : set ioport resources (->resource[0,1])
- CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
+
+ - CONF_AUTO_CHECK_VCC : check for matching Vcc
+ - CONF_AUTO_SET_VPP : set Vpp
+ - CONF_AUTO_AUDIO : auto-enable audio line, if required
+ - CONF_AUTO_SET_IO : set ioport resources (->resource[0,1])
+ - CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
* pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36)
pcmcia_request_configuration() got renamed to pcmcia_enable_device(),
@@ -19,14 +25,14 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* pcmcia_request_window changes (as of 2.6.36)
Instead of win_req_t, drivers are now requested to fill out
- struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport
+ `struct pcmcia_device *p_dev->resource[2,3,4,5]` for up to four ioport
ranges. After a call to pcmcia_request_window(), the regions found there
are reserved and may be used immediately -- until pcmcia_release_window()
is called.
* pcmcia_request_io changes (as of 2.6.36)
Instead of io_req_t, drivers are now requested to fill out
- struct pcmcia_device *p_dev->resource[0,1] for up to two ioport
+ `struct pcmcia_device *p_dev->resource[0,1]` for up to two ioport
ranges. After a call to pcmcia_request_io(), the ports found there
are reserved, after calling pcmcia_request_configuration(), they may
be used.
@@ -42,7 +48,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* New IRQ request rules (as of 2.6.35)
Instead of the old pcmcia_request_irq() interface, drivers may now
choose between:
- - calling request_irq/free_irq directly. Use the IRQ from *p_dev->irq.
+
+ - calling request_irq/free_irq directly. Use the IRQ from `*p_dev->irq`.
- use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will
clean up automatically on calls to pcmcia_disable_device() or
device ejection.
@@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
exports for them were removed.
* Unify detach and REMOVAL event code, as well as attach and INSERTION
- code (as of 2.6.16)
+ code (as of 2.6.16)::
+
void (*remove) (struct pcmcia_device *dev);
int (*probe) (struct pcmcia_device *dev);
-* Move suspend, resume and reset out of event handler (as of 2.6.16)
+* Move suspend, resume and reset out of event handler (as of 2.6.16)::
+
int (*suspend) (struct pcmcia_device *dev);
int (*resume) (struct pcmcia_device *dev);
+
should be initialized in struct pcmcia_driver, and handle
(SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events
@@ -117,7 +127,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* core functions no longer available (as of 2.6.11)
The following functions have been removed from the kernel source
because they are unused by all in-kernel drivers, and no external
- driver was reported to rely on them:
+ driver was reported to rely on them::
+
pcmcia_get_first_region()
pcmcia_get_next_region()
pcmcia_modify_window()
diff --git a/Documentation/pcmcia/driver.txt b/Documentation/pcmcia/driver.rst
similarity index 66%
rename from Documentation/pcmcia/driver.txt
rename to Documentation/pcmcia/driver.rst
index 0ac167920778..5c4fe84d51c1 100644
--- a/Documentation/pcmcia/driver.txt
+++ b/Documentation/pcmcia/driver.rst
@@ -1,16 +1,16 @@
+=============
PCMCIA Driver
--------------
-
+=============
sysfs
-----
New PCMCIA IDs may be added to a device driver pcmcia_device_id table at
-runtime as shown below:
+runtime as shown below::
-echo "match_flags manf_id card_id func_id function device_no \
-prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
-/sys/bus/pcmcia/drivers/{driver}/new_id
+ echo "match_flags manf_id card_id func_id function device_no \
+ prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
+ /sys/bus/pcmcia/drivers/{driver}/new_id
All fields are passed in as hexadecimal values (no leading 0x).
The meaning is described in the PCMCIA specification, the match_flags is
@@ -22,9 +22,9 @@ PCMCIA device listed in its (newly updated) pcmcia_device_id list.
A common use-case is to add a new device according to the manufacturer ID
and the card ID (form the manf_id and card_id file in the device tree).
-For this, just use:
+For this, just use::
-echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
- /sys/bus/pcmcia/drivers/{driver}/new_id
+ echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
+ /sys/bus/pcmcia/drivers/{driver}/new_id
after loading the driver.
diff --git a/Documentation/pcmcia/index.rst b/Documentation/pcmcia/index.rst
new file mode 100644
index 000000000000..779c8527109e
--- /dev/null
+++ b/Documentation/pcmcia/index.rst
@@ -0,0 +1,20 @@
+:orphan:
+
+======
+pcmcia
+======
+
+.. toctree::
+ :maxdepth: 1
+
+ driver
+ devicetable
+ locking
+ driver-changes
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/pcmcia/locking.txt b/Documentation/pcmcia/locking.rst
similarity index 81%
rename from Documentation/pcmcia/locking.txt
rename to Documentation/pcmcia/locking.rst
index b2c9b478906b..e35257139c89 100644
--- a/Documentation/pcmcia/locking.txt
+++ b/Documentation/pcmcia/locking.rst
@@ -1,3 +1,7 @@
+=======
+Locking
+=======
+
This file explains the locking and exclusion scheme used in the PCCARD
and PCMCIA subsystems.
@@ -5,16 +9,21 @@ and PCMCIA subsystems.
A) Overview, Locking Hierarchy:
===============================
-pcmcia_socket_list_rwsem - protects only the list of sockets
-- skt_mutex - serializes card insert / ejection
- - ops_mutex - serializes socket operation
+pcmcia_socket_list_rwsem
+ - protects only the list of sockets
+
+- skt_mutex
+ - serializes card insert / ejection
+
+ - ops_mutex
+ - serializes socket operation
B) Exclusion
============
The following functions and callbacks to struct pcmcia_socket must
-be called with "skt_mutex" held:
+be called with "skt_mutex" held::
socket_detect_change()
send_event()
@@ -31,7 +40,7 @@ be called with "skt_mutex" held:
struct pcmcia_callback *callback
The following functions and callbacks to struct pcmcia_socket must
-be called with "ops_mutex" held:
+be called with "ops_mutex" held::
socket_reset()
socket_setup()
@@ -39,7 +48,7 @@ be called with "ops_mutex" held:
struct pccard_operations *ops
struct pccard_resource_ops *resource_ops;
-Note that send_event() and struct pcmcia_callback *callback must not be
+Note that send_event() and `struct pcmcia_callback *callback` must not be
called with "ops_mutex" held.
@@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex.
The "main" struct pcmcia_socket is protected as follows (read-only fields
or single-use fields not mentioned):
-- by pcmcia_socket_list_rwsem:
+- by pcmcia_socket_list_rwsem::
+
struct list_head socket_list;
-- by thread_lock:
+- by thread_lock::
+
unsigned int thread_events;
-- by skt_mutex:
+- by skt_mutex::
+
u_int suspended_state;
void (*tune_bridge);
struct pcmcia_callback *callback;
int resume_status;
-- by ops_mutex:
+- by ops_mutex::
+
socket_state_t socket;
u_int state;
u_short lock_count;
@@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields
or single-use fields not mentioned):
-- by pcmcia_socket->ops_mutex:
+- by pcmcia_socket->ops_mutex::
+
struct list_head socket_device_list;
struct config_t *function_config;
u16 _irq:1;
@@ -111,7 +125,8 @@ or single-use fields not mentioned):
u16 suspended:1;
u16 _removed:1;
-- by the PCMCIA driver:
+- by the PCMCIA driver::
+
io_req_t io;
irq_req_t irq;
config_req_t conf;
diff --git a/drivers/pcmcia/ds.c b/drivers/pcmcia/ds.c
index a9258f641cee..5230e284bb20 100644
--- a/drivers/pcmcia/ds.c
+++ b/drivers/pcmcia/ds.c
@@ -67,7 +67,7 @@ static void pcmcia_check_driver(struct pcmcia_driver *p_drv)
"be 0x%x\n", p_drv->name, did->prod_id[i],
did->prod_id_hash[i], hash);
printk(KERN_DEBUG "pcmcia: see "
- "Documentation/pcmcia/devicetable.txt for "
+ "Documentation/pcmcia/devicetable.rst for "
"details\n");
}
did++;
diff --git a/include/pcmcia/ds.h b/include/pcmcia/ds.h
index 3037157855f0..4e58c20dabcb 100644
--- a/include/pcmcia/ds.h
+++ b/include/pcmcia/ds.h
@@ -39,7 +39,7 @@ struct config_t;
struct net_device;
/* dynamic device IDs for PCMCIA device drivers. See
- * Documentation/pcmcia/driver.txt for details.
+ * Documentation/pcmcia/driver.rst for details.
*/
struct pcmcia_dynids {
struct mutex lock;
diff --git a/include/pcmcia/ss.h b/include/pcmcia/ss.h
index 731cde010f42..89629ee57840 100644
--- a/include/pcmcia/ss.h
+++ b/include/pcmcia/ss.h
@@ -190,7 +190,7 @@ struct pcmcia_socket {
unsigned int sysfs_events;
/* For the non-trivial interaction between these locks,
- * see Documentation/pcmcia/locking.txt */
+ * see Documentation/pcmcia/locking.rst */
struct mutex skt_mutex;
struct mutex ops_mutex;
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 19/28] docs: powerpc: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (11 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 17/28] docs: pcmcia: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-14 20:36 ` Jonathan Corbet
2019-06-12 17:52 ` [PATCH v4 20/28] docs: pps.txt: convert to ReST and rename to pps.rst Mauro Carvalho Chehab
` (11 subsequent siblings)
24 siblings, 1 reply; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Linas Vepstas, Russell Currey, Sam Bobroff,
Oliver O'Halloran, Bjorn Helgaas, Benjamin Herrenschmidt,
Paul Mackerras, Michael Ellerman, Frederic Barrat,
Andrew Donnellan, Manoj N. Kumar, Matthew R. Ochs, Uma Krishnan,
Qiang Zhao, Li Yang, Greg Kroah-Hartman, Jiri Slaby, linux-pci,
linuxppc-dev, linux-scsi, linux-arm-kernel, Andrew Donnellan
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
Documentation/PCI/pci-error-recovery.rst | 23 ++-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +++-
.../{cpu_families.txt => cpu_families.rst} | 23 +--
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 ++++--
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 ++++++------
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +++++++------
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 ++++++------
Documentation/powerpc/index.rst | 34 ++++
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
Documentation/powerpc/ptrace.rst | 156 ++++++++++++++++++
Documentation/powerpc/ptrace.txt | 151 -----------------
.../{qe_firmware.txt => qe_firmware.rst} | 37 +++--
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 ++--
...al_memory.txt => transactional_memory.rst} | 45 ++---
MAINTAINERS | 6 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
26 files changed, 584 insertions(+), 427 deletions(-)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
create mode 100644 Documentation/powerpc/ptrace.rst
delete mode 100644 Documentation/powerpc/ptrace.txt
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..acc21ecca322 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
.. note::
Implementation details for the powerpc platform are discussed in
- the file Documentation/powerpc/eeh-pci-error-recovery.txt
+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
@@ -422,3 +422,24 @@ That is, the recovery API only requires that:
- drivers/net/cxgb3
- drivers/net/s2io.c
- drivers/net/qlge
+
+>>> As of this writing, there is a growing list of device drivers with
+>>> patches implementing error recovery. Not all of these patches are in
+>>> mainline yet. These may be used as "examples":
+>>>
+>>> drivers/scsi/ipr
+>>> drivers/scsi/sym53c8xx_2
+>>> drivers/scsi/qla2xxx
+>>> drivers/scsi/lpfc
+>>> drivers/next/bnx2.c
+>>> drivers/next/e100.c
+>>> drivers/net/e1000
+>>> drivers/net/e1000e
+>>> drivers/net/ixgb
+>>> drivers/net/ixgbe
+>>> drivers/net/cxgb3
+>>> drivers/net/s2io.c
+>>> drivers/net/qlge
+
+The End
+-------
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+ - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -28,7 +32,7 @@ Introduction
responsible for the initialization of the adapter, setting up the
special path for user space access, and performing error recovery. It
communicates directly the Flash Accelerator Functional Unit (AFU)
- as described in Documentation/powerpc/cxl.txt.
+ as described in Documentation/powerpc/cxl.rst.
The cxlflash driver supports two, mutually exclusive, modes of
operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
if it points to cache inhibited (CI) memory. Currently Linux has no way to
disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
writing the DAWR.
To double check the DAWR is working, run this kernel selftest:
+
tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 0c41d6d463f3..d7fa7c35dd12 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..1ff17268db46
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+:orphan:
+
+=======
+powerpc
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ bootwrapper
+ cpu_families
+ cpu_features
+ cxl
+ cxlflash
+ dawr-power9
+ dscr
+ eeh-pci-error-recovery
+ firmware-assisted-dump
+ hvcs
+ isa-versions
+ mpc52xx
+ pci_iov_resource_on_powernv
+ pmu-ebb
+ ptrace
+ qe_firmware
+ syscall64-abi
+ transactional_memory
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -60,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -73,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.rst b/Documentation/powerpc/ptrace.rst
new file mode 100644
index 000000000000..864d4b6dddd1
--- /dev/null
+++ b/Documentation/powerpc/ptrace.rst
@@ -0,0 +1,156 @@
+======
+Ptrace
+======
+
+GDB intends to support the following hardware debug features of BookE
+processors:
+
+4 hardware breakpoints (IAC)
+2 hardware watchpoints (read, write and read-write) (DAC)
+2 value conditions for the hardware watchpoints (DVC)
+
+For that, we need to extend ptrace so that GDB can query and set these
+resources. Since we're extending, we're trying to create an interface
+that's extendable and that covers both BookE and server processors, so
+that GDB doesn't need to special-case each of them. We added the
+following 3 new ptrace requests.
+
+1. PTRACE_PPC_GETHWDEBUGINFO
+============================
+
+Query for GDB to discover the hardware debug features. The main info to
+be returned here is the minimum alignment for the hardware watchpoints.
+BookE processors don't have restrictions here, but server processors have
+an 8-byte alignment restriction for hardware watchpoints. We'd like to avoid
+adding special cases to GDB based on what it sees in AUXV.
+
+Since we're at it, we added other useful info that the kernel can return to
+GDB: this query will return the number of hardware breakpoints, hardware
+watchpoints and whether it supports a range of addresses and a condition.
+The query will fill the following structure provided by the requesting process::
+
+ struct ppc_debug_info {
+ unit32_t version;
+ unit32_t num_instruction_bps;
+ unit32_t num_data_bps;
+ unit32_t num_condition_regs;
+ unit32_t data_bp_alignment;
+ unit32_t sizeof_condition; /* size of the DVC register */
+ uint64_t features; /* bitmask of the individual flags */
+ };
+
+features will have bits indicating whether there is support for::
+
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+
+2. PTRACE_SETHWDEBUG
+
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
+
+ struct ppc_hw_breakpoint {
+ uint32_t version;
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ uint32_t trigger_type; /* only some combinations allowed */
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
+ uint32_t addr_mode; /* address match mode */
+
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ uint32_t condition_mode; /* break/watchpoint condition flags */
+
+ uint64_t addr;
+ uint64_t addr2;
+ uint64_t condition_value;
+ };
+
+A request specifies one event, not necessarily just one register to be set.
+For instance, if the request is for a watchpoint with a condition, both the
+DAC and DVC registers will be set in the same request.
+
+With this GDB can ask for all kinds of hardware breakpoints and watchpoints
+that the BookE supports. COMEFROM breakpoints available in server processors
+are not contemplated, but that is out of the scope of this work.
+
+ptrace will return an integer (handle) uniquely identifying the breakpoint or
+watchpoint just created. This integer will be used in the PTRACE_DELHWDEBUG
+request to ask for its removal. Return -ENOSPC if the requested breakpoint
+can't be allocated on the registers.
+
+Some examples of using the structure to:
+
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+3. PTRACE_DELHWDEBUG
+
+Takes an integer which identifies an existing breakpoint or watchpoint
+(i.e., the value returned from PTRACE_SETHWDEBUG), and deletes the
+corresponding breakpoint or watchpoint..
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.txt
deleted file mode 100644
index 99c5ce88d0fe..000000000000
--- a/Documentation/powerpc/ptrace.txt
+++ /dev/null
@@ -1,151 +0,0 @@
-GDB intends to support the following hardware debug features of BookE
-processors:
-
-4 hardware breakpoints (IAC)
-2 hardware watchpoints (read, write and read-write) (DAC)
-2 value conditions for the hardware watchpoints (DVC)
-
-For that, we need to extend ptrace so that GDB can query and set these
-resources. Since we're extending, we're trying to create an interface
-that's extendable and that covers both BookE and server processors, so
-that GDB doesn't need to special-case each of them. We added the
-following 3 new ptrace requests.
-
-1. PTRACE_PPC_GETHWDEBUGINFO
-
-Query for GDB to discover the hardware debug features. The main info to
-be returned here is the minimum alignment for the hardware watchpoints.
-BookE processors don't have restrictions here, but server processors have
-an 8-byte alignment restriction for hardware watchpoints. We'd like to avoid
-adding special cases to GDB based on what it sees in AUXV.
-
-Since we're at it, we added other useful info that the kernel can return to
-GDB: this query will return the number of hardware breakpoints, hardware
-watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
-
-struct ppc_debug_info {
- unit32_t version;
- unit32_t num_instruction_bps;
- unit32_t num_data_bps;
- unit32_t num_condition_regs;
- unit32_t data_bp_alignment;
- unit32_t sizeof_condition; /* size of the DVC register */
- uint64_t features; /* bitmask of the individual flags */
-};
-
-features will have bits indicating whether there is support for:
-
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
-
-2. PTRACE_SETHWDEBUG
-
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
-
-struct ppc_hw_breakpoint {
- uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
- uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
- uint32_t addr_mode; /* address match mode */
-
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
- uint32_t condition_mode; /* break/watchpoint condition flags */
-
- uint64_t addr;
- uint64_t addr2;
- uint64_t condition_value;
-};
-
-A request specifies one event, not necessarily just one register to be set.
-For instance, if the request is for a watchpoint with a condition, both the
-DAC and DVC registers will be set in the same request.
-
-With this GDB can ask for all kinds of hardware breakpoints and watchpoints
-that the BookE supports. COMEFROM breakpoints available in server processors
-are not contemplated, but that is out of the scope of this work.
-
-ptrace will return an integer (handle) uniquely identifying the breakpoint or
-watchpoint just created. This integer will be used in the PTRACE_DELHWDEBUG
-request to ask for its removal. Return -ENOSPC if the requested breakpoint
-can't be allocated on the registers.
-
-Some examples of using the structure to:
-
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-3. PTRACE_DELHWDEBUG
-
-Takes an integer which identifies an existing breakpoint or watchpoint
-(i.e., the value returned from PTRACE_SETHWDEBUG), and deletes the
-corresponding breakpoint or watchpoint..
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 1c9ed0a5a9df..b3746e7b5652 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4401,7 +4401,7 @@ F: arch/powerpc/platforms/powernv/pci-cxl.c
F: drivers/misc/cxl/
F: include/misc/cxl*
F: include/uapi/misc/cxl.h
-F: Documentation/powerpc/cxl.txt
+F: Documentation/powerpc/cxl.rst
F: Documentation/ABI/testing/sysfs-class-cxl
CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4412,7 +4412,7 @@ L: linux-scsi@vger.kernel.org
S: Supported
F: drivers/scsi/cxlflash/
F: include/uapi/scsi/cxlflash_ioctl.h
-F: Documentation/powerpc/cxlflash.txt
+F: Documentation/powerpc/cxlflash.rst
CYBERPRO FB DRIVER
M: Russell King <linux@armlinux.org.uk>
@@ -12208,7 +12208,7 @@ F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
-F: Documentation/powerpc/eeh-pci-error-recovery.txt
+F: Documentation/powerpc/eeh-pci-error-recovery.rst
F: arch/powerpc/kernel/eeh*.c
F: arch/powerpc/platforms/*/eeh*.c
F: arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index 6b86055e5251..aaf2a56bb012 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -910,7 +910,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
*
* Call convention:
*
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
*
* For hypercalls, the register convention is as follows:
* r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index ba38c4bb2a88..417df7e19281 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -430,7 +430,7 @@ static void qe_upload_microcode(const void *base,
/*
* Upload a microcode to the I-RAM at a specific address.
*
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
* uploading.
*
* Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
* using the 2.6 Linux kernel kref construct.
*
* For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
*/
#include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
/* Structure that defines QE firmware binary files.
*
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
* fields.
*/
struct qe_firmware {
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 20/28] docs: pps.txt: convert to ReST and rename to pps.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (12 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 19/28] docs: powerpc: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 21/28] docs: ptp.txt: convert to ReST and move to driver-api Mauro Carvalho Chehab
` (10 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rodolfo Giometti
This file is already in a good shape: just its title and
adding some literal block markups is needed for it to be
part of the document.
While it has a small chapter with sysfs stuff, most of
the document is focused on driver development.
As it describes a kernel API, move it to the driver-api
directory.
In order to avoid conflicts, let's add an :orphan: tag
to it, to be removed when added to the driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rodolfo Giometti <giometti@enneenne.com>
---
.../{pps/pps.txt => driver-api/pps.rst} | 67 ++++++++++---------
MAINTAINERS | 2 +-
2 files changed, 36 insertions(+), 33 deletions(-)
rename Documentation/{pps/pps.txt => driver-api/pps.rst} (89%)
diff --git a/Documentation/pps/pps.txt b/Documentation/driver-api/pps.rst
similarity index 89%
rename from Documentation/pps/pps.txt
rename to Documentation/driver-api/pps.rst
index 99f5d8c4c652..1456d2c32ebd 100644
--- a/Documentation/pps/pps.txt
+++ b/Documentation/driver-api/pps.rst
@@ -1,8 +1,10 @@
+:orphan:
- PPS - Pulse Per Second
- ----------------------
+======================
+PPS - Pulse Per Second
+======================
-(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
+Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
@@ -88,7 +90,7 @@ Coding example
--------------
To register a PPS source into the kernel you should define a struct
-pps_source_info as follows:
+pps_source_info as follows::
static struct pps_source_info pps_ktimer_info = {
.name = "ktimer",
@@ -101,12 +103,12 @@ pps_source_info as follows:
};
and then calling the function pps_register_source() in your
-initialization routine as follows:
+initialization routine as follows::
source = pps_register_source(&pps_ktimer_info,
PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
-The pps_register_source() prototype is:
+The pps_register_source() prototype is::
int pps_register_source(struct pps_source_info *info, int default_params)
@@ -118,7 +120,7 @@ pps_source_info which describe the capabilities of the driver).
Once you have registered a new PPS source into the system you can
signal an assert event (for example in the interrupt handler routine)
-just using:
+just using::
pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
@@ -134,13 +136,13 @@ Please see the file drivers/pps/clients/pps-ktimer.c for example code.
SYSFS support
-------------
-If the SYSFS filesystem is enabled in the kernel it provides a new class:
+If the SYSFS filesystem is enabled in the kernel it provides a new class::
$ ls /sys/class/pps/
pps0/ pps1/ pps2/
Every directory is the ID of a PPS sources defined in the system and
-inside you find several files:
+inside you find several files::
$ ls -F /sys/class/pps/pps0/
assert dev mode path subsystem@
@@ -148,7 +150,7 @@ inside you find several files:
Inside each "assert" and "clear" file you can find the timestamp and a
-sequence number:
+sequence number::
$ cat /sys/class/pps/pps0/assert
1170026870.983207967#8
@@ -175,11 +177,11 @@ and the userland tools available in your distribution's pps-tools package,
http://linuxpps.org , or https://github.com/redlab-i/pps-tools.
Once you have enabled the compilation of pps-ktimer just modprobe it (if
-not statically compiled):
+not statically compiled)::
# modprobe pps-ktimer
-and the run ppstest as follow:
+and the run ppstest as follow::
$ ./ppstest /dev/pps1
trying PPS source "/dev/pps1"
@@ -204,26 +206,27 @@ nor affordable. The cheap way is to load a PPS generator on one of the
computers (master) and PPS clients on others (slaves), and use very simple
cables to deliver signals using parallel ports, for example.
-Parallel port cable pinout:
-pin name master slave
-1 STROBE *------ *
-2 D0 * | *
-3 D1 * | *
-4 D2 * | *
-5 D3 * | *
-6 D4 * | *
-7 D5 * | *
-8 D6 * | *
-9 D7 * | *
-10 ACK * ------*
-11 BUSY * *
-12 PE * *
-13 SEL * *
-14 AUTOFD * *
-15 ERROR * *
-16 INIT * *
-17 SELIN * *
-18-25 GND *-----------*
+Parallel port cable pinout::
+
+ pin name master slave
+ 1 STROBE *------ *
+ 2 D0 * | *
+ 3 D1 * | *
+ 4 D2 * | *
+ 5 D3 * | *
+ 6 D4 * | *
+ 7 D5 * | *
+ 8 D6 * | *
+ 9 D7 * | *
+ 10 ACK * ------*
+ 11 BUSY * *
+ 12 PE * *
+ 13 SEL * *
+ 14 AUTOFD * *
+ 15 ERROR * *
+ 16 INIT * *
+ 17 SELIN * *
+ 18-25 GND *-----------*
Please note that parallel port interrupt occurs only on high->low transition,
so it is used for PPS assert edge. PPS clear edge can be determined only
diff --git a/MAINTAINERS b/MAINTAINERS
index b3746e7b5652..5c5714eddde4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12709,7 +12709,7 @@ M: Rodolfo Giometti <giometti@enneenne.com>
W: http://wiki.enneenne.com/index.php/LinuxPPS_support
L: linuxpps@ml.enneenne.com (subscribers-only)
S: Maintained
-F: Documentation/pps/
+F: Documentation/driver-api/pps.rst
F: Documentation/devicetree/bindings/pps/pps-gpio.txt
F: Documentation/ABI/testing/sysfs-pps
F: drivers/pps/
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 21/28] docs: ptp.txt: convert to ReST and move to driver-api
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (13 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 20/28] docs: pps.txt: convert to ReST and rename to pps.rst Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 22/28] docs: riscv: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (9 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Richard Cochran, David S. Miller, netdev
The conversion is trivial: just adjust title markups.
In order to avoid conflicts, let's add an :orphan: tag
to it, to be removed when this file gets added to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Richard Cochran <richardcochran@gmail.com>
---
.../{ptp/ptp.txt => driver-api/ptp.rst} | 26 +++++++++++++------
Documentation/networking/timestamping.txt | 2 +-
MAINTAINERS | 2 +-
3 files changed, 20 insertions(+), 10 deletions(-)
rename Documentation/{ptp/ptp.txt => driver-api/ptp.rst} (88%)
diff --git a/Documentation/ptp/ptp.txt b/Documentation/driver-api/ptp.rst
similarity index 88%
rename from Documentation/ptp/ptp.txt
rename to Documentation/driver-api/ptp.rst
index 11e904ee073f..b6e65d66d37a 100644
--- a/Documentation/ptp/ptp.txt
+++ b/Documentation/driver-api/ptp.rst
@@ -1,5 +1,8 @@
+:orphan:
-* PTP hardware clock infrastructure for Linux
+===========================================
+PTP hardware clock infrastructure for Linux
+===========================================
This patch set introduces support for IEEE 1588 PTP clocks in
Linux. Together with the SO_TIMESTAMPING socket options, this
@@ -22,7 +25,8 @@
- Period output signals configurable from user space
- Synchronization of the Linux system time via the PPS subsystem
-** PTP hardware clock kernel API
+PTP hardware clock kernel API
+=============================
A PTP clock driver registers itself with the class driver. The
class driver handles all of the dealings with user space. The
@@ -36,7 +40,8 @@
development, it can be useful to have more than one clock in a
single system, in order to allow performance comparisons.
-** PTP hardware clock user space API
+PTP hardware clock user space API
+=================================
The class driver also creates a character device for each
registered clock. User space can use an open file descriptor from
@@ -49,7 +54,8 @@
ancillary clock features. User space can receive time stamped
events via blocking read() and poll().
-** Writing clock drivers
+Writing clock drivers
+=====================
Clock drivers include include/linux/ptp_clock_kernel.h and register
themselves by presenting a 'struct ptp_clock_info' to the
@@ -66,14 +72,17 @@
class driver, since the lock may also be needed by the clock
driver's interrupt service routine.
-** Supported hardware
+Supported hardware
+==================
+
+ * Freescale eTSEC gianfar
- + Freescale eTSEC gianfar
- 2 Time stamp external triggers, programmable polarity (opt. interrupt)
- 2 Alarm registers (optional interrupt)
- 3 Periodic signals (optional interrupt)
- + National DP83640
+ * National DP83640
+
- 6 GPIOs programmable as inputs or outputs
- 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
used as general inputs or outputs
@@ -81,6 +90,7 @@
- GPIO outputs can produce periodic signals
- 1 interrupt pin
- + Intel IXP465
+ * Intel IXP465
+
- Auxiliary Slave/Master Mode Snapshot (optional interrupt)
- Target Time (optional interrupt)
diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt
index bbdaf8990031..8dd6333c3270 100644
--- a/Documentation/networking/timestamping.txt
+++ b/Documentation/networking/timestamping.txt
@@ -368,7 +368,7 @@ ts[1] used to hold hardware timestamps converted to system time.
Instead, expose the hardware clock device on the NIC directly as
a HW PTP clock source, to allow time conversion in userspace and
optionally synchronize system time with a userspace PTP stack such
-as linuxptp. For the PTP clock API, see Documentation/ptp/ptp.txt.
+as linuxptp. For the PTP clock API, see Documentation/driver-api/ptp.rst.
Note that if the SO_TIMESTAMP or SO_TIMESTAMPNS option is enabled
together with SO_TIMESTAMPING using SOF_TIMESTAMPING_SOFTWARE, a false
diff --git a/MAINTAINERS b/MAINTAINERS
index 5c5714eddde4..9d9399c9cf47 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12815,7 +12815,7 @@ L: netdev@vger.kernel.org
S: Maintained
W: http://linuxptp.sourceforge.net/
F: Documentation/ABI/testing/sysfs-ptp
-F: Documentation/ptp/*
+F: Documentation/driver-api/ptp.rst
F: drivers/net/phy/dp83640*
F: drivers/ptp/*
F: include/linux/ptp_cl*
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 22/28] docs: riscv: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (14 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 21/28] docs: ptp.txt: convert to ReST and move to driver-api Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 23/28] docs: target: " Mauro Carvalho Chehab
` (8 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Palmer Dabbelt, Albert Ou, linux-riscv
The conversion here is trivial:
- Adjust the document title's markup
- Do some whitespace alignment;
- mark literal blocks;
- Use ReST way to markup indented lists.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/riscv/index.rst | 17 ++++
Documentation/riscv/{pmu.txt => pmu.rst} | 98 +++++++++++++-----------
2 files changed, 69 insertions(+), 46 deletions(-)
create mode 100644 Documentation/riscv/index.rst
rename Documentation/riscv/{pmu.txt => pmu.rst} (77%)
diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
new file mode 100644
index 000000000000..c4b906d9b5a7
--- /dev/null
+++ b/Documentation/riscv/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+===================
+RISC-V architecture
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ pmu
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/riscv/pmu.txt b/Documentation/riscv/pmu.rst
similarity index 77%
rename from Documentation/riscv/pmu.txt
rename to Documentation/riscv/pmu.rst
index b29f03a6d82f..acb216b99c26 100644
--- a/Documentation/riscv/pmu.txt
+++ b/Documentation/riscv/pmu.rst
@@ -1,5 +1,7 @@
+===================================
Supporting PMUs on RISC-V platforms
-==========================================
+===================================
+
Alan Kao <alankao@andestech.com>, Mar 2018
Introduction
@@ -77,13 +79,13 @@ Note that some features can be done in this stage as well:
(2) privilege level setting (user space only, kernel space only, both);
(3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*;
(4) tweaks for non-sampling events, which will be utilized by functions such as
-*perf_adjust_period*, usually something like the follows:
+ *perf_adjust_period*, usually something like the follows::
-if (!is_sampling_event(event)) {
- hwc->sample_period = x86_pmu.max_period;
- hwc->last_period = hwc->sample_period;
- local64_set(&hwc->period_left, hwc->sample_period);
-}
+ if (!is_sampling_event(event)) {
+ hwc->sample_period = x86_pmu.max_period;
+ hwc->last_period = hwc->sample_period;
+ local64_set(&hwc->period_left, hwc->sample_period);
+ }
In the case of *riscv_base_pmu*, only (3) is provided for now.
@@ -94,10 +96,10 @@ In the case of *riscv_base_pmu*, only (3) is provided for now.
3.1. Interrupt Initialization
This often occurs at the beginning of the *event_init* method. In common
-practice, this should be a code segment like
+practice, this should be a code segment like::
-int x86_reserve_hardware(void)
-{
+ int x86_reserve_hardware(void)
+ {
int err = 0;
if (!atomic_inc_not_zero(&pmc_refcount)) {
@@ -114,7 +116,7 @@ int x86_reserve_hardware(void)
}
return err;
-}
+ }
And the magic is in *reserve_pmc_hardware*, which usually does atomic
operations to make implemented IRQ accessible from some global function pointer.
@@ -128,28 +130,28 @@ which will be introduced in the next section.)
3.2. IRQ Structure
-Basically, a IRQ runs the following pseudo code:
+Basically, a IRQ runs the following pseudo code::
-for each hardware counter that triggered this overflow
+ for each hardware counter that triggered this overflow
- get the event of this counter
+ get the event of this counter
- // following two steps are defined as *read()*,
- // check the section Reading/Writing Counters for details.
- count the delta value since previous interrupt
- update the event->count (# event occurs) by adding delta, and
- event->hw.period_left by subtracting delta
+ // following two steps are defined as *read()*,
+ // check the section Reading/Writing Counters for details.
+ count the delta value since previous interrupt
+ update the event->count (# event occurs) by adding delta, and
+ event->hw.period_left by subtracting delta
- if the event overflows
- sample data
- set the counter appropriately for the next overflow
+ if the event overflows
+ sample data
+ set the counter appropriately for the next overflow
- if the event overflows again
- too frequently, throttle this event
- fi
- fi
+ if the event overflows again
+ too frequently, throttle this event
+ fi
+ fi
-end for
+ end for
However as of this writing, none of the RISC-V implementations have designed an
interrupt for perf, so the details are to be completed in the future.
@@ -195,23 +197,26 @@ A normal flow of these state transitions are as follows:
At this stage, a general event is bound to a physical counter, if any.
The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now
stopped, and the (software) event count does not need updating.
-** *start* is then called, and the counter is enabled.
- With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
- previous section for detail).
- Nothing is written if the flag does not contain PERF_EF_RELOAD.
- The state now is reset to none, because it is neither stopped nor updated
- (the counting already started)
+
+ - *start* is then called, and the counter is enabled.
+ With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
+ previous section for detail).
+ Nothing is written if the flag does not contain PERF_EF_RELOAD.
+ The state now is reset to none, because it is neither stopped nor updated
+ (the counting already started)
+
* When being context-switched out, *del* is called. It then checks out all the
events in the PMU and calls *stop* to update their counts.
-** *stop* is called by *del*
- and the perf core with flag PERF_EF_UPDATE, and it often shares the same
- subroutine as *read* with the same logic.
- The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
-** Life cycle of these two pairs: *add* and *del* are called repeatedly as
- tasks switch in-and-out; *start* and *stop* is also called when the perf core
- needs a quick stop-and-start, for instance, when the interrupt period is being
- adjusted.
+ - *stop* is called by *del*
+ and the perf core with flag PERF_EF_UPDATE, and it often shares the same
+ subroutine as *read* with the same logic.
+ The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
+
+ - Life cycle of these two pairs: *add* and *del* are called repeatedly as
+ tasks switch in-and-out; *start* and *stop* is also called when the perf core
+ needs a quick stop-and-start, for instance, when the interrupt period is being
+ adjusted.
Current implementation is sufficient for now and can be easily extended to
features in the future.
@@ -225,25 +230,26 @@ A. Related Structures
Both structures are designed to be read-only.
*struct pmu* defines some function pointer interfaces, and most of them take
-*struct perf_event* as a main argument, dealing with perf events according to
-perf's internal state machine (check kernel/events/core.c for details).
+ *struct perf_event* as a main argument, dealing with perf events according to
+ perf's internal state machine (check kernel/events/core.c for details).
*struct riscv_pmu* defines PMU-specific parameters. The naming follows the
-convention of all other architectures.
+ convention of all other architectures.
* struct perf_event: include/linux/perf_event.h
* struct hw_perf_event
The generic structure that represents perf events, and the hardware-related
-details.
+ details.
* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h
The structure that holds the status of events, has two fixed members:
-the number of events and the array of the events.
+ the number of events and the array of the events.
References
----------
[1] https://github.com/riscv/riscv-linux/pull/124
+
[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 23/28] docs: target: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (15 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 22/28] docs: riscv: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-19 3:38 ` Martin K. Petersen
2019-06-12 17:53 ` [PATCH v4 24/28] docs: timers: " Mauro Carvalho Chehab
` (7 subsequent siblings)
24 siblings, 1 reply; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Martin K. Petersen, linux-scsi, target-devel
Convert the TCM docs to ReST format and add them to the
bookset.
This has a mix of userspace-faced and Kernelspace faced
docs. Still, it sounds a better candidate to be added at
the kernel API set of docs.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/target/index.rst | 19 ++
Documentation/target/scripts.rst | 11 +
Documentation/target/tcm_mod_builder.rst | 149 ++++++++++
Documentation/target/tcm_mod_builder.txt | 145 ----------
.../{tcmu-design.txt => tcmu-design.rst} | 268 ++++++++++--------
scripts/documentation-file-ref-check | 2 +-
6 files changed, 326 insertions(+), 268 deletions(-)
create mode 100644 Documentation/target/index.rst
create mode 100644 Documentation/target/scripts.rst
create mode 100644 Documentation/target/tcm_mod_builder.rst
delete mode 100644 Documentation/target/tcm_mod_builder.txt
rename Documentation/target/{tcmu-design.txt => tcmu-design.rst} (69%)
diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst
new file mode 100644
index 000000000000..b68f48982392
--- /dev/null
+++ b/Documentation/target/index.rst
@@ -0,0 +1,19 @@
+:orphan:
+
+==================
+TCM Virtual Device
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ tcmu-design
+ tcm_mod_builder
+ scripts
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/target/scripts.rst b/Documentation/target/scripts.rst
new file mode 100644
index 000000000000..172d42b522e4
--- /dev/null
+++ b/Documentation/target/scripts.rst
@@ -0,0 +1,11 @@
+TCM mod builder script
+----------------------
+
+.. literalinclude:: tcm_mod_builder.py
+ :language: perl
+
+Target export device script
+---------------------------
+
+.. literalinclude:: target-export-device
+ :language: shell
diff --git a/Documentation/target/tcm_mod_builder.rst b/Documentation/target/tcm_mod_builder.rst
new file mode 100644
index 000000000000..9bfc9822e2bd
--- /dev/null
+++ b/Documentation/target/tcm_mod_builder.rst
@@ -0,0 +1,149 @@
+=========================================
+The TCM v4 fabric module script generator
+=========================================
+
+Greetings all,
+
+This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
+script to generate a brand new functional TCM v4 fabric .ko module of your very own,
+that once built can be immediately be loaded to start access the new TCM/ConfigFS
+fabric skeleton, by simply using::
+
+ modprobe $TCM_NEW_MOD
+ mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
+
+This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
+
+ 1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
+ ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
+ into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
+ 2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
+ using a skeleton struct target_core_fabric_ops API template.
+ 3) Based on user defined T10 Proto_Ident for the new fabric module being built,
+ the TransportID / Initiator and Target WWPN related handlers for
+ SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
+ using drivers/target/target_core_fabric_lib.c logic.
+ 4) NOP API calls for all other Data I/O path and fabric dependent attribute logic
+ in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
+
+tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
+$FABRIC_MOD_name' parameters, and actually running the script looks like::
+
+ target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
+ tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
+ Set fabric_mod_name: tcm_nab5000
+ Set fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Using proto_ident: iSCSI
+ Creating fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
+ Using tcm_mod_scan_fabric_ops:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
+ Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
+ Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
+
+At the end of tcm_mod_builder.py. the script will ask to add the following
+line to drivers/target/Kbuild::
+
+ obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
+
+and the same for drivers/target/Kconfig::
+
+ source "drivers/target/tcm_nab5000/Kconfig"
+
+#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item::
+
+ <M> TCM_NAB5000 fabric module
+
+#) Build using 'make modules', once completed you will have::
+
+ target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
+ total 1348
+ drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
+ drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
+ -rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
+ -rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
+ -rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
+ -rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
+ -rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
+ -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
+ -rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
+ -rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
+ -rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
+ -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
+ -rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
+ -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
+ -rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
+ -rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
+ -rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
+ -rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
+ -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
+ -rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
+
+#) Load the new module, create a lun_0 configfs group, and add new TCM Core
+ IBLOCK backstore symlink to port::
+
+ target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
+ target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
+ target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
+
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
+ target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
+ /sys/kernel/config/target/nab5000/
+ |-- discovery_auth
+ |-- iqn.foo
+ | `-- tpgt_1
+ | |-- acls
+ | |-- attrib
+ | |-- lun
+ | | `-- lun_0
+ | | |-- alua_tg_pt_gp
+ | | |-- alua_tg_pt_offline
+ | | |-- alua_tg_pt_status
+ | | |-- alua_tg_pt_write_md
+ | | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
+ | |-- np
+ | `-- param
+ `-- version
+
+ target:/mnt/sdb/lio-core-2.6.git# lsmod
+ Module Size Used by
+ tcm_nab5000 3935 4
+ iscsi_target_mod 193211 0
+ target_core_stgt 8090 0
+ target_core_pscsi 11122 1
+ target_core_file 9172 2
+ target_core_iblock 9280 1
+ target_core_mod 228575 31
+ tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
+ libfc 73681 0
+ scsi_debug 56265 0
+ scsi_tgt 8666 1 target_core_stgt
+ configfs 20644 2 target_core_mod
+
+----------------------------------------------------------------------
+
+Future TODO items
+=================
+
+ 1) Add more T10 proto_idents
+ 2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
+ defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
+ structure members.
+
+October 5th, 2010
+
+Nicholas A. Bellinger <nab@linux-iscsi.org>
diff --git a/Documentation/target/tcm_mod_builder.txt b/Documentation/target/tcm_mod_builder.txt
deleted file mode 100644
index ae22f7005540..000000000000
--- a/Documentation/target/tcm_mod_builder.txt
+++ /dev/null
@@ -1,145 +0,0 @@
->>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<<
-
-Greetings all,
-
-This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
-script to generate a brand new functional TCM v4 fabric .ko module of your very own,
-that once built can be immediately be loaded to start access the new TCM/ConfigFS
-fabric skeleton, by simply using:
-
- modprobe $TCM_NEW_MOD
- mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
-
-This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
-
- *) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
- ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
- into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
- *) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
- using a skeleton struct target_core_fabric_ops API template.
- *) Based on user defined T10 Proto_Ident for the new fabric module being built,
- the TransportID / Initiator and Target WWPN related handlers for
- SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
- using drivers/target/target_core_fabric_lib.c logic.
- *) NOP API calls for all other Data I/O path and fabric dependent attribute logic
- in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
-
-tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
-$FABRIC_MOD_name' parameters, and actually running the script looks like:
-
-target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
-tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
-Set fabric_mod_name: tcm_nab5000
-Set fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Using proto_ident: iSCSI
-Creating fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
-Using tcm_mod_scan_fabric_ops:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
-Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
-Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
-
-At the end of tcm_mod_builder.py. the script will ask to add the following
-line to drivers/target/Kbuild:
-
- obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
-
-and the same for drivers/target/Kconfig:
-
- source "drivers/target/tcm_nab5000/Kconfig"
-
-*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:
-
- <M> TCM_NAB5000 fabric module
-
-*) Build using 'make modules', once completed you will have:
-
-target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
-total 1348
-drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
-drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
--rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
--rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
--rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
--rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
--rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
--rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
--rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
--rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
--rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
--rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
--rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
--rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
--rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
--rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
--rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
--rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
--rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
--rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
-
-*) Load the new module, create a lun_0 configfs group, and add new TCM Core
- IBLOCK backstore symlink to port:
-
-target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
-target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
-target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
-
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
-target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
-/sys/kernel/config/target/nab5000/
-|-- discovery_auth
-|-- iqn.foo
-| `-- tpgt_1
-| |-- acls
-| |-- attrib
-| |-- lun
-| | `-- lun_0
-| | |-- alua_tg_pt_gp
-| | |-- alua_tg_pt_offline
-| | |-- alua_tg_pt_status
-| | |-- alua_tg_pt_write_md
-| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
-| |-- np
-| `-- param
-`-- version
-
-target:/mnt/sdb/lio-core-2.6.git# lsmod
-Module Size Used by
-tcm_nab5000 3935 4
-iscsi_target_mod 193211 0
-target_core_stgt 8090 0
-target_core_pscsi 11122 1
-target_core_file 9172 2
-target_core_iblock 9280 1
-target_core_mod 228575 31
-tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
-libfc 73681 0
-scsi_debug 56265 0
-scsi_tgt 8666 1 target_core_stgt
-configfs 20644 2 target_core_mod
-
-----------------------------------------------------------------------
-
-Future TODO items:
-
- *) Add more T10 proto_idents
- *) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
- defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
- structure members.
-
-October 5th, 2010
-Nicholas A. Bellinger <nab@linux-iscsi.org>
diff --git a/Documentation/target/tcmu-design.txt b/Documentation/target/tcmu-design.rst
similarity index 69%
rename from Documentation/target/tcmu-design.txt
rename to Documentation/target/tcmu-design.rst
index 4cebc1ebf99a..a7b426707bf6 100644
--- a/Documentation/target/tcmu-design.txt
+++ b/Documentation/target/tcmu-design.rst
@@ -1,25 +1,30 @@
-Contents:
+====================
+TCM Userspace Design
+====================
+
+
+.. Contents:
-1) TCM Userspace Design
- a) Background
- b) Benefits
- c) Design constraints
- d) Implementation overview
- i. Mailbox
- ii. Command ring
- iii. Data Area
- e) Device discovery
- f) Device events
- g) Other contingencies
-2) Writing a user pass-through handler
- a) Discovering and configuring TCMU uio devices
- b) Waiting for events on the device(s)
- c) Managing the command ring
-3) A final note
+ 1) TCM Userspace Design
+ a) Background
+ b) Benefits
+ c) Design constraints
+ d) Implementation overview
+ i. Mailbox
+ ii. Command ring
+ iii. Data Area
+ e) Device discovery
+ f) Device events
+ g) Other contingencies
+ 2) Writing a user pass-through handler
+ a) Discovering and configuring TCMU uio devices
+ b) Waiting for events on the device(s)
+ c) Managing the command ring
+ 3) A final note
TCM Userspace Design
---------------------
+====================
TCM is another name for LIO, an in-kernel iSCSI target (server).
Existing TCM targets run in the kernel. TCMU (TCM in Userspace)
@@ -32,7 +37,8 @@ modules for file, block device, RAM or using another SCSI device as
storage. These are called "backstores" or "storage engines". These
built-in modules are implemented entirely as kernel code.
-Background:
+Background
+----------
In addition to modularizing the transport protocol used for carrying
SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes
@@ -60,7 +66,8 @@ kernel, another approach is to create a userspace pass-through
backstore for LIO, "TCMU".
-Benefits:
+Benefits
+--------
In addition to allowing relatively easy support for RBD and GLFS, TCMU
will also allow easier development of new backstores. TCMU combines
@@ -72,21 +79,25 @@ The disadvantage is there are more distinct components to configure, and
potentially to malfunction. This is unavoidable, but hopefully not
fatal if we're careful to keep things as simple as possible.
-Design constraints:
+Design constraints
+------------------
- Good performance: high throughput, low latency
- Cleanly handle if userspace:
+
1) never attaches
2) hangs
3) dies
4) misbehaves
+
- Allow future flexibility in user & kernel implementations
- Be reasonably memory-efficient
- Simple to configure & run
- Simple to write a userspace backend
-Implementation overview:
+Implementation overview
+-----------------------
The core of the TCMU interface is a memory region that is shared
between kernel and userspace. Within this region is: a control area
@@ -108,7 +119,8 @@ the region mapped at a different virtual address.
See target_core_user.h for the struct definitions.
-The Mailbox:
+The Mailbox
+-----------
The mailbox is always at the start of the shared memory region, and
contains a version, details about the starting offset and size of the
@@ -117,19 +129,27 @@ userspace (respectively) to put commands on the ring, and indicate
when the commands are completed.
version - 1 (userspace should abort if otherwise)
+
flags:
-- TCMU_MAILBOX_FLAG_CAP_OOOC: indicates out-of-order completion is
- supported. See "The Command Ring" for details.
-cmdr_off - The offset of the start of the command ring from the start
-of the memory region, to account for the mailbox size.
-cmdr_size - The size of the command ring. This does *not* need to be a
-power of two.
-cmd_head - Modified by the kernel to indicate when a command has been
-placed on the ring.
-cmd_tail - Modified by userspace to indicate when it has completed
-processing of a command.
+ - TCMU_MAILBOX_FLAG_CAP_OOOC:
+ indicates out-of-order completion is supported.
+ See "The Command Ring" for details.
-The Command Ring:
+cmdr_off
+ The offset of the start of the command ring from the start
+ of the memory region, to account for the mailbox size.
+cmdr_size
+ The size of the command ring. This does *not* need to be a
+ power of two.
+cmd_head
+ Modified by the kernel to indicate when a command has been
+ placed on the ring.
+cmd_tail
+ Modified by userspace to indicate when it has completed
+ processing of a command.
+
+The Command Ring
+----------------
Commands are placed on the ring by the kernel incrementing
mailbox.cmd_head by the size of the command, modulo cmdr_size, and
@@ -180,29 +200,31 @@ opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in
hdr.uflags, update cmd_tail, and proceed with processing additional
commands, if any.
-The Data Area:
+The Data Area
+-------------
This is shared-memory space after the command ring. The organization
of this area is not defined in the TCMU interface, and userspace
should access only the parts referenced by pending iovs.
-Device Discovery:
+Device Discovery
+----------------
Other devices may be using UIO besides TCMU. Unrelated user processes
may also be handling different sets of TCMU devices. TCMU userspace
processes must find their devices by scanning sysfs
class/uio/uio*/name. For TCMU devices, these names will be of the
-format:
+format::
-tcm-user/<hba_num>/<device_name>/<subtype>/<path>
+ tcm-user/<hba_num>/<device_name>/<subtype>/<path>
where "tcm-user" is common for all TCMU-backed UIO devices. <hba_num>
and <device_name> allow userspace to find the device's path in the
kernel target's configfs tree. Assuming the usual mount point, it is
-found at:
+found at::
-/sys/kernel/config/target/core/user_<hba_num>/<device_name>
+ /sys/kernel/config/target/core/user_<hba_num>/<device_name>
This location contains attributes such as "hw_block_size", that
userspace needs to know for correct operation.
@@ -214,15 +236,16 @@ configure the device, if needed. The name cannot contain ':', due to
LIO limitations.
For all devices so discovered, the user handler opens /dev/uioX and
-calls mmap():
+calls mmap()::
-mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
+ mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
where size must be equal to the value read from
/sys/class/uio/uioX/maps/map0/size.
-Device Events:
+Device Events
+-------------
If a new device is added or removed, a notification will be broadcast
over netlink, using a generic netlink family name of "TCM-USER" and a
@@ -233,7 +256,8 @@ the LIO device, so that after determining the device is supported
(based on subtype) it can take the appropriate action.
-Other contingencies:
+Other contingencies
+-------------------
Userspace handler process never attaches:
@@ -258,7 +282,7 @@ Userspace handler process is malicious:
Writing a user pass-through handler (with example code)
--------------------------------------------------------
+=======================================================
A user process handing a TCMU device must support the following:
@@ -277,103 +301,103 @@ TCMU is designed so that multiple unrelated processes can manage TCMU
devices separately. All handlers should make sure to only open their
devices, based opon a known subtype string.
-a) Discovering and configuring TCMU UIO devices:
+a) Discovering and configuring TCMU UIO devices::
-(error checking omitted for brevity)
+ /* error checking omitted for brevity */
-int fd, dev_fd;
-char buf[256];
-unsigned long long map_len;
-void *map;
+ int fd, dev_fd;
+ char buf[256];
+ unsigned long long map_len;
+ void *map;
-fd = open("/sys/class/uio/uio0/name", O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open("/sys/class/uio/uio0/name", O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-/* we only want uio devices whose name is a format we expect */
-if (strncmp(buf, "tcm-user", 8))
+ /* we only want uio devices whose name is a format we expect */
+ if (strncmp(buf, "tcm-user", 8))
exit(-1);
-/* Further checking for subtype also needed here */
+ /* Further checking for subtype also needed here */
-fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-map_len = strtoull(buf, NULL, 0);
+ map_len = strtoull(buf, NULL, 0);
-dev_fd = open("/dev/uio0", O_RDWR);
-map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
+ dev_fd = open("/dev/uio0", O_RDWR);
+ map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
-b) Waiting for events on the device(s)
+ b) Waiting for events on the device(s)
-while (1) {
- char buf[4];
+ while (1) {
+ char buf[4];
- int ret = read(dev_fd, buf, 4); /* will block */
+ int ret = read(dev_fd, buf, 4); /* will block */
- handle_device_events(dev_fd, map);
-}
-
-
-c) Managing the command ring
-
-#include <linux/target_core_user.h>
-
-int handle_device_events(int fd, void *map)
-{
- struct tcmu_mailbox *mb = map;
- struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- int did_some_work = 0;
-
- /* Process events from cmd ring until we catch up with cmd_head */
- while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
-
- if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
- uint8_t *cdb = (void *)mb + ent->req.cdb_off;
- bool success = true;
+ handle_device_events(dev_fd, map);
+ }
- /* Handle command here. */
- printf("SCSI opcode: 0x%x\n", cdb[0]);
- /* Set response fields */
- if (success)
- ent->rsp.scsi_status = SCSI_NO_SENSE;
- else {
- /* Also fill in rsp->sense_buffer here */
- ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+c) Managing the command ring::
+
+ #include <linux/target_core_user.h>
+
+ int handle_device_events(int fd, void *map)
+ {
+ struct tcmu_mailbox *mb = map;
+ struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ int did_some_work = 0;
+
+ /* Process events from cmd ring until we catch up with cmd_head */
+ while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
+
+ if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
+ uint8_t *cdb = (void *)mb + ent->req.cdb_off;
+ bool success = true;
+
+ /* Handle command here. */
+ printf("SCSI opcode: 0x%x\n", cdb[0]);
+
+ /* Set response fields */
+ if (success)
+ ent->rsp.scsi_status = SCSI_NO_SENSE;
+ else {
+ /* Also fill in rsp->sense_buffer here */
+ ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+ }
+ }
+ else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
+ /* Tell the kernel we didn't handle unknown opcodes */
+ ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
+ }
+ else {
+ /* Do nothing for PAD entries except update cmd_tail */
+ }
+
+ /* update cmd_tail */
+ mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
+ ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ did_some_work = 1;
+ }
+
+ /* Notify the kernel that work has been finished */
+ if (did_some_work) {
+ uint32_t buf = 0;
+
+ write(fd, &buf, 4);
+ }
+
+ return 0;
}
- }
- else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
- /* Tell the kernel we didn't handle unknown opcodes */
- ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
- }
- else {
- /* Do nothing for PAD entries except update cmd_tail */
- }
-
- /* update cmd_tail */
- mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
- ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- did_some_work = 1;
- }
-
- /* Notify the kernel that work has been finished */
- if (did_some_work) {
- uint32_t buf = 0;
-
- write(fd, &buf, 4);
- }
-
- return 0;
-}
A final note
-------------
+============
Please be careful to return codes as defined by the SCSI
specifications. These are different than some values defined in the
diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check
index 440227bb55a9..a4139a576726 100755
--- a/scripts/documentation-file-ref-check
+++ b/scripts/documentation-file-ref-check
@@ -124,7 +124,7 @@ while (<IN>) {
# Remove sched-pelt false-positive
next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
- # Discard some build examples from Documentation/target/tcm_mod_builder.txt
+ # Discard some build examples from Documentation/target/tcm_mod_builder.rst
next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
# Check if exists, evaluating wildcards
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 24/28] docs: timers: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (16 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 23/28] docs: target: " Mauro Carvalho Chehab
@ 2019-06-12 17:53 ` Mauro Carvalho Chehab
2019-06-12 18:25 ` Mark Brown
2019-06-12 17:53 ` [PATCH v4 25/28] docs: watchdog: " Mauro Carvalho Chehab
` (6 subsequent siblings)
24 siblings, 1 reply; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:53 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Thomas Gleixner, Clemens Ladisch,
Antti Palosaari, Liam Girdwood, Mark Brown, Andy Whitcroft,
Joe Perches, Jaroslav Kysela, Takashi Iwai, alsa-devel
The conversion here is really trivial: just a bunch of title
markups and very few puntual changes is enough to make it to
be parsed by Sphinx and generate a nice html.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../timers/{highres.txt => highres.rst} | 13 +++---
Documentation/timers/{hpet.txt => hpet.rst} | 4 +-
.../timers/{hrtimers.txt => hrtimers.rst} | 6 +--
Documentation/timers/index.rst | 22 ++++++++++
Documentation/timers/{NO_HZ.txt => no_hz.rst} | 40 +++++++++++--------
.../{timekeeping.txt => timekeeping.rst} | 3 +-
.../{timers-howto.txt => timers-howto.rst} | 15 +++++--
MAINTAINERS | 2 +-
drivers/media/usb/dvb-usb-v2/anysee.c | 2 +-
drivers/regulator/core.c | 2 +-
include/linux/iopoll.h | 4 +-
include/linux/regmap.h | 4 +-
scripts/checkpatch.pl | 8 ++--
sound/soc/sof/ops.h | 2 +-
14 files changed, 84 insertions(+), 43 deletions(-)
rename Documentation/timers/{highres.txt => highres.rst} (98%)
rename Documentation/timers/{hpet.txt => hpet.rst} (91%)
rename Documentation/timers/{hrtimers.txt => hrtimers.rst} (98%)
create mode 100644 Documentation/timers/index.rst
rename Documentation/timers/{NO_HZ.txt => no_hz.rst} (93%)
rename Documentation/timers/{timekeeping.txt => timekeeping.rst} (98%)
rename Documentation/timers/{timers-howto.txt => timers-howto.rst} (93%)
diff --git a/Documentation/timers/highres.txt b/Documentation/timers/highres.rst
similarity index 98%
rename from Documentation/timers/highres.txt
rename to Documentation/timers/highres.rst
index 8f9741592123..bde5eb7e5c9e 100644
--- a/Documentation/timers/highres.txt
+++ b/Documentation/timers/highres.rst
@@ -1,5 +1,6 @@
+=====================================================
High resolution timers and dynamic ticks design notes
------------------------------------------------------
+=====================================================
Further information can be found in the paper of the OLS 2006 talk "hrtimers
and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
@@ -30,11 +31,12 @@ hrtimer base infrastructure
---------------------------
The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of
-the base implementation are covered in Documentation/timers/hrtimers.txt. See
+the base implementation are covered in Documentation/timers/hrtimers.rst. See
also figure #2 (OLS slides p. 15)
The main differences to the timer wheel, which holds the armed timer_list type
timers are:
+
- time ordered enqueueing into a rb-tree
- independent of ticks (the processing is based on nanoseconds)
@@ -55,7 +57,8 @@ merged into the 2.6.18 kernel.
Further information about the Generic Time Of Day framework is available in the
OLS 2005 Proceedings Volume 1:
-http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
+
+ http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
The paper "We Are Not Getting Any Younger: A New Approach to Time and
Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.
@@ -100,6 +103,7 @@ accounting, profiling, and high resolution timers.
The management layer assigns one or more of the following functions to a clock
event device:
+
- system global periodic tick (jiffies update)
- cpu local update_process_times
- cpu local profiling
@@ -244,6 +248,3 @@ extended to x86_64 and ARM already. Initial (work in progress) support is also
available for MIPS and PowerPC.
Thomas, Ingo
-
-
-
diff --git a/Documentation/timers/hpet.txt b/Documentation/timers/hpet.rst
similarity index 91%
rename from Documentation/timers/hpet.txt
rename to Documentation/timers/hpet.rst
index 895345ec513b..c9d05d3caaca 100644
--- a/Documentation/timers/hpet.txt
+++ b/Documentation/timers/hpet.rst
@@ -1,4 +1,6 @@
- High Precision Event Timer Driver for Linux
+===========================================
+High Precision Event Timer Driver for Linux
+===========================================
The High Precision Event Timer (HPET) hardware follows a specification
by Intel and Microsoft, revision 1.
diff --git a/Documentation/timers/hrtimers.txt b/Documentation/timers/hrtimers.rst
similarity index 98%
rename from Documentation/timers/hrtimers.txt
rename to Documentation/timers/hrtimers.rst
index 588d85724f10..c1c20a693e8f 100644
--- a/Documentation/timers/hrtimers.txt
+++ b/Documentation/timers/hrtimers.rst
@@ -1,6 +1,6 @@
-
+======================================================
hrtimers - subsystem for high-resolution kernel timers
-----------------------------------------------------
+======================================================
This patch introduces a new subsystem for high-resolution kernel timers.
@@ -146,7 +146,7 @@ the clock_getres() interface. This will return whatever real resolution
a given clock has - be it low-res, high-res, or artificially-low-res.
hrtimers - testing and verification
-----------------------------------
+-----------------------------------
We used the high-resolution clock subsystem ontop of hrtimers to verify
the hrtimer implementation details in praxis, and we also ran the posix
diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst
new file mode 100644
index 000000000000..91f6f8263c48
--- /dev/null
+++ b/Documentation/timers/index.rst
@@ -0,0 +1,22 @@
+:orphan:
+
+======
+timers
+======
+
+.. toctree::
+ :maxdepth: 1
+
+ highres
+ hpet
+ hrtimers
+ no_hz
+ timekeeping
+ timers-howto
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/timers/NO_HZ.txt b/Documentation/timers/no_hz.rst
similarity index 93%
rename from Documentation/timers/NO_HZ.txt
rename to Documentation/timers/no_hz.rst
index 9591092da5e0..065db217cb04 100644
--- a/Documentation/timers/NO_HZ.txt
+++ b/Documentation/timers/no_hz.rst
@@ -1,4 +1,6 @@
- NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
+NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
This document describes Kconfig options and boot parameters that can
@@ -28,7 +30,8 @@ by a third section on RCU-specific considerations, a fourth section
discussing testing, and a fifth and final section listing known issues.
-NEVER OMIT SCHEDULING-CLOCK TICKS
+Never Omit Scheduling-Clock Ticks
+=================================
Very old versions of Linux from the 1990s and the very early 2000s
are incapable of omitting scheduling-clock ticks. It turns out that
@@ -59,7 +62,8 @@ degrade your applications performance. If this describes your workload,
you should read the following two sections.
-OMIT SCHEDULING-CLOCK TICKS FOR IDLE CPUs
+Omit Scheduling-Clock Ticks For Idle CPUs
+=========================================
If a CPU is idle, there is little point in sending it a scheduling-clock
interrupt. After all, the primary purpose of a scheduling-clock interrupt
@@ -97,7 +101,8 @@ By default, CONFIG_NO_HZ_IDLE=y kernels boot with "nohz=on", enabling
dyntick-idle mode.
-OMIT SCHEDULING-CLOCK TICKS FOR CPUs WITH ONLY ONE RUNNABLE TASK
+Omit Scheduling-Clock Ticks For CPUs With Only One Runnable Task
+================================================================
If a CPU has only one runnable task, there is little point in sending it
a scheduling-clock interrupt because there is no other task to switch to.
@@ -174,7 +179,8 @@ However, the drawbacks listed above mean that adaptive ticks should not
(yet) be enabled by default.
-RCU IMPLICATIONS
+RCU Implications
+================
There are situations in which idle CPUs cannot be permitted to
enter either dyntick-idle mode or adaptive-tick mode, the most
@@ -199,7 +205,8 @@ scheduler will decide where to run them, which might or might not be
where you want them to run.
-TESTING
+Testing
+=======
So you enable all the OS-jitter features described in this document,
but do not see any change in your workload's behavior. Is this because
@@ -222,9 +229,10 @@ We do not currently have a good way to remove OS jitter from single-CPU
systems.
-KNOWN ISSUES
+Known Issues
+============
-o Dyntick-idle slows transitions to and from idle slightly.
+* Dyntick-idle slows transitions to and from idle slightly.
In practice, this has not been a problem except for the most
aggressive real-time workloads, which have the option of disabling
dyntick-idle mode, an option that most of them take. However,
@@ -248,13 +256,13 @@ o Dyntick-idle slows transitions to and from idle slightly.
this parameter effectively disables Turbo Mode on Intel
CPUs, which can significantly reduce maximum performance.
-o Adaptive-ticks slows user/kernel transitions slightly.
+* Adaptive-ticks slows user/kernel transitions slightly.
This is not expected to be a problem for computationally intensive
workloads, which have few such transitions. Careful benchmarking
will be required to determine whether or not other workloads
are significantly affected by this effect.
-o Adaptive-ticks does not do anything unless there is only one
+* Adaptive-ticks does not do anything unless there is only one
runnable task for a given CPU, even though there are a number
of other situations where the scheduling-clock tick is not
needed. To give but one example, consider a CPU that has one
@@ -275,7 +283,7 @@ o Adaptive-ticks does not do anything unless there is only one
Better handling of these sorts of situations is future work.
-o A reboot is required to reconfigure both adaptive idle and RCU
+* A reboot is required to reconfigure both adaptive idle and RCU
callback offloading. Runtime reconfiguration could be provided
if needed, however, due to the complexity of reconfiguring RCU at
runtime, there would need to be an earthshakingly good reason.
@@ -283,12 +291,12 @@ o A reboot is required to reconfigure both adaptive idle and RCU
simply offloading RCU callbacks from all CPUs and pinning them
where you want them whenever you want them pinned.
-o Additional configuration is required to deal with other sources
+* Additional configuration is required to deal with other sources
of OS jitter, including interrupts and system-utility tasks
and processes. This configuration normally involves binding
interrupts and tasks to particular CPUs.
-o Some sources of OS jitter can currently be eliminated only by
+* Some sources of OS jitter can currently be eliminated only by
constraining the workload. For example, the only way to eliminate
OS jitter due to global TLB shootdowns is to avoid the unmapping
operations (such as kernel module unload operations) that
@@ -299,17 +307,17 @@ o Some sources of OS jitter can currently be eliminated only by
helpful, especially when combined with the mlock() and mlockall()
system calls.
-o Unless all CPUs are idle, at least one CPU must keep the
+* Unless all CPUs are idle, at least one CPU must keep the
scheduling-clock interrupt going in order to support accurate
timekeeping.
-o If there might potentially be some adaptive-ticks CPUs, there
+* If there might potentially be some adaptive-ticks CPUs, there
will be at least one CPU keeping the scheduling-clock interrupt
going, even if all CPUs are otherwise idle.
Better handling of this situation is ongoing work.
-o Some process-handling operations still require the occasional
+* Some process-handling operations still require the occasional
scheduling-clock tick. These operations include calculating CPU
load, maintaining sched average, computing CFS entity vruntime,
computing avenrun, and carrying out load balancing. They are
diff --git a/Documentation/timers/timekeeping.txt b/Documentation/timers/timekeeping.rst
similarity index 98%
rename from Documentation/timers/timekeeping.txt
rename to Documentation/timers/timekeeping.rst
index 2d1732b0a868..f83e98852e2c 100644
--- a/Documentation/timers/timekeeping.txt
+++ b/Documentation/timers/timekeeping.rst
@@ -1,5 +1,6 @@
+===========================================================
Clock sources, Clock events, sched_clock() and delay timers
------------------------------------------------------------
+===========================================================
This document tries to briefly explain some basic kernel timekeeping
abstractions. It partly pertains to the drivers usually found in
diff --git a/Documentation/timers/timers-howto.txt b/Documentation/timers/timers-howto.rst
similarity index 93%
rename from Documentation/timers/timers-howto.txt
rename to Documentation/timers/timers-howto.rst
index 038f8c77a076..7e3167bec2b1 100644
--- a/Documentation/timers/timers-howto.txt
+++ b/Documentation/timers/timers-howto.rst
@@ -1,5 +1,6 @@
+===================================================================
delays - Information on the various kernel delay / sleep mechanisms
--------------------------------------------------------------------
+===================================================================
This document seeks to answer the common question: "What is the
RightWay (TM) to insert a delay?"
@@ -17,7 +18,7 @@ code in an atomic context?" This should be followed closely by "Does
it really need to delay in atomic context?" If so...
ATOMIC CONTEXT:
- You must use the *delay family of functions. These
+ You must use the `*delay` family of functions. These
functions use the jiffie estimation of clock speed
and will busy wait for enough loop cycles to achieve
the desired delay:
@@ -35,21 +36,26 @@ ATOMIC CONTEXT:
be refactored to allow for the use of msleep.
NON-ATOMIC CONTEXT:
- You should use the *sleep[_range] family of functions.
+ You should use the `*sleep[_range]` family of functions.
There are a few more options here, while any of them may
work correctly, using the "right" sleep function will
help the scheduler, power management, and just make your
driver better :)
-- Backed by busy-wait loop:
+
udelay(unsigned long usecs)
+
-- Backed by hrtimers:
+
usleep_range(unsigned long min, unsigned long max)
+
-- Backed by jiffies / legacy_timers
+
msleep(unsigned long msecs)
msleep_interruptible(unsigned long msecs)
- Unlike the *delay family, the underlying mechanism
+ Unlike the `*delay` family, the underlying mechanism
driving each of these calls varies, thus there are
quirks you should be aware of.
@@ -70,6 +76,7 @@ NON-ATOMIC CONTEXT:
- Why not msleep for (1ms - 20ms)?
Explained originally here:
http://lkml.org/lkml/2007/8/3/250
+
msleep(1~20) may not do what the caller intends, and
will often sleep longer (~20 ms actual sleep for any
value given in the 1~20ms range). In many cases this
diff --git a/MAINTAINERS b/MAINTAINERS
index 9d9399c9cf47..71b4754ea7c3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7223,7 +7223,7 @@ F: drivers/net/ethernet/hp/hp100.*
HPET: High Precision Event Timers driver
M: Clemens Ladisch <clemens@ladisch.de>
S: Maintained
-F: Documentation/timers/hpet.txt
+F: Documentation/timers/hpet.rst
F: drivers/char/hpet.c
F: include/linux/hpet.h
F: include/uapi/linux/hpet.h
diff --git a/drivers/media/usb/dvb-usb-v2/anysee.c b/drivers/media/usb/dvb-usb-v2/anysee.c
index 48fb0d41e03b..fb6d99dea31a 100644
--- a/drivers/media/usb/dvb-usb-v2/anysee.c
+++ b/drivers/media/usb/dvb-usb-v2/anysee.c
@@ -56,7 +56,7 @@ static int anysee_ctrl_msg(struct dvb_usb_device *d,
/* TODO FIXME: dvb_usb_generic_rw() fails rarely with error code -32
* (EPIPE, Broken pipe). Function supports currently msleep() as a
* parameter but I would not like to use it, since according to
- * Documentation/timers/timers-howto.txt it should not be used such
+ * Documentation/timers/timers-howto.rst it should not be used such
* short, under < 20ms, sleeps. Repeating failed message would be
* better choice as not to add unwanted delays...
* Fixing that correctly is one of those or both;
diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index 85f61e5dc312..aff1f2cefe4b 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -2304,7 +2304,7 @@ static int regulator_ena_gpio_ctrl(struct regulator_dev *rdev, bool enable)
*
* Delay for the requested amount of time as per the guidelines in:
*
- * Documentation/timers/timers-howto.txt
+ * Documentation/timers/timers-howto.rst
*
* The assumption here is that regulators will never be enabled in
* atomic context and therefore sleeping functions can be used.
diff --git a/include/linux/iopoll.h b/include/linux/iopoll.h
index 3908353deec6..35e15dfd4155 100644
--- a/include/linux/iopoll.h
+++ b/include/linux/iopoll.h
@@ -21,7 +21,7 @@
* @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range
- * is used (see Documentation/timers/timers-howto.txt).
+ * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout
*
* Returns 0 on success and -ETIMEDOUT upon a timeout. In either
@@ -60,7 +60,7 @@
* @cond: Break condition (usually involving @val)
* @delay_us: Time to udelay between reads in us (0 tight-loops). Should
* be less than ~10us since udelay is used (see
- * Documentation/timers/timers-howto.txt).
+ * Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout
*
* Returns 0 on success and -ETIMEDOUT upon a timeout. In either
diff --git a/include/linux/regmap.h b/include/linux/regmap.h
index f65984d98b07..038568a9b957 100644
--- a/include/linux/regmap.h
+++ b/include/linux/regmap.h
@@ -113,7 +113,7 @@ struct reg_sequence {
* @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range
- * is used (see Documentation/timers/timers-howto.txt).
+ * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout
*
* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
@@ -155,7 +155,7 @@ struct reg_sequence {
* @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range
- * is used (see Documentation/timers/timers-howto.txt).
+ * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout
*
* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index c1be9f6958b7..6cb99ec62000 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -5714,7 +5714,7 @@ sub process {
# ignore udelay's < 10, however
if (! ($delay < 10) ) {
CHK("USLEEP_RANGE",
- "usleep_range is preferred over udelay; see Documentation/timers/timers-howto.txt\n" . $herecurr);
+ "usleep_range is preferred over udelay; see Documentation/timers/timers-howto.rst\n" . $herecurr);
}
if ($delay > 2000) {
WARN("LONG_UDELAY",
@@ -5726,7 +5726,7 @@ sub process {
if ($line =~ /\bmsleep\s*\((\d+)\);/) {
if ($1 < 20) {
WARN("MSLEEP",
- "msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.txt\n" . $herecurr);
+ "msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.rst\n" . $herecurr);
}
}
@@ -6117,11 +6117,11 @@ sub process {
my $max = $7;
if ($min eq $max) {
WARN("USLEEP_RANGE",
- "usleep_range should not use min == max args; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n");
+ "usleep_range should not use min == max args; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n");
} elsif ($min =~ /^\d+$/ && $max =~ /^\d+$/ &&
$min > $max) {
WARN("USLEEP_RANGE",
- "usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n");
+ "usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n");
}
}
diff --git a/sound/soc/sof/ops.h b/sound/soc/sof/ops.h
index 80fc3b374c2b..8058a6c73082 100644
--- a/sound/soc/sof/ops.h
+++ b/sound/soc/sof/ops.h
@@ -349,7 +349,7 @@ static inline const struct snd_sof_dsp_ops
* @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range
- * is used (see Documentation/timers/timers-howto.txt).
+ * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout
*
* Returns 0 on success and -ETIMEDOUT upon a timeout. In either
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 25/28] docs: watchdog: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (17 preceding siblings ...)
2019-06-12 17:53 ` [PATCH v4 24/28] docs: timers: " Mauro Carvalho Chehab
@ 2019-06-12 17:53 ` Mauro Carvalho Chehab
2019-06-12 17:53 ` [PATCH v4 26/28] docs: xilinx: convert eemi.txt to eemi.rst Mauro Carvalho Chehab
` (5 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:53 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Wim Van Sebroeck, Guenter Roeck, Jerry Hoemann,
linux-watchdog
Convert those documents and prepare them to be part of the kernel
API book, as most of the stuff there are related to the
Kernel interfaces.
Still, in the future, it would make sense to split the docs,
as some of the stuff is clearly focused on sysadmin tasks.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Guenter Roeck <linux@roeck-us.net>
---
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/kernel-per-CPU-kthreads.txt | 2 +-
....txt => convert_drivers_to_kernel_api.rst} | 109 +--
.../watchdog/{hpwdt.txt => hpwdt.rst} | 25 +-
Documentation/watchdog/index.rst | 25 +
.../watchdog/{mlx-wdt.txt => mlx-wdt.rst} | 24 +-
.../{pcwd-watchdog.txt => pcwd-watchdog.rst} | 13 +-
.../{watchdog-api.txt => watchdog-api.rst} | 76 +-
...kernel-api.txt => watchdog-kernel-api.rst} | 91 ++-
.../watchdog/watchdog-parameters.rst | 736 ++++++++++++++++++
.../watchdog/watchdog-parameters.txt | 410 ----------
.../{watchdog-pm.txt => watchdog-pm.rst} | 3 +
Documentation/watchdog/{wdt.txt => wdt.rst} | 31 +-
MAINTAINERS | 2 +-
drivers/watchdog/Kconfig | 6 +-
drivers/watchdog/smsc37b787_wdt.c | 2 +-
16 files changed, 1004 insertions(+), 553 deletions(-)
rename Documentation/watchdog/{convert_drivers_to_kernel_api.txt => convert_drivers_to_kernel_api.rst} (75%)
rename Documentation/watchdog/{hpwdt.txt => hpwdt.rst} (79%)
create mode 100644 Documentation/watchdog/index.rst
rename Documentation/watchdog/{mlx-wdt.txt => mlx-wdt.rst} (78%)
rename Documentation/watchdog/{pcwd-watchdog.txt => pcwd-watchdog.rst} (89%)
rename Documentation/watchdog/{watchdog-api.txt => watchdog-api.rst} (80%)
rename Documentation/watchdog/{watchdog-kernel-api.txt => watchdog-kernel-api.rst} (90%)
create mode 100644 Documentation/watchdog/watchdog-parameters.rst
delete mode 100644 Documentation/watchdog/watchdog-parameters.txt
rename Documentation/watchdog/{watchdog-pm.txt => watchdog-pm.rst} (92%)
rename Documentation/watchdog/{wdt.txt => wdt.rst} (68%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 0092a453f7dc..3d072ca532bb 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -5182,7 +5182,7 @@
Default: 3 = cyan.
watchdog timers [HW,WDT] For information on watchdog timers,
- see Documentation/watchdog/watchdog-parameters.txt
+ see Documentation/watchdog/watchdog-parameters.rst
or other driver-specific files in the
Documentation/watchdog/ directory.
diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.txt
index 23b0c8b20cd1..5623b9916411 100644
--- a/Documentation/kernel-per-CPU-kthreads.txt
+++ b/Documentation/kernel-per-CPU-kthreads.txt
@@ -348,7 +348,7 @@ To reduce its OS jitter, do at least one of the following:
2. Boot with "nosoftlockup=0", which will also prevent these kthreads
from being created. Other related watchdog and softlockup boot
parameters may be found in Documentation/admin-guide/kernel-parameters.rst
- and Documentation/watchdog/watchdog-parameters.txt.
+ and Documentation/watchdog/watchdog-parameters.rst.
3. Echo a zero to /proc/sys/kernel/watchdog to disable the
watchdog timer.
4. Echo a large number of /proc/sys/kernel/watchdog_thresh in
diff --git a/Documentation/watchdog/convert_drivers_to_kernel_api.txt b/Documentation/watchdog/convert_drivers_to_kernel_api.rst
similarity index 75%
rename from Documentation/watchdog/convert_drivers_to_kernel_api.txt
rename to Documentation/watchdog/convert_drivers_to_kernel_api.rst
index 9fffb2958d13..dd934cc08e40 100644
--- a/Documentation/watchdog/convert_drivers_to_kernel_api.txt
+++ b/Documentation/watchdog/convert_drivers_to_kernel_api.rst
@@ -1,6 +1,8 @@
+=========================================================
Converting old watchdog drivers to the watchdog framework
+=========================================================
+
by Wolfram Sang <w.sang@pengutronix.de>
-=========================================================
Before the watchdog framework came into the kernel, every driver had to
implement the API on its own. Now, as the framework factored out the common
@@ -69,16 +71,16 @@ Here is a overview of the functions and probably needed actions:
-ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error
is directly given to the user.
-Example conversion:
+Example conversion::
--static const struct file_operations s3c2410wdt_fops = {
-- .owner = THIS_MODULE,
-- .llseek = no_llseek,
-- .write = s3c2410wdt_write,
-- .unlocked_ioctl = s3c2410wdt_ioctl,
-- .open = s3c2410wdt_open,
-- .release = s3c2410wdt_release,
--};
+ -static const struct file_operations s3c2410wdt_fops = {
+ - .owner = THIS_MODULE,
+ - .llseek = no_llseek,
+ - .write = s3c2410wdt_write,
+ - .unlocked_ioctl = s3c2410wdt_ioctl,
+ - .open = s3c2410wdt_open,
+ - .release = s3c2410wdt_release,
+ -};
Check the functions for device-specific stuff and keep it for later
refactoring. The rest can go.
@@ -89,24 +91,24 @@ Remove the miscdevice
Since the file_operations are gone now, you can also remove the 'struct
miscdevice'. The framework will create it on watchdog_dev_register() called by
-watchdog_register_device().
+watchdog_register_device()::
--static struct miscdevice s3c2410wdt_miscdev = {
-- .minor = WATCHDOG_MINOR,
-- .name = "watchdog",
-- .fops = &s3c2410wdt_fops,
--};
+ -static struct miscdevice s3c2410wdt_miscdev = {
+ - .minor = WATCHDOG_MINOR,
+ - .name = "watchdog",
+ - .fops = &s3c2410wdt_fops,
+ -};
Remove obsolete includes and defines
------------------------------------
Because of the simplifications, a few defines are probably unused now. Remove
-them. Includes can be removed, too. For example:
+them. Includes can be removed, too. For example::
-- #include <linux/fs.h>
-- #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
-- #include <linux/uaccess.h> (if no custom IOCTLs are used)
+ - #include <linux/fs.h>
+ - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
+ - #include <linux/uaccess.h> (if no custom IOCTLs are used)
Add the watchdog operations
@@ -121,30 +123,30 @@ change the function header. Other changes are most likely not needed, because
here simply happens the direct hardware access. If you have device-specific
code left from the above steps, it should be refactored into these callbacks.
-Here is a simple example:
+Here is a simple example::
-+static struct watchdog_ops s3c2410wdt_ops = {
-+ .owner = THIS_MODULE,
-+ .start = s3c2410wdt_start,
-+ .stop = s3c2410wdt_stop,
-+ .ping = s3c2410wdt_keepalive,
-+ .set_timeout = s3c2410wdt_set_heartbeat,
-+};
+ +static struct watchdog_ops s3c2410wdt_ops = {
+ + .owner = THIS_MODULE,
+ + .start = s3c2410wdt_start,
+ + .stop = s3c2410wdt_stop,
+ + .ping = s3c2410wdt_keepalive,
+ + .set_timeout = s3c2410wdt_set_heartbeat,
+ +};
-A typical function-header change looks like:
+A typical function-header change looks like::
--static void s3c2410wdt_keepalive(void)
-+static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
- {
-...
-+
-+ return 0;
- }
+ -static void s3c2410wdt_keepalive(void)
+ +static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
+ {
+ ...
+ +
+ + return 0;
+ }
-...
+ ...
-- s3c2410wdt_keepalive();
-+ s3c2410wdt_keepalive(&s3c2410_wdd);
+ - s3c2410wdt_keepalive();
+ + s3c2410wdt_keepalive(&s3c2410_wdd);
Add the watchdog device
@@ -159,12 +161,12 @@ static variables. Those have to be converted to use the members in
watchdog_device. Note that the timeout values are unsigned int. Some drivers
use signed int, so this has to be converted, too.
-Here is a simple example for a watchdog device:
+Here is a simple example for a watchdog device::
-+static struct watchdog_device s3c2410_wdd = {
-+ .info = &s3c2410_wdt_ident,
-+ .ops = &s3c2410wdt_ops,
-+};
+ +static struct watchdog_device s3c2410_wdd = {
+ + .info = &s3c2410_wdt_ident,
+ + .ops = &s3c2410wdt_ops,
+ +};
Handle the 'nowayout' feature
@@ -173,12 +175,12 @@ Handle the 'nowayout' feature
A few drivers use nowayout statically, i.e. there is no module parameter for it
and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be
used. This needs to be converted by initializing the status variable of the
-watchdog_device like this:
+watchdog_device like this::
.status = WATCHDOG_NOWAYOUT_INIT_STATUS,
Most drivers, however, also allow runtime configuration of nowayout, usually
-by adding a module parameter. The conversion for this would be something like:
+by adding a module parameter. The conversion for this would be something like::
watchdog_set_nowayout(&s3c2410_wdd, nowayout);
@@ -191,15 +193,15 @@ Register the watchdog device
Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev).
Make sure the return value gets checked and the error message, if present,
-still fits. Also convert the unregister case.
+still fits. Also convert the unregister case::
-- ret = misc_register(&s3c2410wdt_miscdev);
-+ ret = watchdog_register_device(&s3c2410_wdd);
+ - ret = misc_register(&s3c2410wdt_miscdev);
+ + ret = watchdog_register_device(&s3c2410_wdd);
-...
+ ...
-- misc_deregister(&s3c2410wdt_miscdev);
-+ watchdog_unregister_device(&s3c2410_wdd);
+ - misc_deregister(&s3c2410wdt_miscdev);
+ + watchdog_unregister_device(&s3c2410_wdd);
Update the Kconfig-entry
@@ -207,7 +209,7 @@ Update the Kconfig-entry
The entry for the driver now needs to select WATCHDOG_CORE:
-+ select WATCHDOG_CORE
+ + select WATCHDOG_CORE
Create a patch and send it to upstream
@@ -215,4 +217,3 @@ Create a patch and send it to upstream
Make sure you understood Documentation/process/submitting-patches.rst and send your patch to
linux-watchdog@vger.kernel.org. We are looking forward to it :)
-
diff --git a/Documentation/watchdog/hpwdt.txt b/Documentation/watchdog/hpwdt.rst
similarity index 79%
rename from Documentation/watchdog/hpwdt.txt
rename to Documentation/watchdog/hpwdt.rst
index aaa9e4b4bdcd..94a96371113e 100644
--- a/Documentation/watchdog/hpwdt.txt
+++ b/Documentation/watchdog/hpwdt.rst
@@ -1,7 +1,12 @@
+===========================
+HPE iLO NMI Watchdog Driver
+===========================
+
+for iLO based ProLiant Servers
+==============================
+
Last reviewed: 08/20/2018
- HPE iLO NMI Watchdog Driver
- for iLO based ProLiant Servers
The HPE iLO NMI Watchdog driver is a kernel module that provides basic
watchdog functionality and handler for the iLO "Generate NMI to System"
@@ -20,23 +25,26 @@ Last reviewed: 08/20/2018
The hpwdt driver also has the following module parameters:
- soft_margin - allows the user to set the watchdog timer value.
+ ============ ================================================================
+ soft_margin allows the user to set the watchdog timer value.
Default value is 30 seconds.
- timeout - an alias of soft_margin.
- pretimeout - allows the user to set the watchdog pretimeout value.
+ timeout an alias of soft_margin.
+ pretimeout allows the user to set the watchdog pretimeout value.
This is the number of seconds before timeout when an
NMI is delivered to the system. Setting the value to
zero disables the pretimeout NMI.
Default value is 9 seconds.
- nowayout - basic watchdog parameter that does not allow the timer to
+ nowayout basic watchdog parameter that does not allow the timer to
be restarted or an impending ASR to be escaped.
Default value is set when compiling the kernel. If it is set
to "Y", then there is no way of disabling the watchdog once
it has been started.
+ ============ ================================================================
- NOTE: More information about watchdog drivers in general, including the ioctl
+ NOTE:
+ More information about watchdog drivers in general, including the ioctl
interface to /dev/watchdog can be found in
- Documentation/watchdog/watchdog-api.txt and Documentation/IPMI.txt.
+ Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.txt.
Due to limitations in the iLO hardware, the NMI pretimeout if enabled,
can only be set to 9 seconds. Attempts to set pretimeout to other
@@ -63,4 +71,3 @@ Last reviewed: 08/20/2018
The HPE iLO NMI Watchdog Driver and documentation were originally developed
by Tom Mingarelli.
-
diff --git a/Documentation/watchdog/index.rst b/Documentation/watchdog/index.rst
new file mode 100644
index 000000000000..33a0de631e84
--- /dev/null
+++ b/Documentation/watchdog/index.rst
@@ -0,0 +1,25 @@
+:orphan:
+
+======================
+Linux Watchdog Support
+======================
+
+.. toctree::
+ :maxdepth: 1
+
+ hpwdt
+ mlx-wdt
+ pcwd-watchdog
+ watchdog-api
+ watchdog-kernel-api
+ watchdog-parameters
+ watchdog-pm
+ wdt
+ convert_drivers_to_kernel_api
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/watchdog/mlx-wdt.txt b/Documentation/watchdog/mlx-wdt.rst
similarity index 78%
rename from Documentation/watchdog/mlx-wdt.txt
rename to Documentation/watchdog/mlx-wdt.rst
index 66eeb78505c3..bf5bafac47f0 100644
--- a/Documentation/watchdog/mlx-wdt.txt
+++ b/Documentation/watchdog/mlx-wdt.rst
@@ -1,5 +1,9 @@
- Mellanox watchdog drivers
- for x86 based system switches
+=========================
+Mellanox watchdog drivers
+=========================
+
+for x86 based system switches
+=============================
This driver provides watchdog functionality for various Mellanox
Ethernet and Infiniband switch systems.
@@ -9,16 +13,16 @@ Mellanox watchdog device is implemented in a programmable logic device.
There are 2 types of HW watchdog implementations.
Type 1:
-Actual HW timeout can be defined as a power of 2 msec.
-e.g. timeout 20 sec will be rounded up to 32768 msec.
-The maximum timeout period is 32 sec (32768 msec.),
-Get time-left isn't supported
+ Actual HW timeout can be defined as a power of 2 msec.
+ e.g. timeout 20 sec will be rounded up to 32768 msec.
+ The maximum timeout period is 32 sec (32768 msec.),
+ Get time-left isn't supported
Type 2:
-Actual HW timeout is defined in sec. and it's the same as
-a user-defined timeout.
-Maximum timeout is 255 sec.
-Get time-left is supported.
+ Actual HW timeout is defined in sec. and it's the same as
+ a user-defined timeout.
+ Maximum timeout is 255 sec.
+ Get time-left is supported.
Type 1 HW watchdog implementation exist in old systems and
all new systems have type 2 HW watchdog.
diff --git a/Documentation/watchdog/pcwd-watchdog.txt b/Documentation/watchdog/pcwd-watchdog.rst
similarity index 89%
rename from Documentation/watchdog/pcwd-watchdog.txt
rename to Documentation/watchdog/pcwd-watchdog.rst
index b8e60a441a43..405e2a370082 100644
--- a/Documentation/watchdog/pcwd-watchdog.txt
+++ b/Documentation/watchdog/pcwd-watchdog.rst
@@ -1,8 +1,13 @@
+===================================
+Berkshire Products PC Watchdog Card
+===================================
+
Last reviewed: 10/05/2007
- Berkshire Products PC Watchdog Card
- Support for ISA Cards Revision A and C
- Documentation and Driver by Ken Hollis <kenji@bitgate.com>
+Support for ISA Cards Revision A and C
+=======================================
+
+Documentation and Driver by Ken Hollis <kenji@bitgate.com>
The PC Watchdog is a card that offers the same type of functionality that
the WDT card does, only it doesn't require an IRQ to run. Furthermore,
@@ -33,6 +38,7 @@ Last reviewed: 10/05/2007
WDIOC_GETSUPPORT
This returns the support of the card itself. This
returns in structure "PCWDS" which returns:
+
options = WDIOS_TEMPPANIC
(This card supports temperature)
firmware_version = xxxx
@@ -63,4 +69,3 @@ Last reviewed: 10/05/2007
-- Ken Hollis
(kenji@bitgate.com)
-
diff --git a/Documentation/watchdog/watchdog-api.txt b/Documentation/watchdog/watchdog-api.rst
similarity index 80%
rename from Documentation/watchdog/watchdog-api.txt
rename to Documentation/watchdog/watchdog-api.rst
index 0e62ba33b7fb..c6c1e9fa9f73 100644
--- a/Documentation/watchdog/watchdog-api.txt
+++ b/Documentation/watchdog/watchdog-api.rst
@@ -1,7 +1,10 @@
+=============================
+The Linux Watchdog driver API
+=============================
+
Last reviewed: 10/05/2007
-The Linux Watchdog driver API.
Copyright 2002 Christer Weingel <wingel@nano-system.com>
@@ -10,7 +13,8 @@ driver which is (c) Copyright 2000 Jakob Oestergaard <jakob@ostenfeld.dk>
This document describes the state of the Linux 2.4.18 kernel.
-Introduction:
+Introduction
+============
A Watchdog Timer (WDT) is a hardware circuit that can reset the
computer system in case of a software fault. You probably knew that
@@ -30,7 +34,8 @@ drivers implement different, and sometimes incompatible, parts of it.
This file is an attempt to document the existing usage and allow
future driver writers to use it as a reference.
-The simplest API:
+The simplest API
+================
All drivers support the basic mode of operation, where the watchdog
activates as soon as /dev/watchdog is opened and will reboot unless
@@ -54,7 +59,8 @@ after the timeout has passed. Watchdog devices also usually support
the nowayout module parameter so that this option can be controlled at
runtime.
-Magic Close feature:
+Magic Close feature
+===================
If a driver supports "Magic Close", the driver will not disable the
watchdog unless a specific magic character 'V' has been sent to
@@ -64,7 +70,8 @@ will assume that the daemon (and userspace in general) died, and will
stop pinging the watchdog without disabling it first. This will then
cause a reboot if the watchdog is not re-opened in sufficient time.
-The ioctl API:
+The ioctl API
+=============
All conforming drivers also support an ioctl API.
@@ -73,7 +80,7 @@ Pinging the watchdog using an ioctl:
All drivers that have an ioctl interface support at least one ioctl,
KEEPALIVE. This ioctl does exactly the same thing as a write to the
watchdog device, so the main loop in the above program could be
-replaced with:
+replaced with::
while (1) {
ioctl(fd, WDIOC_KEEPALIVE, 0);
@@ -82,14 +89,15 @@ replaced with:
the argument to the ioctl is ignored.
-Setting and getting the timeout:
+Setting and getting the timeout
+===============================
For some drivers it is possible to modify the watchdog timeout on the
fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT
flag set in their option field. The argument is an integer
representing the timeout in seconds. The driver returns the real
timeout used in the same variable, and this timeout might differ from
-the requested one due to limitation of the hardware.
+the requested one due to limitation of the hardware::
int timeout = 45;
ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
@@ -99,18 +107,19 @@ This example might actually print "The timeout was set to 60 seconds"
if the device has a granularity of minutes for its timeout.
Starting with the Linux 2.4.18 kernel, it is possible to query the
-current timeout using the GETTIMEOUT ioctl.
+current timeout using the GETTIMEOUT ioctl::
ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
printf("The timeout was is %d seconds\n", timeout);
-Pretimeouts:
+Pretimeouts
+===========
Some watchdog timers can be set to have a trigger go off before the
actual time they will reset the system. This can be done with an NMI,
interrupt, or other mechanism. This allows Linux to record useful
information (like panic information and kernel coredumps) before it
-resets.
+resets::
pretimeout = 10;
ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);
@@ -121,89 +130,113 @@ the pretimeout. So, for instance, if you set the timeout to 60 seconds
and the pretimeout to 10 seconds, the pretimeout will go off in 50
seconds. Setting a pretimeout to zero disables it.
-There is also a get function for getting the pretimeout:
+There is also a get function for getting the pretimeout::
ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
printf("The pretimeout was is %d seconds\n", timeout);
Not all watchdog drivers will support a pretimeout.
-Get the number of seconds before reboot:
+Get the number of seconds before reboot
+=======================================
Some watchdog drivers have the ability to report the remaining time
before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
-that returns the number of seconds before reboot.
+that returns the number of seconds before reboot::
ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
printf("The timeout was is %d seconds\n", timeleft);
-Environmental monitoring:
+Environmental monitoring
+========================
All watchdog drivers are required return more information about the system,
some do temperature, fan and power level monitoring, some can tell you
the reason for the last reboot of the system. The GETSUPPORT ioctl is
-available to ask what the device can do:
+available to ask what the device can do::
struct watchdog_info ident;
ioctl(fd, WDIOC_GETSUPPORT, &ident);
the fields returned in the ident struct are:
+ ================ =============================================
identity a string identifying the watchdog driver
firmware_version the firmware version of the card if available
options a flags describing what the device supports
+ ================ =============================================
the options field can have the following bits set, and describes what
kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can
return. [FIXME -- Is this correct?]
+ ================ =========================
WDIOF_OVERHEAT Reset due to CPU overheat
+ ================ =========================
The machine was last rebooted by the watchdog because the thermal limit was
-exceeded
+exceeded:
+ ============== ==========
WDIOF_FANFAULT Fan failed
+ ============== ==========
A system fan monitored by the watchdog card has failed
+ ============= ================
WDIOF_EXTERN1 External relay 1
+ ============= ================
External monitoring relay/source 1 was triggered. Controllers intended for
real world applications include external monitoring pins that will trigger
a reset.
+ ============= ================
WDIOF_EXTERN2 External relay 2
+ ============= ================
External monitoring relay/source 2 was triggered
+ ================ =====================
WDIOF_POWERUNDER Power bad/power fault
+ ================ =====================
The machine is showing an undervoltage status
+ =============== =============================
WDIOF_CARDRESET Card previously reset the CPU
+ =============== =============================
The last reboot was caused by the watchdog card
+ ================ =====================
WDIOF_POWEROVER Power over voltage
+ ================ =====================
The machine is showing an overvoltage status. Note that if one level is
under and one over both bits will be set - this may seem odd but makes
sense.
+ =================== =====================
WDIOF_KEEPALIVEPING Keep alive ping reply
+ =================== =====================
The watchdog saw a keepalive ping since it was last queried.
+ ================ =======================
WDIOF_SETTIMEOUT Can set/get the timeout
+ ================ =======================
The watchdog can do pretimeouts.
+ ================ ================================
WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
+ ================ ================================
For those drivers that return any bits set in the option field, the
GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current
-status, and the status at the last reboot, respectively.
+status, and the status at the last reboot, respectively::
int flags;
ioctl(fd, WDIOC_GETSTATUS, &flags);
@@ -216,22 +249,23 @@ Note that not all devices support these two calls, and some only
support the GETBOOTSTATUS call.
Some drivers can measure the temperature using the GETTEMP ioctl. The
-returned value is the temperature in degrees fahrenheit.
+returned value is the temperature in degrees fahrenheit::
int temperature;
ioctl(fd, WDIOC_GETTEMP, &temperature);
Finally the SETOPTIONS ioctl can be used to control some aspects of
-the cards operation.
+the cards operation::
int options = 0;
ioctl(fd, WDIOC_SETOPTIONS, &options);
The following options are available:
+ ================= ================================
WDIOS_DISABLECARD Turn off the watchdog timer
WDIOS_ENABLECARD Turn on the watchdog timer
WDIOS_TEMPPANIC Kernel panic on temperature trip
+ ================= ================================
[FIXME -- better explanations]
-
diff --git a/Documentation/watchdog/watchdog-kernel-api.txt b/Documentation/watchdog/watchdog-kernel-api.rst
similarity index 90%
rename from Documentation/watchdog/watchdog-kernel-api.txt
rename to Documentation/watchdog/watchdog-kernel-api.rst
index 3a91ef5af044..864edbe932c1 100644
--- a/Documentation/watchdog/watchdog-kernel-api.txt
+++ b/Documentation/watchdog/watchdog-kernel-api.rst
@@ -1,5 +1,7 @@
-The Linux WatchDog Timer Driver Core kernel API.
===============================================
+The Linux WatchDog Timer Driver Core kernel API
+===============================================
+
Last reviewed: 12-Feb-2013
Wim Van Sebroeck <wim@iguana.be>
@@ -9,7 +11,7 @@ Introduction
This document does not describe what a WatchDog Timer (WDT) Driver or Device is.
It also does not describe the API which can be used by user space to communicate
with a WatchDog Timer. If you want to know this then please read the following
-file: Documentation/watchdog/watchdog-api.txt .
+file: Documentation/watchdog/watchdog-api.rst .
So what does this document describe? It describes the API that can be used by
WatchDog Timer Drivers that want to use the WatchDog Timer Driver Core
@@ -23,10 +25,10 @@ The API
Each watchdog timer driver that wants to use the WatchDog Timer Driver Core
must #include <linux/watchdog.h> (you would have to do this anyway when
writing a watchdog device driver). This include file contains following
-register/unregister routines:
+register/unregister routines::
-extern int watchdog_register_device(struct watchdog_device *);
-extern void watchdog_unregister_device(struct watchdog_device *);
+ extern int watchdog_register_device(struct watchdog_device *);
+ extern void watchdog_unregister_device(struct watchdog_device *);
The watchdog_register_device routine registers a watchdog timer device.
The parameter of this routine is a pointer to a watchdog_device structure.
@@ -40,9 +42,9 @@ The watchdog subsystem includes an registration deferral mechanism,
which allows you to register an watchdog as early as you wish during
the boot process.
-The watchdog device structure looks like this:
+The watchdog device structure looks like this::
-struct watchdog_device {
+ struct watchdog_device {
int id;
struct device *parent;
const struct attribute_group **groups;
@@ -62,9 +64,10 @@ struct watchdog_device {
struct watchdog_core_data *wd_data;
unsigned long status;
struct list_head deferred;
-};
+ };
It contains following fields:
+
* id: set by watchdog_register_device, id 0 is special. It has both a
/dev/watchdog0 cdev (dynamic major, minor 0) as well as the old
/dev/watchdog miscdev. The id is set automatically when calling
@@ -114,9 +117,9 @@ It contains following fields:
* deferred: entry in wtd_deferred_reg_list which is used to
register early initialized watchdogs.
-The list of watchdog operations is defined as:
+The list of watchdog operations is defined as::
-struct watchdog_ops {
+ struct watchdog_ops {
struct module *owner;
/* mandatory operations */
int (*start)(struct watchdog_device *);
@@ -129,7 +132,7 @@ struct watchdog_ops {
unsigned int (*get_timeleft)(struct watchdog_device *);
int (*restart)(struct watchdog_device *);
long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long);
-};
+ };
It is important that you first define the module owner of the watchdog timer
driver's operations. This module owner will be used to lock the module when
@@ -138,6 +141,7 @@ module and /dev/watchdog is still open).
Some operations are mandatory and some are optional. The mandatory operations
are:
+
* start: this is a pointer to the routine that starts the watchdog timer
device.
The routine needs a pointer to the watchdog timer device structure as a
@@ -146,51 +150,64 @@ are:
Not all watchdog timer hardware supports the same functionality. That's why
all other routines/operations are optional. They only need to be provided if
they are supported. These optional routines/operations are:
+
* stop: with this routine the watchdog timer device is being stopped.
+
The routine needs a pointer to the watchdog timer device structure as a
parameter. It returns zero on success or a negative errno code for failure.
Some watchdog timer hardware can only be started and not be stopped. A
driver supporting such hardware does not have to implement the stop routine.
+
If a driver has no stop function, the watchdog core will set WDOG_HW_RUNNING
and start calling the driver's keepalive pings function after the watchdog
device is closed.
+
If a watchdog driver does not implement the stop function, it must set
max_hw_heartbeat_ms.
* ping: this is the routine that sends a keepalive ping to the watchdog timer
hardware.
+
The routine needs a pointer to the watchdog timer device structure as a
parameter. It returns zero on success or a negative errno code for failure.
+
Most hardware that does not support this as a separate function uses the
start function to restart the watchdog timer hardware. And that's also what
the watchdog timer driver core does: to send a keepalive ping to the watchdog
timer hardware it will either use the ping operation (when available) or the
start operation (when the ping operation is not available).
+
(Note: the WDIOC_KEEPALIVE ioctl call will only be active when the
WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's
info structure).
* status: this routine checks the status of the watchdog timer device. The
status of the device is reported with watchdog WDIOF_* status flags/bits.
+
WDIOF_MAGICCLOSE and WDIOF_KEEPALIVEPING are reported by the watchdog core;
it is not necessary to report those bits from the driver. Also, if no status
function is provided by the driver, the watchdog core reports the status bits
provided in the bootstatus variable of struct watchdog_device.
+
* set_timeout: this routine checks and changes the timeout of the watchdog
timer device. It returns 0 on success, -EINVAL for "parameter out of range"
and -EIO for "could not write value to the watchdog". On success this
routine should set the timeout value of the watchdog_device to the
achieved timeout value (which may be different from the requested one
because the watchdog does not necessarily have a 1 second resolution).
+
Drivers implementing max_hw_heartbeat_ms set the hardware watchdog heartbeat
to the minimum of timeout and max_hw_heartbeat_ms. Those drivers set the
timeout value of the watchdog_device either to the requested timeout value
(if it is larger than max_hw_heartbeat_ms), or to the achieved timeout value.
(Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the
watchdog's info structure).
+
If the watchdog driver does not have to perform any action but setting the
watchdog_device.timeout, this callback can be omitted.
+
If set_timeout is not provided but, WDIOF_SETTIMEOUT is set, the watchdog
infrastructure updates the timeout value of the watchdog_device internally
to the requested value.
+
If the pretimeout feature is used (WDIOF_PRETIMEOUT), then set_timeout must
also take care of checking if pretimeout is still valid and set up the timer
accordingly. This can't be done in the core without races, so it is the
@@ -201,13 +218,16 @@ they are supported. These optional routines/operations are:
seconds before the actual timeout would happen. It returns 0 on success,
-EINVAL for "parameter out of range" and -EIO for "could not write value to
the watchdog". A value of 0 disables pretimeout notification.
+
(Note: the WDIOF_PRETIMEOUT needs to be set in the options field of the
watchdog's info structure).
+
If the watchdog driver does not have to perform any action but setting the
watchdog_device.pretimeout, this callback can be omitted. That means if
set_pretimeout is not provided but WDIOF_PRETIMEOUT is set, the watchdog
infrastructure updates the pretimeout value of the watchdog_device internally
to the requested value.
+
* get_timeleft: this routines returns the time that's left before a reset.
* restart: this routine restarts the machine. It returns 0 on success or a
negative errno code for failure.
@@ -218,6 +238,7 @@ they are supported. These optional routines/operations are:
The status bits should (preferably) be set with the set_bit and clear_bit alike
bit-operations. The status bits that are defined are:
+
* WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device
is active or not from user perspective. User space is expected to send
heartbeat requests to the driver while this flag is set.
@@ -235,22 +256,30 @@ bit-operations. The status bits that are defined are:
To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog
timer device) you can either:
+
* set it statically in your watchdog_device struct with
+
.status = WATCHDOG_NOWAYOUT_INIT_STATUS,
+
(this will set the value the same as CONFIG_WATCHDOG_NOWAYOUT) or
- * use the following helper function:
- static inline void watchdog_set_nowayout(struct watchdog_device *wdd, int nowayout)
+ * use the following helper function::
+
+ static inline void watchdog_set_nowayout(struct watchdog_device *wdd,
+ int nowayout)
+
+Note:
+ The WatchDog Timer Driver Core supports the magic close feature and
+ the nowayout feature. To use the magic close feature you must set the
+ WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
-Note: The WatchDog Timer Driver Core supports the magic close feature and
-the nowayout feature. To use the magic close feature you must set the
-WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
The nowayout feature will overrule the magic close feature.
To get or set driver specific data the following two helper functions should be
-used:
+used::
-static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data)
-static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
+ static inline void watchdog_set_drvdata(struct watchdog_device *wdd,
+ void *data)
+ static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
The watchdog_set_drvdata function allows you to add driver specific data. The
arguments of this function are the watchdog device where you want to add the
@@ -260,10 +289,11 @@ The watchdog_get_drvdata function allows you to retrieve driver specific data.
The argument of this function is the watchdog device where you want to retrieve
data from. The function returns the pointer to the driver specific data.
-To initialize the timeout field, the following function can be used:
+To initialize the timeout field, the following function can be used::
-extern int watchdog_init_timeout(struct watchdog_device *wdd,
- unsigned int timeout_parm, struct device *dev);
+ extern int watchdog_init_timeout(struct watchdog_device *wdd,
+ unsigned int timeout_parm,
+ struct device *dev);
The watchdog_init_timeout function allows you to initialize the timeout field
using the module timeout parameter or by retrieving the timeout-sec property from
@@ -272,30 +302,33 @@ to set the default timeout value as timeout value in the watchdog_device and
then use this function to set the user "preferred" timeout value.
This routine returns zero on success and a negative errno code for failure.
-To disable the watchdog on reboot, the user must call the following helper:
+To disable the watchdog on reboot, the user must call the following helper::
-static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd);
+ static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd);
To disable the watchdog when unregistering the watchdog, the user must call
the following helper. Note that this will only stop the watchdog if the
nowayout flag is not set.
-static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd);
+::
+
+ static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd);
To change the priority of the restart handler the following helper should be
-used:
+used::
-void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
+ void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
User should follow the following guidelines for setting the priority:
+
* 0: should be called in last resort, has limited restart capabilities
* 128: default restart handler, use if no other handler is expected to be
available, and/or if restart is sufficient to restart the entire system
* 255: highest priority, will preempt all other restart handlers
-To raise a pretimeout notification, the following function should be used:
+To raise a pretimeout notification, the following function should be used::
-void watchdog_notify_pretimeout(struct watchdog_device *wdd)
+ void watchdog_notify_pretimeout(struct watchdog_device *wdd)
The function can be called in the interrupt context. If watchdog pretimeout
governor framework (kbuild CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled,
diff --git a/Documentation/watchdog/watchdog-parameters.rst b/Documentation/watchdog/watchdog-parameters.rst
new file mode 100644
index 000000000000..b121caae7798
--- /dev/null
+++ b/Documentation/watchdog/watchdog-parameters.rst
@@ -0,0 +1,736 @@
+==========================
+WatchDog Module Parameters
+==========================
+
+This file provides information on the module parameters of many of
+the Linux watchdog drivers. Watchdog driver parameter specs should
+be listed here unless the driver has its own driver-specific information
+file.
+
+See Documentation/admin-guide/kernel-parameters.rst for information on
+providing kernel parameters for builtin drivers versus loadable
+modules.
+
+-------------------------------------------------
+
+acquirewdt:
+ wdt_stop:
+ Acquire WDT 'stop' io port (default 0x43)
+ wdt_start:
+ Acquire WDT 'start' io port (default 0x443)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+advantechwdt:
+ wdt_stop:
+ Advantech WDT 'stop' io port (default 0x443)
+ wdt_start:
+ Advantech WDT 'start' io port (default 0x443)
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=63, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+alim1535_wdt:
+ timeout:
+ Watchdog timeout in seconds. (0 < timeout < 18000, default=60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+alim7101_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30
+ use_gpio:
+ Use the gpio watchdog (required by old cobalt boards).
+ default=0/off/no
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ar7_wdt:
+ margin:
+ Watchdog margin in seconds (default=60)
+ nowayout:
+ Disable watchdog shutdown on close
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+armada_37xx_wdt:
+ timeout:
+ Watchdog timeout in seconds. (default=120)
+ nowayout:
+ Disable watchdog shutdown on close
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+at91rm9200_wdt:
+ wdt_time:
+ Watchdog time in seconds. (default=5)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+at91sam9_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+bcm47xx_wdt:
+ wdt_time:
+ Watchdog time in seconds. (default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+coh901327_wdt:
+ margin:
+ Watchdog margin in seconds (default 60s)
+
+-------------------------------------------------
+
+cpu5wdt:
+ port:
+ base address of watchdog card, default is 0x91
+ verbose:
+ be verbose, default is 0 (no)
+ ticks:
+ count down ticks, default is 10000
+
+-------------------------------------------------
+
+cpwd:
+ wd0_timeout:
+ Default watchdog0 timeout in 1/10secs
+ wd1_timeout:
+ Default watchdog1 timeout in 1/10secs
+ wd2_timeout:
+ Default watchdog2 timeout in 1/10secs
+
+-------------------------------------------------
+
+da9052wdt:
+ timeout:
+ Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+davinci_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 600, default 60
+
+-------------------------------------------------
+
+ebc-c384_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+
+-------------------------------------------------
+
+ep93xx_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
+
+-------------------------------------------------
+
+eurotechwdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ io:
+ Eurotech WDT io port (default=0x3f0)
+ irq:
+ Eurotech WDT irq (default=10)
+ ev:
+ Eurotech WDT event type (default is `int`)
+
+-------------------------------------------------
+
+gef_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+geodewdt:
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=131, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+i6300esb:
+ heartbeat:
+ Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+iTCO_wdt:
+ heartbeat:
+ Watchdog heartbeat in seconds.
+ (2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+iTCO_vendor_support:
+ vendorsupport:
+ iTCO vendor specific support mode, default=0 (none),
+ 1=SuperMicro Pent3, 2=SuperMicro Pent4+, 911=Broken SMI BIOS
+
+-------------------------------------------------
+
+ib700wdt:
+ timeout:
+ Watchdog timeout in seconds. 0<= timeout <=30, default=30.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ibmasr:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+imx2_wdt:
+ timeout:
+ Watchdog timeout in seconds (default 60 s)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+indydog:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+iop_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+it8712f_wdt:
+ margin:
+ Watchdog margin in seconds (default 60)
+ nowayout:
+ Disable watchdog shutdown on close
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+it87_wdt:
+ nogameport:
+ Forbid the activation of game port, default=0
+ nocir:
+ Forbid the use of CIR (workaround for some buggy setups); set to 1 if
+system resets despite watchdog daemon running, default=0
+ exclusive:
+ Watchdog exclusive device open, default=1
+ timeout:
+ Watchdog timeout in seconds, default=60
+ testmode:
+ Watchdog test mode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ixp4xx_wdt:
+ heartbeat:
+ Watchdog heartbeat in seconds (default 60s)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ks8695_wdt:
+ wdt_time:
+ Watchdog time in seconds. (default=5)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+machzwd:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ action:
+ after watchdog resets, generate:
+ 0 = RESET(*) 1 = SMI 2 = NMI 3 = SCI
+
+-------------------------------------------------
+
+max63xx_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 60, default 60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ nodelay:
+ Force selection of a timeout setting without initial delay
+ (max6373/74 only, default=0)
+
+-------------------------------------------------
+
+mixcomwd:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+mpc8xxx_wdt:
+ timeout:
+ Watchdog timeout in ticks. (0<timeout<65536, default=65535)
+ reset:
+ Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+mv64x60_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ni903x_wdt:
+ timeout:
+ Initial watchdog timeout in seconds (0<timeout<516, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+nic7018_wdt:
+ timeout:
+ Initial watchdog timeout in seconds (0<timeout<464, default=80)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+nuc900_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds.
+ (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+omap_wdt:
+ timer_margin:
+ initial watchdog timeout (in seconds)
+ early_enable:
+ Watchdog is started on module insertion (default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+orion_wdt:
+ heartbeat:
+ Initial watchdog heartbeat in seconds
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+pc87413_wdt:
+ io:
+ pc87413 WDT I/O port (default: io).
+ timeout:
+ Watchdog timeout in minutes (default=timeout).
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+pika_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+pnx4008_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 60, default 19
+ nowayout:
+ Set to 1 to keep watchdog running after device release
+
+-------------------------------------------------
+
+pnx833x_wdt:
+ timeout:
+ Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ start_enabled:
+ Watchdog is started on module insertion (default=1)
+
+-------------------------------------------------
+
+rc32434_wdt:
+ timeout:
+ Watchdog timeout value, in seconds (default=20)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+riowd:
+ riowd_timeout:
+ Watchdog timeout in minutes (default=1)
+
+-------------------------------------------------
+
+s3c2410_wdt:
+ tmr_margin:
+ Watchdog tmr_margin in seconds. (default=15)
+ tmr_atboot:
+ Watchdog is started at boot time if set to 1, default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ soft_noboot:
+ Watchdog action, set to 1 to ignore reboots, 0 to reboot
+ debug:
+ Watchdog debug, set to >1 for debug, (default 0)
+
+-------------------------------------------------
+
+sa1100_wdt:
+ margin:
+ Watchdog margin in seconds (default 60s)
+
+-------------------------------------------------
+
+sb_wdog:
+ timeout:
+ Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
+
+-------------------------------------------------
+
+sbc60xxwdt:
+ wdt_stop:
+ SBC60xx WDT 'stop' io port (default 0x45)
+ wdt_start:
+ SBC60xx WDT 'start' io port (default 0x443)
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sbc7240_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=255, default=30)
+ nowayout:
+ Disable watchdog when closing device file
+
+-------------------------------------------------
+
+sbc8360:
+ timeout:
+ Index into timeout table (0-63) (default=27 (60s))
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sbc_epx_c3:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sbc_fitpc2_wdt:
+ margin:
+ Watchdog margin in seconds (default 60s)
+ nowayout:
+ Watchdog cannot be stopped once started
+
+-------------------------------------------------
+
+sbsa_gwdt:
+ timeout:
+ Watchdog timeout in seconds. (default 10s)
+ action:
+ Watchdog action at the first stage timeout,
+ set to 0 to ignore, 1 to panic. (default=0)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sc1200wdt:
+ isapnp:
+ When set to 0 driver ISA PnP support will be disabled (default=1)
+ io:
+ io port
+ timeout:
+ range is 0-255 minutes, default is 1
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sc520_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sch311x_wdt:
+ force_id:
+ Override the detected device ID
+ therm_trip:
+ Should a ThermTrip trigger the reset generator
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=15300, default=60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+scx200_wdt:
+ margin:
+ Watchdog margin in seconds
+ nowayout:
+ Disable watchdog shutdown on close
+
+-------------------------------------------------
+
+shwdt:
+ clock_division_ratio:
+ Clock division ratio. Valid ranges are from 0x5 (1.31ms)
+ to 0x7 (5.25ms). (default=7)
+ heartbeat:
+ Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+smsc37b787_wdt:
+ timeout:
+ range is 1-255 units, default is 60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+softdog:
+ soft_margin:
+ Watchdog soft_margin in seconds.
+ (0 < soft_margin < 65536, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ soft_noboot:
+ Softdog action, set to 1 to ignore reboots, 0 to reboot
+ (default=0)
+
+-------------------------------------------------
+
+stmp3xxx_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 4194304, default 19
+
+-------------------------------------------------
+
+tegra_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 120)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ts72xx_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
+ nowayout:
+ Disable watchdog shutdown on close
+
+-------------------------------------------------
+
+twl4030_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+txx9wdt:
+ timeout:
+ Watchdog timeout in seconds. (0<timeout<N, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+uniphier_wdt:
+ timeout:
+ Watchdog timeout in power of two seconds.
+ (1 <= timeout <= 128, default=64)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+w83627hf_wdt:
+ wdt_io:
+ w83627hf/thf WDT io port (default 0x2E)
+ timeout:
+ Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+w83877f_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+w83977f_wdt:
+ timeout:
+ Watchdog timeout in seconds (15..7635), default=45)
+ testmode:
+ Watchdog testmode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wafer5823wdt:
+ timeout:
+ Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wdt285:
+ soft_margin:
+ Watchdog timeout in seconds (default=60)
+
+-------------------------------------------------
+
+wdt977:
+ timeout:
+ Watchdog timeout in seconds (60..15300, default=60)
+ testmode:
+ Watchdog testmode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wm831x_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wm8350_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sun4v_wdt:
+ timeout_ms:
+ Watchdog timeout in milliseconds 1..180000, default=60000)
+ nowayout:
+ Watchdog cannot be stopped once started
diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt
deleted file mode 100644
index 0b88e333f9e1..000000000000
--- a/Documentation/watchdog/watchdog-parameters.txt
+++ /dev/null
@@ -1,410 +0,0 @@
-This file provides information on the module parameters of many of
-the Linux watchdog drivers. Watchdog driver parameter specs should
-be listed here unless the driver has its own driver-specific information
-file.
-
-
-See Documentation/admin-guide/kernel-parameters.rst for information on
-providing kernel parameters for builtin drivers versus loadable
-modules.
-
-
--------------------------------------------------
-acquirewdt:
-wdt_stop: Acquire WDT 'stop' io port (default 0x43)
-wdt_start: Acquire WDT 'start' io port (default 0x443)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-advantechwdt:
-wdt_stop: Advantech WDT 'stop' io port (default 0x443)
-wdt_start: Advantech WDT 'start' io port (default 0x443)
-timeout: Watchdog timeout in seconds. 1<= timeout <=63, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-alim1535_wdt:
-timeout: Watchdog timeout in seconds. (0 < timeout < 18000, default=60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-alim7101_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30
-use_gpio: Use the gpio watchdog (required by old cobalt boards).
- default=0/off/no
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ar7_wdt:
-margin: Watchdog margin in seconds (default=60)
-nowayout: Disable watchdog shutdown on close
- (default=kernel config parameter)
--------------------------------------------------
-armada_37xx_wdt:
-timeout: Watchdog timeout in seconds. (default=120)
-nowayout: Disable watchdog shutdown on close
- (default=kernel config parameter)
--------------------------------------------------
-at91rm9200_wdt:
-wdt_time: Watchdog time in seconds. (default=5)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-at91sam9_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 15)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-bcm47xx_wdt:
-wdt_time: Watchdog time in seconds. (default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-coh901327_wdt:
-margin: Watchdog margin in seconds (default 60s)
--------------------------------------------------
-cpu5wdt:
-port: base address of watchdog card, default is 0x91
-verbose: be verbose, default is 0 (no)
-ticks: count down ticks, default is 10000
--------------------------------------------------
-cpwd:
-wd0_timeout: Default watchdog0 timeout in 1/10secs
-wd1_timeout: Default watchdog1 timeout in 1/10secs
-wd2_timeout: Default watchdog2 timeout in 1/10secs
--------------------------------------------------
-da9052wdt:
-timeout: Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-davinci_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 600, default 60
--------------------------------------------------
-ebc-c384_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
-nowayout: Watchdog cannot be stopped once started
--------------------------------------------------
-ep93xx_wdt:
-nowayout: Watchdog cannot be stopped once started
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
--------------------------------------------------
-eurotechwdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-io: Eurotech WDT io port (default=0x3f0)
-irq: Eurotech WDT irq (default=10)
-ev: Eurotech WDT event type (default is `int')
--------------------------------------------------
-gef_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-geodewdt:
-timeout: Watchdog timeout in seconds. 1<= timeout <=131, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-i6300esb:
-heartbeat: Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-iTCO_wdt:
-heartbeat: Watchdog heartbeat in seconds.
- (2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-iTCO_vendor_support:
-vendorsupport: iTCO vendor specific support mode, default=0 (none),
- 1=SuperMicro Pent3, 2=SuperMicro Pent4+, 911=Broken SMI BIOS
--------------------------------------------------
-ib700wdt:
-timeout: Watchdog timeout in seconds. 0<= timeout <=30, default=30.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ibmasr:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-imx2_wdt:
-timeout: Watchdog timeout in seconds (default 60 s)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-indydog:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-iop_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-it8712f_wdt:
-margin: Watchdog margin in seconds (default 60)
-nowayout: Disable watchdog shutdown on close
- (default=kernel config parameter)
--------------------------------------------------
-it87_wdt:
-nogameport: Forbid the activation of game port, default=0
-nocir: Forbid the use of CIR (workaround for some buggy setups); set to 1 if
-system resets despite watchdog daemon running, default=0
-exclusive: Watchdog exclusive device open, default=1
-timeout: Watchdog timeout in seconds, default=60
-testmode: Watchdog test mode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ixp4xx_wdt:
-heartbeat: Watchdog heartbeat in seconds (default 60s)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ks8695_wdt:
-wdt_time: Watchdog time in seconds. (default=5)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-machzwd:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-action: after watchdog resets, generate:
- 0 = RESET(*) 1 = SMI 2 = NMI 3 = SCI
--------------------------------------------------
-max63xx_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-nodelay: Force selection of a timeout setting without initial delay
- (max6373/74 only, default=0)
--------------------------------------------------
-mixcomwd:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-mpc8xxx_wdt:
-timeout: Watchdog timeout in ticks. (0<timeout<65536, default=65535)
-reset: Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-mv64x60_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ni903x_wdt:
-timeout: Initial watchdog timeout in seconds (0<timeout<516, default=60)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-nic7018_wdt:
-timeout: Initial watchdog timeout in seconds (0<timeout<464, default=80)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-nuc900_wdt:
-heartbeat: Watchdog heartbeats in seconds.
- (default = 15)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-omap_wdt:
-timer_margin: initial watchdog timeout (in seconds)
-early_enable: Watchdog is started on module insertion (default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-orion_wdt:
-heartbeat: Initial watchdog heartbeat in seconds
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-pc87413_wdt:
-io: pc87413 WDT I/O port (default: io).
-timeout: Watchdog timeout in minutes (default=timeout).
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-pika_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 15)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-pnx4008_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 19
-nowayout: Set to 1 to keep watchdog running after device release
--------------------------------------------------
-pnx833x_wdt:
-timeout: Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-start_enabled: Watchdog is started on module insertion (default=1)
--------------------------------------------------
-rc32434_wdt:
-timeout: Watchdog timeout value, in seconds (default=20)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-riowd:
-riowd_timeout: Watchdog timeout in minutes (default=1)
--------------------------------------------------
-s3c2410_wdt:
-tmr_margin: Watchdog tmr_margin in seconds. (default=15)
-tmr_atboot: Watchdog is started at boot time if set to 1, default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-soft_noboot: Watchdog action, set to 1 to ignore reboots, 0 to reboot
-debug: Watchdog debug, set to >1 for debug, (default 0)
--------------------------------------------------
-sa1100_wdt:
-margin: Watchdog margin in seconds (default 60s)
--------------------------------------------------
-sb_wdog:
-timeout: Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
--------------------------------------------------
-sbc60xxwdt:
-wdt_stop: SBC60xx WDT 'stop' io port (default 0x45)
-wdt_start: SBC60xx WDT 'start' io port (default 0x443)
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sbc7240_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=255, default=30)
-nowayout: Disable watchdog when closing device file
--------------------------------------------------
-sbc8360:
-timeout: Index into timeout table (0-63) (default=27 (60s))
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sbc_epx_c3:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sbc_fitpc2_wdt:
-margin: Watchdog margin in seconds (default 60s)
-nowayout: Watchdog cannot be stopped once started
--------------------------------------------------
-sbsa_gwdt:
-timeout: Watchdog timeout in seconds. (default 10s)
-action: Watchdog action at the first stage timeout,
- set to 0 to ignore, 1 to panic. (default=0)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sc1200wdt:
-isapnp: When set to 0 driver ISA PnP support will be disabled (default=1)
-io: io port
-timeout: range is 0-255 minutes, default is 1
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sc520_wdt:
-timeout: Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sch311x_wdt:
-force_id: Override the detected device ID
-therm_trip: Should a ThermTrip trigger the reset generator
-timeout: Watchdog timeout in seconds. 1<= timeout <=15300, default=60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-scx200_wdt:
-margin: Watchdog margin in seconds
-nowayout: Disable watchdog shutdown on close
--------------------------------------------------
-shwdt:
-clock_division_ratio: Clock division ratio. Valid ranges are from 0x5 (1.31ms)
- to 0x7 (5.25ms). (default=7)
-heartbeat: Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-smsc37b787_wdt:
-timeout: range is 1-255 units, default is 60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-softdog:
-soft_margin: Watchdog soft_margin in seconds.
- (0 < soft_margin < 65536, default=60)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-soft_noboot: Softdog action, set to 1 to ignore reboots, 0 to reboot
- (default=0)
--------------------------------------------------
-stmp3xxx_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 4194304, default 19
--------------------------------------------------
-tegra_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 120)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ts72xx_wdt:
-timeout: Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
-nowayout: Disable watchdog shutdown on close
--------------------------------------------------
-twl4030_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-txx9wdt:
-timeout: Watchdog timeout in seconds. (0<timeout<N, default=60)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-uniphier_wdt:
-timeout: Watchdog timeout in power of two seconds.
- (1 <= timeout <= 128, default=64)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-w83627hf_wdt:
-wdt_io: w83627hf/thf WDT io port (default 0x2E)
-timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-w83877f_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-w83977f_wdt:
-timeout: Watchdog timeout in seconds (15..7635), default=45)
-testmode: Watchdog testmode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wafer5823wdt:
-timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wdt285:
-soft_margin: Watchdog timeout in seconds (default=60)
--------------------------------------------------
-wdt977:
-timeout: Watchdog timeout in seconds (60..15300, default=60)
-testmode: Watchdog testmode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wm831x_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wm8350_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sun4v_wdt:
-timeout_ms: Watchdog timeout in milliseconds 1..180000, default=60000)
-nowayout: Watchdog cannot be stopped once started
--------------------------------------------------
diff --git a/Documentation/watchdog/watchdog-pm.txt b/Documentation/watchdog/watchdog-pm.rst
similarity index 92%
rename from Documentation/watchdog/watchdog-pm.txt
rename to Documentation/watchdog/watchdog-pm.rst
index 7a4dd46e0d24..646e1f28f31f 100644
--- a/Documentation/watchdog/watchdog-pm.txt
+++ b/Documentation/watchdog/watchdog-pm.rst
@@ -1,5 +1,7 @@
+===============================================
The Linux WatchDog Timer Power Management Guide
===============================================
+
Last reviewed: 17-Dec-2018
Wolfram Sang <wsa+renesas@sang-engineering.com>
@@ -16,4 +18,5 @@ On resume, a watchdog timer shall be reset to its selected value to give
userspace enough time to resume. [1] [2]
[1] https://patchwork.kernel.org/patch/10252209/
+
[2] https://patchwork.kernel.org/patch/10711625/
diff --git a/Documentation/watchdog/wdt.txt b/Documentation/watchdog/wdt.rst
similarity index 68%
rename from Documentation/watchdog/wdt.txt
rename to Documentation/watchdog/wdt.rst
index ed2f0b860869..d97b0361535b 100644
--- a/Documentation/watchdog/wdt.txt
+++ b/Documentation/watchdog/wdt.rst
@@ -1,11 +1,14 @@
+============================================================
+WDT Watchdog Timer Interfaces For The Linux Operating System
+============================================================
+
Last Reviewed: 10/05/2007
- WDT Watchdog Timer Interfaces For The Linux Operating System
- Alan Cox <alan@lxorguk.ukuu.org.uk>
+Alan Cox <alan@lxorguk.ukuu.org.uk>
- ICS WDT501-P
- ICS WDT501-P (no fan tachometer)
- ICS WDT500-P
+ - ICS WDT501-P
+ - ICS WDT501-P (no fan tachometer)
+ - ICS WDT500-P
All the interfaces provide /dev/watchdog, which when open must be written
to within a timeout or the machine will reboot. Each write delays the reboot
@@ -21,19 +24,26 @@ degrees Fahrenheit. Each read returns a single byte giving the temperature.
The third interface logs kernel messages on additional alert events.
The ICS ISA-bus wdt card cannot be safely probed for. Instead you need to
-pass IO address and IRQ boot parameters. E.g.:
+pass IO address and IRQ boot parameters. E.g.::
+
wdt.io=0x240 wdt.irq=11
Other "wdt" driver parameters are:
+
+ =========== ======================================================
heartbeat Watchdog heartbeat in seconds (default 60)
nowayout Watchdog cannot be stopped once started (kernel
- build parameter)
+ build parameter)
tachometer WDT501-P Fan Tachometer support (0=disable, default=0)
type WDT501-P Card type (500 or 501, default=500)
+ =========== ======================================================
Features
--------
- WDT501P WDT500P
+
+================ ======= =======
+ WDT501P WDT500P
+================ ======= =======
Reboot Timer X X
External Reboot X X
I/O Port Monitor o o
@@ -42,9 +52,12 @@ Fan Speed X o
Power Under X o
Power Over X o
Overheat X o
+================ ======= =======
The external event interfaces on the WDT boards are not currently supported.
Minor numbers are however allocated for it.
-Example Watchdog Driver: see samples/watchdog/watchdog-simple.c
+Example Watchdog Driver:
+
+ see samples/watchdog/watchdog-simple.c
diff --git a/MAINTAINERS b/MAINTAINERS
index 71b4754ea7c3..b0b674f5aaca 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7040,7 +7040,7 @@ F: drivers/media/usb/hdpvr/
HEWLETT PACKARD ENTERPRISE ILO NMI WATCHDOG DRIVER
M: Jerry Hoemann <jerry.hoemann@hpe.com>
S: Supported
-F: Documentation/watchdog/hpwdt.txt
+F: Documentation/watchdog/hpwdt.rst
F: drivers/watchdog/hpwdt.c
HEWLETT-PACKARD SMART ARRAY RAID DRIVER (hpsa)
diff --git a/drivers/watchdog/Kconfig b/drivers/watchdog/Kconfig
index ffe754539f5a..6cad0b33d7ad 100644
--- a/drivers/watchdog/Kconfig
+++ b/drivers/watchdog/Kconfig
@@ -18,7 +18,7 @@ menuconfig WATCHDOG
reboot the machine) and a driver for hardware watchdog boards, which
are more robust and can also keep track of the temperature inside
your computer. For details, read
- <file:Documentation/watchdog/watchdog-api.txt> in the kernel source.
+ <file:Documentation/watchdog/watchdog-api.rst> in the kernel source.
The watchdog is usually used together with the watchdog daemon
which is available from
@@ -1870,7 +1870,7 @@ config BOOKE_WDT
Watchdog driver for PowerPC Book-E chips, such as the Freescale
MPC85xx SOCs and the IBM PowerPC 440.
- Please see Documentation/watchdog/watchdog-api.txt for
+ Please see Documentation/watchdog/watchdog-api.rst for
more information.
config BOOKE_WDT_DEFAULT_TIMEOUT
@@ -2019,7 +2019,7 @@ config PCWATCHDOG
This card simply watches your kernel to make sure it doesn't freeze,
and if it does, it reboots your computer after a certain amount of
time. This driver is like the WDT501 driver but for different
- hardware. Please read <file:Documentation/watchdog/pcwd-watchdog.txt>. The PC
+ hardware. Please read <file:Documentation/watchdog/pcwd-watchdog.rst>. The PC
watchdog cards can be ordered from <http://www.berkprod.com/>.
To compile this driver as a module, choose M here: the
diff --git a/drivers/watchdog/smsc37b787_wdt.c b/drivers/watchdog/smsc37b787_wdt.c
index 13c817ea1d6a..f5713030d0f7 100644
--- a/drivers/watchdog/smsc37b787_wdt.c
+++ b/drivers/watchdog/smsc37b787_wdt.c
@@ -36,7 +36,7 @@
* mknod /dev/watchdog c 10 130
*
* For an example userspace keep-alive daemon, see:
- * Documentation/watchdog/wdt.txt
+ * Documentation/watchdog/wdt.rst
*/
#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 26/28] docs: xilinx: convert eemi.txt to eemi.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (18 preceding siblings ...)
2019-06-12 17:53 ` [PATCH v4 25/28] docs: watchdog: " Mauro Carvalho Chehab
@ 2019-06-12 17:53 ` Mauro Carvalho Chehab
2019-06-12 17:53 ` [PATCH v4 27/28] docs: scheduler: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (4 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:53 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Michal Simek, linux-arm-kernel
This is a very trivial conversion: adjust the title markup
and add a few literal block markups to produce a better
visual when parsed and avoid warnings.
As newer documents related to xilinx could be added in the future,
create a new index file for it.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/xilinx/{eemi.txt => eemi.rst} | 8 ++++----
Documentation/xilinx/index.rst | 17 +++++++++++++++++
2 files changed, 21 insertions(+), 4 deletions(-)
rename Documentation/xilinx/{eemi.txt => eemi.rst} (92%)
create mode 100644 Documentation/xilinx/index.rst
diff --git a/Documentation/xilinx/eemi.txt b/Documentation/xilinx/eemi.rst
similarity index 92%
rename from Documentation/xilinx/eemi.txt
rename to Documentation/xilinx/eemi.rst
index 5f39b4ffdcd4..9dcbc6f18d75 100644
--- a/Documentation/xilinx/eemi.txt
+++ b/Documentation/xilinx/eemi.rst
@@ -1,6 +1,6 @@
----------------------------------------------------------------------
+====================================
Xilinx Zynq MPSoC EEMI Documentation
----------------------------------------------------------------------
+====================================
Xilinx Zynq MPSoC Firmware Interface
-------------------------------------
@@ -21,7 +21,7 @@ The zynqmp-firmware driver maintain all EEMI APIs in zynqmp_eemi_ops
structure. Any driver who want to communicate with PMC using EEMI APIs
can call zynqmp_pm_get_eemi_ops().
-Example of EEMI ops:
+Example of EEMI ops::
/* zynqmp-firmware driver maintain all EEMI APIs */
struct zynqmp_eemi_ops {
@@ -34,7 +34,7 @@ Example of EEMI ops:
.query_data = zynqmp_pm_query_data,
};
-Example of EEMI ops usage:
+Example of EEMI ops usage::
static const struct zynqmp_eemi_ops *eemi_ops;
u32 ret_payload[PAYLOAD_ARG_CNT];
diff --git a/Documentation/xilinx/index.rst b/Documentation/xilinx/index.rst
new file mode 100644
index 000000000000..01cc1a0714df
--- /dev/null
+++ b/Documentation/xilinx/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+===========
+Xilinx FPGA
+===========
+
+.. toctree::
+ :maxdepth: 1
+
+ eemi
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 27/28] docs: scheduler: convert docs to ReST and rename to *.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (19 preceding siblings ...)
2019-06-12 17:53 ` [PATCH v4 26/28] docs: xilinx: convert eemi.txt to eemi.rst Mauro Carvalho Chehab
@ 2019-06-12 17:53 ` Mauro Carvalho Chehab
2019-06-12 17:53 ` [PATCH v4 28/28] docs: EDID/HOWTO.txt: convert it and rename to howto.rst Mauro Carvalho Chehab
` (3 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:53 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Ingo Molnar, Peter Zijlstra
In order to prepare to add them to the Kernel API book,
convert the files to ReST format.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/testing/sysfs-kernel-uids | 2 +-
.../{completion.txt => completion.rst} | 38 +--
Documentation/scheduler/index.rst | 29 ++
.../{sched-arch.txt => sched-arch.rst} | 18 +-
.../{sched-bwc.txt => sched-bwc.rst} | 30 +-
...{sched-deadline.txt => sched-deadline.rst} | 295 +++++++++---------
...ed-design-CFS.txt => sched-design-CFS.rst} | 15 +-
.../{sched-domains.txt => sched-domains.rst} | 8 +-
.../{sched-energy.txt => sched-energy.rst} | 47 +--
...-nice-design.txt => sched-nice-design.rst} | 6 +-
...{sched-rt-group.txt => sched-rt-group.rst} | 28 +-
.../{sched-stats.txt => sched-stats.rst} | 35 ++-
Documentation/scheduler/text_files.rst | 5 +
Documentation/vm/numa.rst | 2 +-
init/Kconfig | 6 +-
kernel/sched/deadline.c | 2 +-
16 files changed, 332 insertions(+), 234 deletions(-)
rename Documentation/scheduler/{completion.txt => completion.rst} (94%)
create mode 100644 Documentation/scheduler/index.rst
rename Documentation/scheduler/{sched-arch.txt => sched-arch.rst} (81%)
rename Documentation/scheduler/{sched-bwc.txt => sched-bwc.rst} (90%)
rename Documentation/scheduler/{sched-deadline.txt => sched-deadline.rst} (88%)
rename Documentation/scheduler/{sched-design-CFS.txt => sched-design-CFS.rst} (97%)
rename Documentation/scheduler/{sched-domains.txt => sched-domains.rst} (97%)
rename Documentation/scheduler/{sched-energy.txt => sched-energy.rst} (96%)
rename Documentation/scheduler/{sched-nice-design.txt => sched-nice-design.rst} (98%)
rename Documentation/scheduler/{sched-rt-group.txt => sched-rt-group.rst} (95%)
rename Documentation/scheduler/{sched-stats.txt => sched-stats.rst} (91%)
create mode 100644 Documentation/scheduler/text_files.rst
diff --git a/Documentation/ABI/testing/sysfs-kernel-uids b/Documentation/ABI/testing/sysfs-kernel-uids
index 28f14695a852..4182b7061816 100644
--- a/Documentation/ABI/testing/sysfs-kernel-uids
+++ b/Documentation/ABI/testing/sysfs-kernel-uids
@@ -11,4 +11,4 @@ Description:
example would be, if User A has shares = 1024 and user
B has shares = 2048, User B will get twice the CPU
bandwidth user A will. For more details refer
- Documentation/scheduler/sched-design-CFS.txt
+ Documentation/scheduler/sched-design-CFS.rst
diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.rst
similarity index 94%
rename from Documentation/scheduler/completion.txt
rename to Documentation/scheduler/completion.rst
index e5b9df4d8078..9f039b4f4b09 100644
--- a/Documentation/scheduler/completion.txt
+++ b/Documentation/scheduler/completion.rst
@@ -1,3 +1,4 @@
+================================================
Completions - "wait for completion" barrier APIs
================================================
@@ -46,7 +47,7 @@ it has to wait for it.
To use completions you need to #include <linux/completion.h> and
create a static or dynamic variable of type 'struct completion',
-which has only two fields:
+which has only two fields::
struct completion {
unsigned int done;
@@ -57,7 +58,7 @@ This provides the ->wait waitqueue to place tasks on for waiting (if any), and
the ->done completion flag for indicating whether it's completed or not.
Completions should be named to refer to the event that is being synchronized on.
-A good example is:
+A good example is::
wait_for_completion(&early_console_added);
@@ -81,7 +82,7 @@ have taken place, even if these wait functions return prematurely due to a timeo
or a signal triggering.
Initializing of dynamically allocated completion objects is done via a call to
-init_completion():
+init_completion()::
init_completion(&dynamic_object->done);
@@ -100,7 +101,8 @@ but be aware of other races.
For static declaration and initialization, macros are available.
-For static (or global) declarations in file scope you can use DECLARE_COMPLETION():
+For static (or global) declarations in file scope you can use
+DECLARE_COMPLETION()::
static DECLARE_COMPLETION(setup_done);
DECLARE_COMPLETION(setup_done);
@@ -111,7 +113,7 @@ initialized to 'not done' and doesn't require an init_completion() call.
When a completion is declared as a local variable within a function,
then the initialization should always use DECLARE_COMPLETION_ONSTACK()
explicitly, not just to make lockdep happy, but also to make it clear
-that limited scope had been considered and is intentional:
+that limited scope had been considered and is intentional::
DECLARE_COMPLETION_ONSTACK(setup_done)
@@ -140,11 +142,11 @@ Waiting for completions:
------------------------
For a thread to wait for some concurrent activity to finish, it
-calls wait_for_completion() on the initialized completion structure:
+calls wait_for_completion() on the initialized completion structure::
void wait_for_completion(struct completion *done)
-A typical usage scenario is:
+A typical usage scenario is::
CPU#1 CPU#2
@@ -192,17 +194,17 @@ A common problem that occurs is to have unclean assignment of return types,
so take care to assign return-values to variables of the proper type.
Checking for the specific meaning of return values also has been found
-to be quite inaccurate, e.g. constructs like:
+to be quite inaccurate, e.g. constructs like::
if (!wait_for_completion_interruptible_timeout(...))
... would execute the same code path for successful completion and for the
-interrupted case - which is probably not what you want.
+interrupted case - which is probably not what you want::
int wait_for_completion_interruptible(struct completion *done)
This function marks the task TASK_INTERRUPTIBLE while it is waiting.
-If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise.
+If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise::
unsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout)
@@ -214,7 +216,7 @@ Timeouts are preferably calculated with msecs_to_jiffies() or usecs_to_jiffies()
to make the code largely HZ-invariant.
If the returned timeout value is deliberately ignored a comment should probably explain
-why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc()).
+why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc())::
long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout)
@@ -225,14 +227,14 @@ jiffies if completion occurred.
Further variants include _killable which uses TASK_KILLABLE as the
designated tasks state and will return -ERESTARTSYS if it is interrupted,
-or 0 if completion was achieved. There is a _timeout variant as well:
+or 0 if completion was achieved. There is a _timeout variant as well::
long wait_for_completion_killable(struct completion *done)
long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout)
The _io variants wait_for_completion_io() behave the same as the non-_io
variants, except for accounting waiting time as 'waiting on IO', which has
-an impact on how the task is accounted in scheduling/IO stats:
+an impact on how the task is accounted in scheduling/IO stats::
void wait_for_completion_io(struct completion *done)
unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout)
@@ -243,11 +245,11 @@ Signaling completions:
A thread that wants to signal that the conditions for continuation have been
achieved calls complete() to signal exactly one of the waiters that it can
-continue:
+continue::
void complete(struct completion *done)
-... or calls complete_all() to signal all current and future waiters:
+... or calls complete_all() to signal all current and future waiters::
void complete_all(struct completion *done)
@@ -268,7 +270,7 @@ probably are a design bug.
Signaling completion from IRQ context is fine as it will appropriately
lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
-sleep.
+sleep.
try_wait_for_completion()/completion_done():
@@ -276,14 +278,14 @@ try_wait_for_completion()/completion_done():
The try_wait_for_completion() function will not put the thread on the wait
queue but rather returns false if it would need to enqueue (block) the thread,
-else it consumes one posted completion and returns true.
+else it consumes one posted completion and returns true::
bool try_wait_for_completion(struct completion *done)
Finally, to check the state of a completion without changing it in any way,
call completion_done(), which returns false if there are no posted
completions that were not yet consumed by waiters (implying that there are
-waiters) and true otherwise;
+waiters) and true otherwise::
bool completion_done(struct completion *done)
diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
new file mode 100644
index 000000000000..058be77a4c34
--- /dev/null
+++ b/Documentation/scheduler/index.rst
@@ -0,0 +1,29 @@
+:orphan:
+
+===============
+Linux Scheduler
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+
+ completion
+ sched-arch
+ sched-bwc
+ sched-deadline
+ sched-design-CFS
+ sched-domains
+ sched-energy
+ sched-nice-design
+ sched-rt-group
+ sched-stats
+
+ text_files
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/scheduler/sched-arch.txt b/Documentation/scheduler/sched-arch.rst
similarity index 81%
rename from Documentation/scheduler/sched-arch.txt
rename to Documentation/scheduler/sched-arch.rst
index a2f27bbf2cba..0eaec669790a 100644
--- a/Documentation/scheduler/sched-arch.txt
+++ b/Documentation/scheduler/sched-arch.rst
@@ -1,4 +1,6 @@
- CPU Scheduler implementation hints for architecture specific code
+=================================================================
+CPU Scheduler implementation hints for architecture specific code
+=================================================================
Nick Piggin, 2005
@@ -35,9 +37,10 @@ Your cpu_idle routines need to obey the following rules:
4. The only time interrupts need to be disabled when checking
need_resched is if we are about to sleep the processor until
the next interrupt (this doesn't provide any protection of
- need_resched, it prevents losing an interrupt).
+ need_resched, it prevents losing an interrupt):
+
+ 4a. Common problem with this type of sleep appears to be::
- 4a. Common problem with this type of sleep appears to be:
local_irq_disable();
if (!need_resched()) {
local_irq_enable();
@@ -51,10 +54,10 @@ Your cpu_idle routines need to obey the following rules:
although it may be reasonable to do some background work or enter
a low CPU priority.
- 5a. If TIF_POLLING_NRFLAG is set, and we do decide to enter
- an interrupt sleep, it needs to be cleared then a memory
- barrier issued (followed by a test of need_resched with
- interrupts disabled, as explained in 3).
+ - 5a. If TIF_POLLING_NRFLAG is set, and we do decide to enter
+ an interrupt sleep, it needs to be cleared then a memory
+ barrier issued (followed by a test of need_resched with
+ interrupts disabled, as explained in 3).
arch/x86/kernel/process.c has examples of both polling and
sleeping idle functions.
@@ -71,4 +74,3 @@ sh64 - Is sleeping racy vs interrupts? (See #4a)
sparc - IRQs on at this point(?), change local_irq_save to _disable.
- TODO: needs secondary CPUs to disable preempt (See #1)
-
diff --git a/Documentation/scheduler/sched-bwc.txt b/Documentation/scheduler/sched-bwc.rst
similarity index 90%
rename from Documentation/scheduler/sched-bwc.txt
rename to Documentation/scheduler/sched-bwc.rst
index f6b1873f68ab..3a9064219656 100644
--- a/Documentation/scheduler/sched-bwc.txt
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -1,8 +1,9 @@
+=====================
CFS Bandwidth Control
=====================
[ This document only discusses CPU bandwidth control for SCHED_NORMAL.
- The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.txt ]
+ The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.rst ]
CFS bandwidth control is a CONFIG_FAIR_GROUP_SCHED extension which allows the
specification of the maximum CPU bandwidth available to a group or hierarchy.
@@ -27,7 +28,8 @@ cpu.cfs_quota_us: the total available run-time within a period (in microseconds)
cpu.cfs_period_us: the length of a period (in microseconds)
cpu.stat: exports throttling statistics [explained further below]
-The default values are:
+The default values are::
+
cpu.cfs_period_us=100ms
cpu.cfs_quota=-1
@@ -55,7 +57,8 @@ For efficiency run-time is transferred between the global pool and CPU local
on large systems. The amount transferred each time such an update is required
is described as the "slice".
-This is tunable via procfs:
+This is tunable via procfs::
+
/proc/sys/kernel/sched_cfs_bandwidth_slice_us (default=5ms)
Larger slice values will reduce transfer overheads, while smaller values allow
@@ -66,6 +69,7 @@ Statistics
A group's bandwidth statistics are exported via 3 fields in cpu.stat.
cpu.stat:
+
- nr_periods: Number of enforcement intervals that have elapsed.
- nr_throttled: Number of times the group has been throttled/limited.
- throttled_time: The total time duration (in nanoseconds) for which entities
@@ -78,12 +82,15 @@ Hierarchical considerations
The interface enforces that an individual entity's bandwidth is always
attainable, that is: max(c_i) <= C. However, over-subscription in the
aggregate case is explicitly allowed to enable work-conserving semantics
-within a hierarchy.
+within a hierarchy:
+
e.g. \Sum (c_i) may exceed C
+
[ Where C is the parent's bandwidth, and c_i its children ]
There are two ways in which a group may become throttled:
+
a. it fully consumes its own quota within a period
b. a parent's quota is fully consumed within its period
@@ -92,7 +99,7 @@ be allowed to until the parent's runtime is refreshed.
Examples
--------
-1. Limit a group to 1 CPU worth of runtime.
+1. Limit a group to 1 CPU worth of runtime::
If period is 250ms and quota is also 250ms, the group will get
1 CPU worth of runtime every 250ms.
@@ -100,10 +107,10 @@ Examples
# echo 250000 > cpu.cfs_quota_us /* quota = 250ms */
# echo 250000 > cpu.cfs_period_us /* period = 250ms */
-2. Limit a group to 2 CPUs worth of runtime on a multi-CPU machine.
+2. Limit a group to 2 CPUs worth of runtime on a multi-CPU machine
- With 500ms period and 1000ms quota, the group can get 2 CPUs worth of
- runtime every 500ms.
+ With 500ms period and 1000ms quota, the group can get 2 CPUs worth of
+ runtime every 500ms::
# echo 1000000 > cpu.cfs_quota_us /* quota = 1000ms */
# echo 500000 > cpu.cfs_period_us /* period = 500ms */
@@ -112,11 +119,10 @@ Examples
3. Limit a group to 20% of 1 CPU.
- With 50ms period, 10ms quota will be equivalent to 20% of 1 CPU.
+ With 50ms period, 10ms quota will be equivalent to 20% of 1 CPU::
# echo 10000 > cpu.cfs_quota_us /* quota = 10ms */
# echo 50000 > cpu.cfs_period_us /* period = 50ms */
- By using a small period here we are ensuring a consistent latency
- response at the expense of burst capacity.
-
+ By using a small period here we are ensuring a consistent latency
+ response at the expense of burst capacity.
diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.rst
similarity index 88%
rename from Documentation/scheduler/sched-deadline.txt
rename to Documentation/scheduler/sched-deadline.rst
index a7514343b660..3391e86d810c 100644
--- a/Documentation/scheduler/sched-deadline.txt
+++ b/Documentation/scheduler/sched-deadline.rst
@@ -1,29 +1,29 @@
- Deadline Task Scheduling
- ------------------------
+========================
+Deadline Task Scheduling
+========================
-CONTENTS
-========
+.. CONTENTS
- 0. WARNING
- 1. Overview
- 2. Scheduling algorithm
- 2.1 Main algorithm
- 2.2 Bandwidth reclaiming
- 3. Scheduling Real-Time Tasks
- 3.1 Definitions
- 3.2 Schedulability Analysis for Uniprocessor Systems
- 3.3 Schedulability Analysis for Multiprocessor Systems
- 3.4 Relationship with SCHED_DEADLINE Parameters
- 4. Bandwidth management
- 4.1 System-wide settings
- 4.2 Task interface
- 4.3 Default behavior
- 4.4 Behavior of sched_yield()
- 5. Tasks CPU affinity
- 5.1 SCHED_DEADLINE and cpusets HOWTO
- 6. Future plans
- A. Test suite
- B. Minimal main()
+ 0. WARNING
+ 1. Overview
+ 2. Scheduling algorithm
+ 2.1 Main algorithm
+ 2.2 Bandwidth reclaiming
+ 3. Scheduling Real-Time Tasks
+ 3.1 Definitions
+ 3.2 Schedulability Analysis for Uniprocessor Systems
+ 3.3 Schedulability Analysis for Multiprocessor Systems
+ 3.4 Relationship with SCHED_DEADLINE Parameters
+ 4. Bandwidth management
+ 4.1 System-wide settings
+ 4.2 Task interface
+ 4.3 Default behavior
+ 4.4 Behavior of sched_yield()
+ 5. Tasks CPU affinity
+ 5.1 SCHED_DEADLINE and cpusets HOWTO
+ 6. Future plans
+ A. Test suite
+ B. Minimal main()
0. WARNING
@@ -44,7 +44,7 @@ CONTENTS
2. Scheduling algorithm
-==================
+=======================
2.1 Main algorithm
------------------
@@ -80,7 +80,7 @@ CONTENTS
a "remaining runtime". These two parameters are initially set to 0;
- When a SCHED_DEADLINE task wakes up (becomes ready for execution),
- the scheduler checks if
+ the scheduler checks if::
remaining runtime runtime
---------------------------------- > ---------
@@ -97,7 +97,7 @@ CONTENTS
left unchanged;
- When a SCHED_DEADLINE task executes for an amount of time t, its
- remaining runtime is decreased as
+ remaining runtime is decreased as::
remaining runtime = remaining runtime - t
@@ -112,7 +112,7 @@ CONTENTS
- When the current time is equal to the replenishment time of a
throttled task, the scheduling deadline and the remaining runtime are
- updated as
+ updated as::
scheduling deadline = scheduling deadline + period
remaining runtime = remaining runtime + runtime
@@ -129,7 +129,7 @@ CONTENTS
Reclamation of Unused Bandwidth) algorithm [15, 16, 17] and it is enabled
when flag SCHED_FLAG_RECLAIM is set.
- The following diagram illustrates the state names for tasks handled by GRUB:
+ The following diagram illustrates the state names for tasks handled by GRUB::
------------
(d) | Active |
@@ -168,7 +168,7 @@ CONTENTS
breaking the real-time guarantees.
The 0-lag time for a task entering the ActiveNonContending state is
- computed as
+ computed as::
(runtime * dl_period)
deadline - ---------------------
@@ -183,7 +183,7 @@ CONTENTS
the task's utilization must be removed from the previous runqueue's active
utilization and must be added to the new runqueue's active utilization.
In order to avoid races between a task waking up on a runqueue while the
- "inactive timer" is running on a different CPU, the "dl_non_contending"
+ "inactive timer" is running on a different CPU, the "dl_non_contending"
flag is used to indicate that a task is not on a runqueue but is active
(so, the flag is set when the task blocks and is cleared when the
"inactive timer" fires or when the task wakes up).
@@ -222,36 +222,36 @@ CONTENTS
Let's now see a trivial example of two deadline tasks with runtime equal
- to 4 and period equal to 8 (i.e., bandwidth equal to 0.5):
+ to 4 and period equal to 8 (i.e., bandwidth equal to 0.5)::
- A Task T1
- |
- | |
- | |
- |-------- |----
- | | V
- |---|---|---|---|---|---|---|---|--------->t
- 0 1 2 3 4 5 6 7 8
+ A Task T1
+ |
+ | |
+ | |
+ |-------- |----
+ | | V
+ |---|---|---|---|---|---|---|---|--------->t
+ 0 1 2 3 4 5 6 7 8
- A Task T2
- |
- | |
- | |
- | ------------------------|
- | | V
- |---|---|---|---|---|---|---|---|--------->t
- 0 1 2 3 4 5 6 7 8
+ A Task T2
+ |
+ | |
+ | |
+ | ------------------------|
+ | | V
+ |---|---|---|---|---|---|---|---|--------->t
+ 0 1 2 3 4 5 6 7 8
- A running_bw
- |
- 1 ----------------- ------
- | | |
- 0.5- -----------------
- | |
- |---|---|---|---|---|---|---|---|--------->t
- 0 1 2 3 4 5 6 7 8
+ A running_bw
+ |
+ 1 ----------------- ------
+ | | |
+ 0.5- -----------------
+ | |
+ |---|---|---|---|---|---|---|---|--------->t
+ 0 1 2 3 4 5 6 7 8
- Time t = 0:
@@ -284,7 +284,7 @@ CONTENTS
2.3 Energy-aware scheduling
-------------------------
+---------------------------
When cpufreq's schedutil governor is selected, SCHED_DEADLINE implements the
GRUB-PA [19] algorithm, reducing the CPU operating frequency to the minimum
@@ -299,15 +299,20 @@ CONTENTS
3. Scheduling Real-Time Tasks
=============================
- * BIG FAT WARNING ******************************************************
- *
- * This section contains a (not-thorough) summary on classical deadline
- * scheduling theory, and how it applies to SCHED_DEADLINE.
- * The reader can "safely" skip to Section 4 if only interested in seeing
- * how the scheduling policy can be used. Anyway, we strongly recommend
- * to come back here and continue reading (once the urge for testing is
- * satisfied :P) to be sure of fully understanding all technical details.
- ************************************************************************
+
+
+ .. BIG FAT WARNING ******************************************************
+
+ .. warning::
+
+ This section contains a (not-thorough) summary on classical deadline
+ scheduling theory, and how it applies to SCHED_DEADLINE.
+ The reader can "safely" skip to Section 4 if only interested in seeing
+ how the scheduling policy can be used. Anyway, we strongly recommend
+ to come back here and continue reading (once the urge for testing is
+ satisfied :P) to be sure of fully understanding all technical details.
+
+ .. ************************************************************************
There are no limitations on what kind of task can exploit this new
scheduling discipline, even if it must be said that it is particularly
@@ -329,6 +334,7 @@ CONTENTS
sporadic with minimum inter-arrival time P is r_{j+1} >= r_j + P. Finally,
d_j = r_j + D, where D is the task's relative deadline.
Summing up, a real-time task can be described as
+
Task = (WCET, D, P)
The utilization of a real-time task is defined as the ratio between its
@@ -352,13 +358,15 @@ CONTENTS
between the finishing time of a job and its absolute deadline).
More precisely, it can be proven that using a global EDF scheduler the
maximum tardiness of each task is smaller or equal than
+
((M − 1) · WCET_max − WCET_min)/(M − (M − 2) · U_max) + WCET_max
+
where WCET_max = max{WCET_i} is the maximum WCET, WCET_min=min{WCET_i}
is the minimum WCET, and U_max = max{WCET_i/P_i} is the maximum
utilization[12].
3.2 Schedulability Analysis for Uniprocessor Systems
-------------------------
+----------------------------------------------------
If M=1 (uniprocessor system), or in case of partitioned scheduling (each
real-time task is statically assigned to one and only one CPU), it is
@@ -370,7 +378,9 @@ CONTENTS
a task as WCET_i/min{D_i,P_i}, and EDF is able to respect all the deadlines
of all the tasks running on a CPU if the sum of the densities of the tasks
running on such a CPU is smaller or equal than 1:
+
sum(WCET_i / min{D_i, P_i}) <= 1
+
It is important to notice that this condition is only sufficient, and not
necessary: there are task sets that are schedulable, but do not respect the
condition. For example, consider the task set {Task_1,Task_2} composed by
@@ -379,7 +389,9 @@ CONTENTS
(Task_1 is scheduled as soon as it is released, and finishes just in time
to respect its deadline; Task_2 is scheduled immediately after Task_1, hence
its response time cannot be larger than 50ms + 10ms = 60ms) even if
+
50 / min{50,100} + 10 / min{100, 100} = 50 / 50 + 10 / 100 = 1.1
+
Of course it is possible to test the exact schedulability of tasks with
D_i != P_i (checking a condition that is both sufficient and necessary),
but this cannot be done by comparing the total utilization or density with
@@ -399,7 +411,7 @@ CONTENTS
4 Linux uses an admission test based on the tasks' utilizations.
3.3 Schedulability Analysis for Multiprocessor Systems
-------------------------
+------------------------------------------------------
On multiprocessor systems with global EDF scheduling (non partitioned
systems), a sufficient test for schedulability can not be based on the
@@ -428,7 +440,9 @@ CONTENTS
between total utilization (or density) and a fixed constant. If all tasks
have D_i = P_i, a sufficient schedulability condition can be expressed in
a simple way:
+
sum(WCET_i / P_i) <= M - (M - 1) · U_max
+
where U_max = max{WCET_i / P_i}[10]. Notice that for U_max = 1,
M - (M - 1) · U_max becomes M - M + 1 = 1 and this schedulability condition
just confirms the Dhall's effect. A more complete survey of the literature
@@ -447,7 +461,7 @@ CONTENTS
the tasks are limited.
3.4 Relationship with SCHED_DEADLINE Parameters
-------------------------
+-----------------------------------------------
Finally, it is important to understand the relationship between the
SCHED_DEADLINE scheduling parameters described in Section 2 (runtime,
@@ -473,6 +487,7 @@ CONTENTS
this task, as it is not possible to respect its temporal constraints.
References:
+
1 - C. L. Liu and J. W. Layland. Scheduling algorithms for multiprogram-
ming in a hard-real-time environment. Journal of the Association for
Computing Machinery, 20(1), 1973.
@@ -550,7 +565,7 @@ CONTENTS
The interface used to control the CPU bandwidth that can be allocated
to -deadline tasks is similar to the one already used for -rt
tasks with real-time group scheduling (a.k.a. RT-throttling - see
- Documentation/scheduler/sched-rt-group.txt), and is based on readable/
+ Documentation/scheduler/sched-rt-group.rst), and is based on readable/
writable control files located in procfs (for system wide settings).
Notice that per-group settings (controlled through cgroupfs) are still not
defined for -deadline tasks, because more discussion is needed in order to
@@ -596,11 +611,13 @@ CONTENTS
Specifying a periodic/sporadic task that executes for a given amount of
runtime at each instance, and that is scheduled according to the urgency of
its own timing constraints needs, in general, a way of declaring:
+
- a (maximum/typical) instance execution time,
- a minimum interval between consecutive instances,
- a time constraint by which each instance must be completed.
Therefore:
+
* a new struct sched_attr, containing all the necessary fields is
provided;
* the new scheduling related syscalls that manipulate it, i.e.,
@@ -658,21 +675,21 @@ CONTENTS
------------------------------------
An example of a simple configuration (pin a -deadline task to CPU0)
- follows (rt-app is used to create a -deadline task).
+ follows (rt-app is used to create a -deadline task)::
- mkdir /dev/cpuset
- mount -t cgroup -o cpuset cpuset /dev/cpuset
- cd /dev/cpuset
- mkdir cpu0
- echo 0 > cpu0/cpuset.cpus
- echo 0 > cpu0/cpuset.mems
- echo 1 > cpuset.cpu_exclusive
- echo 0 > cpuset.sched_load_balance
- echo 1 > cpu0/cpuset.cpu_exclusive
- echo 1 > cpu0/cpuset.mem_exclusive
- echo $$ > cpu0/tasks
- rt-app -t 100000:10000:d:0 -D5 (it is now actually superfluous to specify
- task affinity)
+ mkdir /dev/cpuset
+ mount -t cgroup -o cpuset cpuset /dev/cpuset
+ cd /dev/cpuset
+ mkdir cpu0
+ echo 0 > cpu0/cpuset.cpus
+ echo 0 > cpu0/cpuset.mems
+ echo 1 > cpuset.cpu_exclusive
+ echo 0 > cpuset.sched_load_balance
+ echo 1 > cpu0/cpuset.cpu_exclusive
+ echo 1 > cpu0/cpuset.mem_exclusive
+ echo $$ > cpu0/tasks
+ rt-app -t 100000:10000:d:0 -D5 # it is now actually superfluous to specify
+ # task affinity
6. Future plans
===============
@@ -711,7 +728,7 @@ Appendix A. Test suite
rt-app is available at: https://github.com/scheduler-tools/rt-app.
Thread parameters can be specified from the command line, with something like
- this:
+ this::
# rt-app -t 100000:10000:d -t 150000:20000:f:10 -D5
@@ -721,27 +738,27 @@ Appendix A. Test suite
of 5 seconds.
More interestingly, configurations can be described with a json file that
- can be passed as input to rt-app with something like this:
+ can be passed as input to rt-app with something like this::
# rt-app my_config.json
The parameters that can be specified with the second method are a superset
of the command line options. Please refer to rt-app documentation for more
- details (<rt-app-sources>/doc/*.json).
+ details (`<rt-app-sources>/doc/*.json`).
The second testing application is a modification of schedtool, called
schedtool-dl, which can be used to setup SCHED_DEADLINE parameters for a
certain pid/application. schedtool-dl is available at:
https://github.com/scheduler-tools/schedtool-dl.git.
- The usage is straightforward:
+ The usage is straightforward::
# schedtool -E -t 10000000:100000000 -e ./my_cpuhog_app
With this, my_cpuhog_app is put to run inside a SCHED_DEADLINE reservation
of 10ms every 100ms (note that parameters are expressed in microseconds).
You can also use schedtool to create a reservation for an already running
- application, given that you know its pid:
+ application, given that you know its pid::
# schedtool -E -t 10000000:100000000 my_app_pid
@@ -750,43 +767,43 @@ Appendix B. Minimal main()
We provide in what follows a simple (ugly) self-contained code snippet
showing how SCHED_DEADLINE reservations can be created by a real-time
- application developer.
-
- #define _GNU_SOURCE
- #include <unistd.h>
- #include <stdio.h>
- #include <stdlib.h>
- #include <string.h>
- #include <time.h>
- #include <linux/unistd.h>
- #include <linux/kernel.h>
- #include <linux/types.h>
- #include <sys/syscall.h>
- #include <pthread.h>
-
- #define gettid() syscall(__NR_gettid)
-
- #define SCHED_DEADLINE 6
-
- /* XXX use the proper syscall numbers */
- #ifdef __x86_64__
- #define __NR_sched_setattr 314
- #define __NR_sched_getattr 315
- #endif
-
- #ifdef __i386__
- #define __NR_sched_setattr 351
- #define __NR_sched_getattr 352
- #endif
-
- #ifdef __arm__
- #define __NR_sched_setattr 380
- #define __NR_sched_getattr 381
- #endif
-
- static volatile int done;
-
- struct sched_attr {
+ application developer::
+
+ #define _GNU_SOURCE
+ #include <unistd.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <time.h>
+ #include <linux/unistd.h>
+ #include <linux/kernel.h>
+ #include <linux/types.h>
+ #include <sys/syscall.h>
+ #include <pthread.h>
+
+ #define gettid() syscall(__NR_gettid)
+
+ #define SCHED_DEADLINE 6
+
+ /* XXX use the proper syscall numbers */
+ #ifdef __x86_64__
+ #define __NR_sched_setattr 314
+ #define __NR_sched_getattr 315
+ #endif
+
+ #ifdef __i386__
+ #define __NR_sched_setattr 351
+ #define __NR_sched_getattr 352
+ #endif
+
+ #ifdef __arm__
+ #define __NR_sched_setattr 380
+ #define __NR_sched_getattr 381
+ #endif
+
+ static volatile int done;
+
+ struct sched_attr {
__u32 size;
__u32 sched_policy;
@@ -802,25 +819,25 @@ Appendix B. Minimal main()
__u64 sched_runtime;
__u64 sched_deadline;
__u64 sched_period;
- };
+ };
- int sched_setattr(pid_t pid,
+ int sched_setattr(pid_t pid,
const struct sched_attr *attr,
unsigned int flags)
- {
+ {
return syscall(__NR_sched_setattr, pid, attr, flags);
- }
+ }
- int sched_getattr(pid_t pid,
+ int sched_getattr(pid_t pid,
struct sched_attr *attr,
unsigned int size,
unsigned int flags)
- {
+ {
return syscall(__NR_sched_getattr, pid, attr, size, flags);
- }
+ }
- void *run_deadline(void *data)
- {
+ void *run_deadline(void *data)
+ {
struct sched_attr attr;
int x = 0;
int ret;
@@ -851,10 +868,10 @@ Appendix B. Minimal main()
printf("deadline thread dies [%ld]\n", gettid());
return NULL;
- }
+ }
- int main (int argc, char **argv)
- {
+ int main (int argc, char **argv)
+ {
pthread_t thread;
printf("main thread [%ld]\n", gettid());
@@ -868,4 +885,4 @@ Appendix B. Minimal main()
printf("main dies [%ld]\n", gettid());
return 0;
- }
+ }
diff --git a/Documentation/scheduler/sched-design-CFS.txt b/Documentation/scheduler/sched-design-CFS.rst
similarity index 97%
rename from Documentation/scheduler/sched-design-CFS.txt
rename to Documentation/scheduler/sched-design-CFS.rst
index d1328890ef28..53b30d1967cf 100644
--- a/Documentation/scheduler/sched-design-CFS.txt
+++ b/Documentation/scheduler/sched-design-CFS.rst
@@ -1,9 +1,10 @@
- =============
- CFS Scheduler
- =============
+=============
+CFS Scheduler
+=============
1. OVERVIEW
+============
CFS stands for "Completely Fair Scheduler," and is the new "desktop" process
scheduler implemented by Ingo Molnar and merged in Linux 2.6.23. It is the
@@ -27,6 +28,7 @@ is its actual runtime normalized to the total number of running tasks.
2. FEW IMPLEMENTATION DETAILS
+==============================
In CFS the virtual runtime is expressed and tracked via the per-task
p->se.vruntime (nanosec-unit) value. This way, it's possible to accurately
@@ -49,6 +51,7 @@ algorithm variants to recognize sleepers.
3. THE RBTREE
+==============
CFS's design is quite radical: it does not use the old data structures for the
runqueues, but it uses a time-ordered rbtree to build a "timeline" of future
@@ -84,6 +87,7 @@ picked and the current task is preempted.
4. SOME FEATURES OF CFS
+========================
CFS uses nanosecond granularity accounting and does not rely on any jiffies or
other HZ detail. Thus the CFS scheduler has no notion of "timeslices" in the
@@ -113,6 +117,7 @@ result.
5. Scheduling policies
+======================
CFS implements three scheduling policies:
@@ -137,6 +142,7 @@ SCHED_IDLE.
6. SCHEDULING CLASSES
+======================
The new CFS scheduler has been designed in such a way to introduce "Scheduling
Classes," an extensible hierarchy of scheduler modules. These modules
@@ -197,6 +203,7 @@ This is the (partial) list of the hooks:
7. GROUP SCHEDULER EXTENSIONS TO CFS
+=====================================
Normally, the scheduler operates on individual tasks and strives to provide
fair CPU time to each task. Sometimes, it may be desirable to group tasks and
@@ -219,7 +226,7 @@ SCHED_BATCH) tasks.
When CONFIG_FAIR_GROUP_SCHED is defined, a "cpu.shares" file is created for each
group created using the pseudo filesystem. See example steps below to create
-task groups and modify their CPU share using the "cgroups" pseudo filesystem.
+task groups and modify their CPU share using the "cgroups" pseudo filesystem::
# mount -t tmpfs cgroup_root /sys/fs/cgroup
# mkdir /sys/fs/cgroup/cpu
diff --git a/Documentation/scheduler/sched-domains.txt b/Documentation/scheduler/sched-domains.rst
similarity index 97%
rename from Documentation/scheduler/sched-domains.txt
rename to Documentation/scheduler/sched-domains.rst
index 4af80b1c05aa..f7504226f445 100644
--- a/Documentation/scheduler/sched-domains.txt
+++ b/Documentation/scheduler/sched-domains.rst
@@ -1,3 +1,7 @@
+=================
+Scheduler Domains
+=================
+
Each CPU has a "base" scheduling domain (struct sched_domain). The domain
hierarchy is built from these base domains via the ->parent pointer. ->parent
MUST be NULL terminated, and domain structures should be per-CPU as they are
@@ -46,7 +50,9 @@ CPU's runqueue and the newly found busiest one and starts moving tasks from it
to our runqueue. The exact number of tasks amounts to an imbalance previously
computed while iterating over this sched domain's groups.
-*** Implementing sched domains ***
+Implementing sched domains
+==========================
+
The "base" domain will "span" the first level of the hierarchy. In the case
of SMT, you'll span all siblings of the physical CPU, with each group being
a single virtual CPU.
diff --git a/Documentation/scheduler/sched-energy.txt b/Documentation/scheduler/sched-energy.rst
similarity index 96%
rename from Documentation/scheduler/sched-energy.txt
rename to Documentation/scheduler/sched-energy.rst
index d97207b9accb..9580c57a52bc 100644
--- a/Documentation/scheduler/sched-energy.txt
+++ b/Documentation/scheduler/sched-energy.rst
@@ -1,6 +1,6 @@
- =======================
- Energy Aware Scheduling
- =======================
+=======================
+Energy Aware Scheduling
+=======================
1. Introduction
---------------
@@ -12,7 +12,7 @@ with a minimal impact on throughput. This document aims at providing an
introduction on how EAS works, what are the main design decisions behind it, and
details what is needed to get it to run.
-Before going any further, please note that at the time of writing:
+Before going any further, please note that at the time of writing::
/!\ EAS does not support platforms with symmetric CPU topologies /!\
@@ -33,13 +33,13 @@ To make it clear from the start:
- power = energy/time = [joule/second] = [watt]
The goal of EAS is to minimize energy, while still getting the job done. That
-is, we want to maximize:
+is, we want to maximize::
performance [inst/s]
--------------------
power [W]
-which is equivalent to minimizing:
+which is equivalent to minimizing::
energy [J]
-----------
@@ -97,7 +97,7 @@ domains can contain duplicate elements.
Example 1.
Let us consider a platform with 12 CPUs, split in 3 performance domains
- (pd0, pd4 and pd8), organized as follows:
+ (pd0, pd4 and pd8), organized as follows::
CPUs: 0 1 2 3 4 5 6 7 8 9 10 11
PDs: |--pd0--|--pd4--|---pd8---|
@@ -108,6 +108,7 @@ Example 1.
containing 6 CPUs. The two root domains are denoted rd1 and rd2 in the
above figure. Since pd4 intersects with both rd1 and rd2, it will be
present in the linked list '->pd' attached to each of them:
+
* rd1->pd: pd0 -> pd4
* rd2->pd: pd4 -> pd8
@@ -159,9 +160,9 @@ Example 2.
Each performance domain has three Operating Performance Points (OPPs).
The CPU capacity and power cost associated with each OPP is listed in
the Energy Model table. The util_avg of P is shown on the figures
- below as 'PP'.
+ below as 'PP'::
- CPU util.
+ CPU util.
1024 - - - - - - - Energy Model
+-----------+-------------+
| Little | Big |
@@ -188,8 +189,7 @@ Example 2.
(which is coherent with the behaviour of the schedutil CPUFreq
governor, see Section 6. for more details on this topic).
- Case 1. P is migrated to CPU1
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ **Case 1. P is migrated to CPU1**::
1024 - - - - - - -
@@ -207,8 +207,7 @@ Example 2.
CPU0 CPU1 CPU2 CPU3
- Case 2. P is migrated to CPU3
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ **Case 2. P is migrated to CPU3**::
1024 - - - - - - -
@@ -226,8 +225,7 @@ Example 2.
CPU0 CPU1 CPU2 CPU3
- Case 3. P stays on prev_cpu / CPU 0
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ **Case 3. P stays on prev_cpu / CPU 0**::
1024 - - - - - - -
@@ -324,7 +322,9 @@ hardware properties and on other features of the kernel being enabled. This
section lists these dependencies and provides hints as to how they can be met.
- 6.1 - Asymmetric CPU topology
+6.1 - Asymmetric CPU topology
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
As mentioned in the introduction, EAS is only supported on platforms with
asymmetric CPU topologies for now. This requirement is checked at run-time by
@@ -347,7 +347,8 @@ significant savings on SMP platforms have been observed yet. This restriction
could be amended in the future if proven otherwise.
- 6.2 - Energy Model presence
+6.2 - Energy Model presence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
EAS uses the EM of a platform to estimate the impact of scheduling decisions on
energy. So, your platform must provide power cost tables to the EM framework in
@@ -358,7 +359,8 @@ Please also note that the scheduling domains need to be re-built after the
EM has been registered in order to start EAS.
- 6.3 - Energy Model complexity
+6.3 - Energy Model complexity
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The task wake-up path is very latency-sensitive. When the EM of a platform is
too complex (too many CPUs, too many performance domains, too many performance
@@ -388,7 +390,8 @@ two possible options:
hence enabling it to cope with larger EMs in reasonable time.
- 6.4 - Schedutil governor
+6.4 - Schedutil governor
+^^^^^^^^^^^^^^^^^^^^^^^^
EAS tries to predict at which OPP will the CPUs be running in the close future
in order to estimate their energy consumption. To do so, it is assumed that OPPs
@@ -405,7 +408,8 @@ frequency requests and energy predictions.
Using EAS with any other governor than schedutil is not supported.
- 6.5 Scale-invariant utilization signals
+6.5 Scale-invariant utilization signals
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to make accurate prediction across CPUs and for all performance
states, EAS needs frequency-invariant and CPU-invariant PELT signals. These can
@@ -416,7 +420,8 @@ Using EAS on a platform that doesn't implement these two callbacks is not
supported.
- 6.6 Multithreading (SMT)
+6.6 Multithreading (SMT)
+^^^^^^^^^^^^^^^^^^^^^^^^
EAS in its current form is SMT unaware and is not able to leverage
multithreaded hardware to save energy. EAS considers threads as independent
diff --git a/Documentation/scheduler/sched-nice-design.txt b/Documentation/scheduler/sched-nice-design.rst
similarity index 98%
rename from Documentation/scheduler/sched-nice-design.txt
rename to Documentation/scheduler/sched-nice-design.rst
index 3ac1e46d5365..0571f1b47e64 100644
--- a/Documentation/scheduler/sched-nice-design.txt
+++ b/Documentation/scheduler/sched-nice-design.rst
@@ -1,3 +1,7 @@
+=====================
+Scheduler Nice Design
+=====================
+
This document explains the thinking about the revamped and streamlined
nice-levels implementation in the new Linux scheduler.
@@ -14,7 +18,7 @@ much stronger than they were before in 2.4 (and people were happy about
that change), and we also intentionally calibrated the linear timeslice
rule so that nice +19 level would be _exactly_ 1 jiffy. To better
understand it, the timeslice graph went like this (cheesy ASCII art
-alert!):
+alert!)::
A
diff --git a/Documentation/scheduler/sched-rt-group.txt b/Documentation/scheduler/sched-rt-group.rst
similarity index 95%
rename from Documentation/scheduler/sched-rt-group.txt
rename to Documentation/scheduler/sched-rt-group.rst
index c09f7a3fee66..d27d3f3712fd 100644
--- a/Documentation/scheduler/sched-rt-group.txt
+++ b/Documentation/scheduler/sched-rt-group.rst
@@ -1,18 +1,18 @@
- Real-Time group scheduling
- --------------------------
+==========================
+Real-Time group scheduling
+==========================
-CONTENTS
-========
+.. CONTENTS
-0. WARNING
-1. Overview
- 1.1 The problem
- 1.2 The solution
-2. The interface
- 2.1 System-wide settings
- 2.2 Default behaviour
- 2.3 Basis for grouping tasks
-3. Future plans
+ 0. WARNING
+ 1. Overview
+ 1.1 The problem
+ 1.2 The solution
+ 2. The interface
+ 2.1 System-wide settings
+ 2.2 Default behaviour
+ 2.3 Basis for grouping tasks
+ 3. Future plans
0. WARNING
@@ -159,9 +159,11 @@ Consider two sibling groups A and B; both have 50% bandwidth, but A's
period is twice the length of B's.
* group A: period=100000us, runtime=50000us
+
- this runs for 0.05s once every 0.1s
* group B: period= 50000us, runtime=25000us
+
- this runs for 0.025s twice every 0.1s (or once every 0.05 sec).
This means that currently a while (1) loop in A will run for the full period of
diff --git a/Documentation/scheduler/sched-stats.txt b/Documentation/scheduler/sched-stats.rst
similarity index 91%
rename from Documentation/scheduler/sched-stats.txt
rename to Documentation/scheduler/sched-stats.rst
index 8259b34a66ae..0cb0aa714545 100644
--- a/Documentation/scheduler/sched-stats.txt
+++ b/Documentation/scheduler/sched-stats.rst
@@ -1,3 +1,7 @@
+====================
+Scheduler Statistics
+====================
+
Version 15 of schedstats dropped counters for some sched_yield:
yld_exp_empty, yld_act_empty and yld_both_empty. Otherwise, it is
identical to version 14.
@@ -35,19 +39,23 @@ CPU statistics
cpu<N> 1 2 3 4 5 6 7 8 9
First field is a sched_yield() statistic:
+
1) # of times sched_yield() was called
Next three are schedule() statistics:
+
2) This field is a legacy array expiration count field used in the O(1)
scheduler. We kept it for ABI compatibility, but it is always set to zero.
3) # of times schedule() was called
4) # of times schedule() left the processor idle
Next two are try_to_wake_up() statistics:
+
5) # of times try_to_wake_up() was called
6) # of times try_to_wake_up() was called to wake up the local cpu
Next three are statistics describing scheduling latency:
+
7) sum of all time spent running by tasks on this processor (in jiffies)
8) sum of all time spent waiting to run by tasks on this processor (in
jiffies)
@@ -67,24 +75,23 @@ The first field is a bit mask indicating what cpus this domain operates over.
The next 24 are a variety of load_balance() statistics in grouped into types
of idleness (idle, busy, and newly idle):
- 1) # of times in this domain load_balance() was called when the
+ 1) # of times in this domain load_balance() was called when the
cpu was idle
- 2) # of times in this domain load_balance() checked but found
+ 2) # of times in this domain load_balance() checked but found
the load did not require balancing when the cpu was idle
- 3) # of times in this domain load_balance() tried to move one or
+ 3) # of times in this domain load_balance() tried to move one or
more tasks and failed, when the cpu was idle
- 4) sum of imbalances discovered (if any) with each call to
+ 4) sum of imbalances discovered (if any) with each call to
load_balance() in this domain when the cpu was idle
- 5) # of times in this domain pull_task() was called when the cpu
+ 5) # of times in this domain pull_task() was called when the cpu
was idle
- 6) # of times in this domain pull_task() was called even though
+ 6) # of times in this domain pull_task() was called even though
the target task was cache-hot when idle
- 7) # of times in this domain load_balance() was called but did
+ 7) # of times in this domain load_balance() was called but did
not find a busier queue while the cpu was idle
- 8) # of times in this domain a busier queue was found while the
+ 8) # of times in this domain a busier queue was found while the
cpu was idle but no busier group was found
-
- 9) # of times in this domain load_balance() was called when the
+ 9) # of times in this domain load_balance() was called when the
cpu was busy
10) # of times in this domain load_balance() checked but found the
load did not require balancing when busy
@@ -117,21 +124,25 @@ of idleness (idle, busy, and newly idle):
was just becoming idle but no busier group was found
Next three are active_load_balance() statistics:
+
25) # of times active_load_balance() was called
26) # of times active_load_balance() tried to move a task and failed
27) # of times active_load_balance() successfully moved a task
Next three are sched_balance_exec() statistics:
+
28) sbe_cnt is not used
29) sbe_balanced is not used
30) sbe_pushed is not used
Next three are sched_balance_fork() statistics:
+
31) sbf_cnt is not used
32) sbf_balanced is not used
33) sbf_pushed is not used
Next three are try_to_wake_up() statistics:
+
34) # of times in this domain try_to_wake_up() awoke a task that
last ran on a different cpu in this domain
35) # of times in this domain try_to_wake_up() moved a task to the
@@ -139,10 +150,11 @@ of idleness (idle, busy, and newly idle):
36) # of times in this domain try_to_wake_up() started passive balancing
/proc/<pid>/schedstat
-----------------
+---------------------
schedstats also adds a new /proc/<pid>/schedstat file to include some of
the same information on a per-process level. There are three fields in
this file correlating for that process to:
+
1) time spent on the cpu
2) time spent waiting on a runqueue
3) # of timeslices run on this cpu
@@ -151,4 +163,5 @@ A program could be easily written to make use of these extra fields to
report on how well a particular process or set of processes is faring
under the scheduler's policies. A simple version of such a program is
available at
+
http://eaglet.rain.com/rick/linux/schedstat/v12/latency.c
diff --git a/Documentation/scheduler/text_files.rst b/Documentation/scheduler/text_files.rst
new file mode 100644
index 000000000000..0bc50307b241
--- /dev/null
+++ b/Documentation/scheduler/text_files.rst
@@ -0,0 +1,5 @@
+Scheduler pelt c program
+------------------------
+
+.. literalinclude:: sched-pelt.c
+ :language: c
diff --git a/Documentation/vm/numa.rst b/Documentation/vm/numa.rst
index 0d830edae8fe..130f3cfa1c19 100644
--- a/Documentation/vm/numa.rst
+++ b/Documentation/vm/numa.rst
@@ -99,7 +99,7 @@ Local allocation will tend to keep subsequent access to the allocated memory
as long as the task on whose behalf the kernel allocated some memory does not
later migrate away from that memory. The Linux scheduler is aware of the
NUMA topology of the platform--embodied in the "scheduling domains" data
-structures [see Documentation/scheduler/sched-domains.txt]--and the scheduler
+structures [see Documentation/scheduler/sched-domains.rst]--and the scheduler
attempts to minimize task migration to distant scheduling domains. However,
the scheduler does not take a task's NUMA footprint into account directly.
Thus, under sufficient imbalance, tasks can migrate between nodes, remote
diff --git a/init/Kconfig b/init/Kconfig
index ab41ffa08d79..6db89d4155d8 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -734,7 +734,7 @@ menuconfig CGROUPS
use with process control subsystems such as Cpusets, CFS, memory
controls or device isolation.
See
- - Documentation/scheduler/sched-design-CFS.txt (CFS)
+ - Documentation/scheduler/sched-design-CFS.rst (CFS)
- Documentation/cgroup-v1/ (features for grouping, isolation
and resource control)
@@ -835,7 +835,7 @@ config CFS_BANDWIDTH
tasks running within the fair group scheduler. Groups with no limit
set are considered to be unconstrained and will run with no
restriction.
- See Documentation/scheduler/sched-bwc.txt for more information.
+ See Documentation/scheduler/sched-bwc.rst for more information.
config RT_GROUP_SCHED
bool "Group scheduling for SCHED_RR/FIFO"
@@ -846,7 +846,7 @@ config RT_GROUP_SCHED
to task groups. If enabled, it will also make it impossible to
schedule realtime tasks for non-root users until you allocate
realtime bandwidth for them.
- See Documentation/scheduler/sched-rt-group.txt for more information.
+ See Documentation/scheduler/sched-rt-group.rst for more information.
endif #CGROUP_SCHED
diff --git a/kernel/sched/deadline.c b/kernel/sched/deadline.c
index c1ef30861068..2df20e15b576 100644
--- a/kernel/sched/deadline.c
+++ b/kernel/sched/deadline.c
@@ -726,7 +726,7 @@ static void replenish_dl_entity(struct sched_dl_entity *dl_se,
* refill the runtime and set the deadline a period in the future,
* because keeping the current (absolute) deadline of the task would
* result in breaking guarantees promised to other tasks (refer to
- * Documentation/scheduler/sched-deadline.txt for more information).
+ * Documentation/scheduler/sched-deadline.rst for more information).
*
* This function returns true if:
*
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* [PATCH v4 28/28] docs: EDID/HOWTO.txt: convert it and rename to howto.rst
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (20 preceding siblings ...)
2019-06-12 17:53 ` [PATCH v4 27/28] docs: scheduler: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 17:53 ` Mauro Carvalho Chehab
[not found] ` <fac44e1fbab5ea755a93601a4fdfa34fcc57ae9e.1560361364.git.mchehab+samsung@kernel.org>
` (2 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:53 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Maarten Lankhorst, Maxime Ripard, Sean Paul,
David Airlie, Daniel Vetter, dri-devel
Sphinx need to know when a paragraph ends. So, do some adjustments
at the file for it to be properly parsed.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
that's said, I believe that this file should be moved to the
GPU/DRM documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/EDID/{HOWTO.txt => howto.rst} | 31 ++++++++++++-------
.../admin-guide/kernel-parameters.txt | 2 +-
drivers/gpu/drm/Kconfig | 2 +-
3 files changed, 22 insertions(+), 13 deletions(-)
rename Documentation/EDID/{HOWTO.txt => howto.rst} (83%)
diff --git a/Documentation/EDID/HOWTO.txt b/Documentation/EDID/howto.rst
similarity index 83%
rename from Documentation/EDID/HOWTO.txt
rename to Documentation/EDID/howto.rst
index 539871c3b785..725fd49a88ca 100644
--- a/Documentation/EDID/HOWTO.txt
+++ b/Documentation/EDID/howto.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+====
+EDID
+====
+
In the good old days when graphics parameters were configured explicitly
in a file called xorg.conf, even broken hardware could be managed.
@@ -34,16 +40,19 @@ Makefile. Please note that the EDID data structure expects the timing
values in a different way as compared to the standard X11 format.
X11:
-HTimings: hdisp hsyncstart hsyncend htotal
-VTimings: vdisp vsyncstart vsyncend vtotal
+ HTimings:
+ hdisp hsyncstart hsyncend htotal
+ VTimings:
+ vdisp vsyncstart vsyncend vtotal
-EDID:
-#define XPIX hdisp
-#define XBLANK htotal-hdisp
-#define XOFFSET hsyncstart-hdisp
-#define XPULSE hsyncend-hsyncstart
+EDID::
-#define YPIX vdisp
-#define YBLANK vtotal-vdisp
-#define YOFFSET vsyncstart-vdisp
-#define YPULSE vsyncend-vsyncstart
+ #define XPIX hdisp
+ #define XBLANK htotal-hdisp
+ #define XOFFSET hsyncstart-hdisp
+ #define XPULSE hsyncend-hsyncstart
+
+ #define YPIX vdisp
+ #define YBLANK vtotal-vdisp
+ #define YOFFSET vsyncstart-vdisp
+ #define YPULSE vsyncend-vsyncstart
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 3d072ca532bb..3faf37b8b001 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -930,7 +930,7 @@
edid/1680x1050.bin, or edid/1920x1080.bin is given
and no file with the same name exists. Details and
instructions how to build your own EDID data are
- available in Documentation/EDID/HOWTO.txt. An EDID
+ available in Documentation/EDID/howto.rst. An EDID
data set will only be used for a particular connector,
if its name and a colon are prepended to the EDID
name. Each connector may use a unique EDID data
diff --git a/drivers/gpu/drm/Kconfig b/drivers/gpu/drm/Kconfig
index 6b34949416b1..c3a6dd284c91 100644
--- a/drivers/gpu/drm/Kconfig
+++ b/drivers/gpu/drm/Kconfig
@@ -141,7 +141,7 @@ config DRM_LOAD_EDID_FIRMWARE
monitor are unable to provide appropriate EDID data. Since this
feature is provided as a workaround for broken hardware, the
default case is N. Details and instructions how to build your own
- EDID data are given in Documentation/EDID/HOWTO.txt.
+ EDID data are given in Documentation/EDID/howto.rst.
config DRM_DP_CEC
bool "Enable DisplayPort CEC-Tunneling-over-AUX HDMI support"
--
2.21.0
^ permalink raw reply related [flat|nested] 39+ messages in thread
* Re: [PATCH v4 24/28] docs: timers: convert docs to ReST and rename to *.rst
2019-06-12 17:53 ` [PATCH v4 24/28] docs: timers: " Mauro Carvalho Chehab
@ 2019-06-12 18:25 ` Mark Brown
0 siblings, 0 replies; 39+ messages in thread
From: Mark Brown @ 2019-06-12 18:25 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Thomas Gleixner, Clemens Ladisch,
Antti Palosaari, Liam Girdwood, Andy Whitcroft, Joe Perches,
Jaroslav Kysela, Takashi Iwai, alsa-devel
[-- Attachment #1: Type: text/plain, Size: 288 bytes --]
On Wed, Jun 12, 2019 at 02:53:00PM -0300, Mauro Carvalho Chehab wrote:
> The conversion here is really trivial: just a bunch of title
> markups and very few puntual changes is enough to make it to
> be parsed by Sphinx and generate a nice html.
Acked-by: Mark Brown <broonie@kernel.org>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst
[not found] ` <fac44e1fbab5ea755a93601a4fdfa34fcc57ae9e.1560361364.git.mchehab+samsung@kernel.org>
@ 2019-06-13 0:25 ` Srivatsa S. Bhat
2019-06-13 9:58 ` Mauro Carvalho Chehab
[not found] ` <72d1f8f360d395958dd0b49165fc51b58801f57e.1560420621.git.mchehab+samsung@kernel.org>
0 siblings, 2 replies; 39+ messages in thread
From: Srivatsa S. Bhat @ 2019-06-13 0:25 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Sebastian Reichel, Rafael J. Wysocki, Viresh Kumar, Len Brown,
Pavel Machek, Nishanth Menon, Stephen Boyd, Liam Girdwood,
Mark Brown, Mathieu Poirier, Suzuki K Poulose, Harry Wei,
Alex Shi, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
H. Peter Anvin, x86, Jani Nikula, Joonas Lahtinen, Rodrigo Vivi,
David Airlie, Daniel Vetter, Bjorn Helgaas, Johannes Berg,
David S. Miller, linux-pm, linux-arm-kernel, intel-gfx, dri-devel,
linux-pci, linux-wireless, netdev
On 6/12/19 10:52 AM, Mauro Carvalho Chehab wrote:
> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> Acked-by: Mark Brown <broonie@kernel.org>
> ---
[...]
> diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst
> similarity index 90%
> rename from Documentation/power/suspend-and-cpuhotplug.txt
> rename to Documentation/power/suspend-and-cpuhotplug.rst
> index a8751b8df10e..9df664f5423a 100644
> --- a/Documentation/power/suspend-and-cpuhotplug.txt
> +++ b/Documentation/power/suspend-and-cpuhotplug.rst
> @@ -1,10 +1,15 @@
> +====================================================================
> Interaction of Suspend code (S3) with the CPU hotplug infrastructure
> +====================================================================
>
> - (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
> +(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
>
>
> -I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> - infrastructure uses it internally? And where do they share common code?
> +I. Differences between CPU hotplug and Suspend-to-RAM
> +======================================================
> +
> +How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> +infrastructure uses it internally? And where do they share common code?
>
> Well, a picture is worth a thousand words... So ASCII art follows :-)
>
[...]
> @@ -101,7 +108,7 @@ execution during resume):
>
> It is to be noted here that the system_transition_mutex lock is acquired at the very
> beginning, when we are just starting out to suspend, and then released only
> -after the entire cycle is complete (i.e., suspend + resume).
> +after the entire cycle is complete (i.e., suspend + resume)::
>
I think that should be a period, not a colon, because it is clarifying
the text above it (as opposed to referring to the example below it).
Other than that, for suspend-and-cpuhotplug.txt:
Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
Regards,
Srivatsa
VMware Photon OS
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst
2019-06-13 0:25 ` [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst Srivatsa S. Bhat
@ 2019-06-13 9:58 ` Mauro Carvalho Chehab
[not found] ` <72d1f8f360d395958dd0b49165fc51b58801f57e.1560420621.git.mchehab+samsung@kernel.org>
1 sibling, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-13 9:58 UTC (permalink / raw)
To: Srivatsa S. Bhat
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sebastian Reichel, Rafael J. Wysocki,
Viresh Kumar, Len Brown, Pavel Machek, Nishanth Menon,
Stephen Boyd, Liam Girdwood, Mark Brown, Mathieu Poirier,
Suzuki K Poulose, Harry Wei, Alex Shi, Thomas Gleixner,
Ingo Molnar, Borislav Petkov, H. Peter Anvin, x86, Jani Nikula,
Joonas Lahtinen, Rodrigo Vivi, David Airlie, Daniel Vetter,
Bjorn Helgaas, Johannes Berg, David S. Miller, linux-pm,
linux-arm-kernel, intel-gfx, dri-devel, linux-pci, linux-wireless,
netdev
Em Wed, 12 Jun 2019 17:25:39 -0700
"Srivatsa S. Bhat" <srivatsa@csail.mit.edu> escreveu:
> On 6/12/19 10:52 AM, Mauro Carvalho Chehab wrote:
> > Convert the PM documents to ReST, in order to allow them to
> > build with Sphinx.
> >
> > The conversion is actually:
> > - add blank lines and identation in order to identify paragraphs;
> > - fix tables markups;
> > - add some lists markups;
> > - mark literal blocks;
> > - adjust title markups.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> > Acked-by: Mark Brown <broonie@kernel.org>
> > ---
>
> [...]
>
> > diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst
> > similarity index 90%
> > rename from Documentation/power/suspend-and-cpuhotplug.txt
> > rename to Documentation/power/suspend-and-cpuhotplug.rst
> > index a8751b8df10e..9df664f5423a 100644
> > --- a/Documentation/power/suspend-and-cpuhotplug.txt
> > +++ b/Documentation/power/suspend-and-cpuhotplug.rst
> > @@ -1,10 +1,15 @@
> > +====================================================================
> > Interaction of Suspend code (S3) with the CPU hotplug infrastructure
> > +====================================================================
> >
> > - (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
> > +(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
> >
> >
> > -I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> > - infrastructure uses it internally? And where do they share common code?
> > +I. Differences between CPU hotplug and Suspend-to-RAM
> > +======================================================
> > +
> > +How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> > +infrastructure uses it internally? And where do they share common code?
> >
> > Well, a picture is worth a thousand words... So ASCII art follows :-)
> >
>
> [...]
>
> > @@ -101,7 +108,7 @@ execution during resume):
> >
> > It is to be noted here that the system_transition_mutex lock is acquired at the very
> > beginning, when we are just starting out to suspend, and then released only
> > -after the entire cycle is complete (i.e., suspend + resume).
> > +after the entire cycle is complete (i.e., suspend + resume)::
> >
>
> I think that should be a period, not a colon, because it is clarifying
> the text above it (as opposed to referring to the example below it).
>
> Other than that, for suspend-and-cpuhotplug.txt:
>
> Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
Ah, ok. I'll change it to:
after the entire cycle is complete (i.e., suspend + resume).
::
and add your acked-by.
>
> Regards,
> Srivatsa
> VMware Photon OS
Thanks,
Mauro
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst
2019-06-12 17:52 ` [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst Mauro Carvalho Chehab
@ 2019-06-14 20:10 ` Jonathan Corbet
2019-06-14 20:34 ` Jonathan Corbet
0 siblings, 1 reply; 39+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:10 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Catalin Marinas, Will Deacon, Harry Wei, Alex Shi, Paolo Bonzini,
Radim Krčmář, Ard Biesheuvel, linux-arm-kernel,
kvm, linux-efi
On Wed, 12 Jun 2019 14:52:38 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> The documentation is in a format that is very close to ReST format.
>
> The conversion is actually:
> - add blank lines in order to identify paragraphs;
> - fixing tables markups;
> - adding some lists markups;
> - marking literal blocks;
> - adjust some title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
This one doesn't apply to docs-next, since there's a bunch of stuff in
linux-next that I don't have. I'd suggest that it either go by way of an
ARM tree or send it my way again after the ARM changes go upstream.
Thanks,
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 05/28] docs: cgroup-v1: convert docs to ReST and rename to *.rst
[not found] ` <c1dd623359f44f05863456b8bceba0d8f3e42f38.1560361364.git.mchehab+samsung@kernel.org>
@ 2019-06-14 20:14 ` Jonathan Corbet
2019-06-14 20:30 ` Tejun Heo
0 siblings, 1 reply; 39+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Thomas Gleixner, Ingo Molnar, Borislav Petkov, H. Peter Anvin,
x86, Jens Axboe, Tejun Heo, Li Zefan, Johannes Weiner,
Alexei Starovoitov, Daniel Borkmann, Martin KaFai Lau, Song Liu,
Yonghong Song, James Morris, Serge E. Hallyn, linux-block,
cgroups, netdev, bpf, linux-security-module
On Wed, 12 Jun 2019 14:52:41 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert the cgroup-v1 files to ReST format, in order to
> allow a later addition to the admin-guide.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Tejun Heo <tj@kernel.org>
This one, too, has linux-next stuff that keeps it from applying to
docs-next. Tejun, would you like to carry it on top of your work?
(This means I won't be able to apply #6 either, naturally).
Thanks,
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 05/28] docs: cgroup-v1: convert docs to ReST and rename to *.rst
2019-06-14 20:14 ` [PATCH v4 05/28] docs: cgroup-v1: " Jonathan Corbet
@ 2019-06-14 20:30 ` Tejun Heo
0 siblings, 0 replies; 39+ messages in thread
From: Tejun Heo @ 2019-06-14 20:30 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, linux-kernel, Thomas Gleixner, Ingo Molnar,
Borislav Petkov, H. Peter Anvin, x86, Jens Axboe, Li Zefan,
Johannes Weiner, Alexei Starovoitov, Daniel Borkmann,
Martin KaFai Lau, Song Liu, Yonghong Song, James Morris,
Serge E. Hallyn, linux-block, cgroups, netdev, bpf,
linux-security-module
On Fri, Jun 14, 2019 at 02:14:01PM -0600, Jonathan Corbet wrote:
> On Wed, 12 Jun 2019 14:52:41 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > Convert the cgroup-v1 files to ReST format, in order to
> > allow a later addition to the admin-guide.
> >
> > The conversion is actually:
> > - add blank lines and identation in order to identify paragraphs;
> > - fix tables markups;
> > - add some lists markups;
> > - mark literal blocks;
> > - adjust title markups.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > Acked-by: Tejun Heo <tj@kernel.org>
>
> This one, too, has linux-next stuff that keeps it from applying to
> docs-next. Tejun, would you like to carry it on top of your work?
Applied to cgroup/for-5.3.
Thanks.
--
tejun
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst
2019-06-14 20:10 ` Jonathan Corbet
@ 2019-06-14 20:34 ` Jonathan Corbet
0 siblings, 0 replies; 39+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:34 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Catalin Marinas, Will Deacon, Harry Wei, Alex Shi, Paolo Bonzini,
Radim Krčmář, Ard Biesheuvel, linux-arm-kernel,
kvm, linux-efi
On Fri, 14 Jun 2019 14:10:41 -0600
Jonathan Corbet <corbet@lwn.net> wrote:
> On Wed, 12 Jun 2019 14:52:38 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > The documentation is in a format that is very close to ReST format.
> >
> > The conversion is actually:
> > - add blank lines in order to identify paragraphs;
> > - fixing tables markups;
> > - adding some lists markups;
> > - marking literal blocks;
> > - adjust some title markups.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
>
> This one doesn't apply to docs-next, since there's a bunch of stuff in
> linux-next that I don't have. I'd suggest that it either go by way of an
> ARM tree or send it my way again after the ARM changes go upstream.
Actually, nevermind. Pulling my tree forward to 5.2-rc4 resolved the
issues here.
Thanks,
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 14/28] docs: locking: convert docs to ReST and rename to *.rst
2019-06-12 17:52 ` [PATCH v4 14/28] docs: locking: " Mauro Carvalho Chehab
@ 2019-06-14 20:36 ` Jonathan Corbet
0 siblings, 0 replies; 39+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Peter Zijlstra, Ingo Molnar, Will Deacon, Federico Vaga,
Maarten Lankhorst, Maxime Ripard, Sean Paul, David Airlie,
Daniel Vetter, dri-devel
On Wed, 12 Jun 2019 14:52:50 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert the locking documents to ReST and add them to the
> kernel development book where it belongs.
>
> Most of the stuff here is just to make Sphinx to properly
> parse the text file, as they're already in good shape,
> not requiring massive changes in order to be parsed.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
This patch contains linux-next changes and doesn't apply to docs-next.
Perhaps the best thing to do is to apply it to the locking tree?
Thanks,
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v5] docs: power: convert docs to ReST and rename to *.rst
[not found] ` <72d1f8f360d395958dd0b49165fc51b58801f57e.1560420621.git.mchehab+samsung@kernel.org>
@ 2019-06-14 20:36 ` Jonathan Corbet
2019-06-14 21:14 ` Bjorn Helgaas
0 siblings, 1 reply; 39+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Sebastian Reichel, Rafael J. Wysocki, Viresh Kumar, Len Brown,
Pavel Machek, Nishanth Menon, Stephen Boyd, Liam Girdwood,
Mark Brown, Mathieu Poirier, Suzuki K Poulose, Harry Wei,
Alex Shi, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
H. Peter Anvin, x86, Jani Nikula, Joonas Lahtinen, Rodrigo Vivi,
David Airlie, Daniel Vetter, Bjorn Helgaas, Johannes Berg,
David S. Miller, linux-pm, linux-arm-kernel, intel-gfx, dri-devel,
linux-pci, linux-wireless, netdev, Srivatsa S . Bhat
On Thu, 13 Jun 2019 07:10:36 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Mark Brown <broonie@kernel.org>
> Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
So I can't apply this one due to conflicts in include/linux/pci.h. Bjorn,
perhaps the easiest thing is for you to take this one through your tree?
Thanks,
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 19/28] docs: powerpc: convert docs to ReST and rename to *.rst
2019-06-12 17:52 ` [PATCH v4 19/28] docs: powerpc: " Mauro Carvalho Chehab
@ 2019-06-14 20:36 ` Jonathan Corbet
2019-06-14 21:30 ` Bjorn Helgaas
2019-06-18 12:39 ` Michael Ellerman
0 siblings, 2 replies; 39+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Linas Vepstas, Russell Currey, Sam Bobroff, Oliver O'Halloran,
Bjorn Helgaas, Benjamin Herrenschmidt, Paul Mackerras,
Michael Ellerman, Frederic Barrat, Andrew Donnellan,
Manoj N. Kumar, Matthew R. Ochs, Uma Krishnan, Qiang Zhao,
Li Yang, Greg Kroah-Hartman, Jiri Slaby, linux-pci, linuxppc-dev,
linux-scsi, linux-arm-kernel, Andrew Donnellan
On Wed, 12 Jun 2019 14:52:55 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert docs to ReST and add them to the arch-specific
> book.
>
> The conversion here was trivial, as almost every file there
> was already using an elegant format close to ReST standard.
>
> The changes were mostly to mark literal blocks and add a few
> missing section title identifiers.
>
> One note with regards to "--": on Sphinx, this can't be used
> to identify a list, as it will format it badly. This can be
> used, however, to identify a long hyphen - and "---" is an
> even longer one.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
This one fails to apply because ...
[...]
> diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
> index 83db42092935..acc21ecca322 100644
> --- a/Documentation/PCI/pci-error-recovery.rst
> +++ b/Documentation/PCI/pci-error-recovery.rst
> @@ -403,7 +403,7 @@ That is, the recovery API only requires that:
> .. note::
>
> Implementation details for the powerpc platform are discussed in
> - the file Documentation/powerpc/eeh-pci-error-recovery.txt
> + the file Documentation/powerpc/eeh-pci-error-recovery.rst
>
> As of this writing, there is a growing list of device drivers with
> patches implementing error recovery. Not all of these patches are in
> @@ -422,3 +422,24 @@ That is, the recovery API only requires that:
> - drivers/net/cxgb3
> - drivers/net/s2io.c
> - drivers/net/qlge
> +
> +>>> As of this writing, there is a growing list of device drivers with
> +>>> patches implementing error recovery. Not all of these patches are in
> +>>> mainline yet. These may be used as "examples":
> +>>>
> +>>> drivers/scsi/ipr
> +>>> drivers/scsi/sym53c8xx_2
> +>>> drivers/scsi/qla2xxx
> +>>> drivers/scsi/lpfc
> +>>> drivers/next/bnx2.c
> +>>> drivers/next/e100.c
> +>>> drivers/net/e1000
> +>>> drivers/net/e1000e
> +>>> drivers/net/ixgb
> +>>> drivers/net/ixgbe
> +>>> drivers/net/cxgb3
> +>>> drivers/net/s2io.c
> +>>> drivers/net/qlge
...of this, which has the look of a set of conflict markers that managed
to get committed...?
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 00/28] Convert files to ReST - part 1
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
` (23 preceding siblings ...)
[not found] ` <c1dd623359f44f05863456b8bceba0d8f3e42f38.1560361364.git.mchehab+samsung@kernel.org>
@ 2019-06-14 20:36 ` Jonathan Corbet
2019-06-18 14:14 ` Mauro Carvalho Chehab
24 siblings, 1 reply; 39+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Palmer Dabbelt, Albert Ou, Alexei Starovoitov, Daniel Borkmann,
Martin KaFai Lau, Song Liu, Yonghong Song, Greentime Hu,
Vincent Chen, linux-riscv, netdev, bpf
On Wed, 12 Jun 2019 14:52:36 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> This is mostly a rebase of the /33 series v3 I sent, on the top of the latest
> linux-next (next-20190612).
>
> Changes from v3:
>
> - dropped cpufreq conversion - documents are too outdated;
> - infiniband patch is not here anymore - as it should be merged via RDMA;
> - s390 patches were already merged;
> - Dropped Geert as Maintainer from fb/framebuffer.rst, as per his request;
> - Did a minor editorial change at popwerpc/cxl.rst per Andrew Donellan
> request;
> - Added acks/reviews;
> - trivial rebase fixups.
So I had to pull docs-next forward to -rc4, but then I was able to apply
this set except for parts 5, 6, 14, 18, and 19. Some progress made, but
this is somewhat painful work...
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v5] docs: power: convert docs to ReST and rename to *.rst
2019-06-14 20:36 ` [PATCH v5] docs: power: " Jonathan Corbet
@ 2019-06-14 21:14 ` Bjorn Helgaas
0 siblings, 0 replies; 39+ messages in thread
From: Bjorn Helgaas @ 2019-06-14 21:14 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, linux-kernel, Sebastian Reichel,
Rafael J. Wysocki, Viresh Kumar, Len Brown, Pavel Machek,
Nishanth Menon, Stephen Boyd, Liam Girdwood, Mark Brown,
Mathieu Poirier, Suzuki K Poulose, Harry Wei, Alex Shi,
Thomas Gleixner, Ingo Molnar, Borislav Petkov, H. Peter Anvin,
x86, Jani Nikula, Joonas Lahtinen, Rodrigo Vivi, David Airlie,
Daniel Vetter, Johannes Berg, David S. Miller, linux-pm,
linux-arm-kernel, intel-gfx, dri-devel, linux-pci, linux-wireless,
netdev, Srivatsa S . Bhat
On Fri, Jun 14, 2019 at 02:36:31PM -0600, Jonathan Corbet wrote:
> On Thu, 13 Jun 2019 07:10:36 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > Convert the PM documents to ReST, in order to allow them to
> > build with Sphinx.
> >
> > The conversion is actually:
> > - add blank lines and identation in order to identify paragraphs;
> > - fix tables markups;
> > - add some lists markups;
> > - mark literal blocks;
> > - adjust title markups.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > Acked-by: Mark Brown <broonie@kernel.org>
> > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> > Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
>
> So I can't apply this one due to conflicts in include/linux/pci.h. Bjorn,
> perhaps the easiest thing is for you to take this one through your tree?
OK, I applied this to pci/docs for v5.3. I applied this entire patch,
but if you would prefer that I only apply the PCI-related parts, let
me know and I'll split those out.
Bjorn
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 19/28] docs: powerpc: convert docs to ReST and rename to *.rst
2019-06-14 20:36 ` Jonathan Corbet
@ 2019-06-14 21:30 ` Bjorn Helgaas
2019-06-18 12:39 ` Michael Ellerman
1 sibling, 0 replies; 39+ messages in thread
From: Bjorn Helgaas @ 2019-06-14 21:30 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, linux-kernel, Linas Vepstas,
Russell Currey, Sam Bobroff, Oliver O'Halloran,
Benjamin Herrenschmidt, Paul Mackerras, Michael Ellerman,
Frederic Barrat, Andrew Donnellan, Manoj N. Kumar,
Matthew R. Ochs, Uma Krishnan, Qiang Zhao, Li Yang,
Greg Kroah-Hartman, Jiri Slaby, linux-pci, linuxppc-dev,
linux-scsi, linux-arm-kernel, Andrew Donnellan
On Fri, Jun 14, 2019 at 02:36:35PM -0600, Jonathan Corbet wrote:
> On Wed, 12 Jun 2019 14:52:55 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > Convert docs to ReST and add them to the arch-specific
> > book.
> >
> > The conversion here was trivial, as almost every file there
> > was already using an elegant format close to ReST standard.
> >
> > The changes were mostly to mark literal blocks and add a few
> > missing section title identifiers.
> >
> > One note with regards to "--": on Sphinx, this can't be used
> > to identify a list, as it will format it badly. This can be
> > used, however, to identify a long hyphen - and "---" is an
> > even longer one.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
>
> This one fails to apply because ...
>
> [...]
>
> > diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
> > index 83db42092935..acc21ecca322 100644
> > --- a/Documentation/PCI/pci-error-recovery.rst
> > +++ b/Documentation/PCI/pci-error-recovery.rst
> > @@ -403,7 +403,7 @@ That is, the recovery API only requires that:
> > .. note::
> >
> > Implementation details for the powerpc platform are discussed in
> > - the file Documentation/powerpc/eeh-pci-error-recovery.txt
> > + the file Documentation/powerpc/eeh-pci-error-recovery.rst
> >
> > As of this writing, there is a growing list of device drivers with
> > patches implementing error recovery. Not all of these patches are in
> > @@ -422,3 +422,24 @@ That is, the recovery API only requires that:
> > - drivers/net/cxgb3
> > - drivers/net/s2io.c
> > - drivers/net/qlge
> > +
> > +>>> As of this writing, there is a growing list of device drivers with
> > +>>> patches implementing error recovery. Not all of these patches are in
> > +>>> mainline yet. These may be used as "examples":
> > +>>>
> > +>>> drivers/scsi/ipr
> > +>>> drivers/scsi/sym53c8xx_2
> > +>>> drivers/scsi/qla2xxx
> > +>>> drivers/scsi/lpfc
> > +>>> drivers/next/bnx2.c
> > +>>> drivers/next/e100.c
> > +>>> drivers/net/e1000
> > +>>> drivers/net/e1000e
> > +>>> drivers/net/ixgb
> > +>>> drivers/net/ixgbe
> > +>>> drivers/net/cxgb3
> > +>>> drivers/net/s2io.c
> > +>>> drivers/net/qlge
>
> ...of this, which has the look of a set of conflict markers that managed
> to get committed...?
I don't see these conflict markers in my local branch or in
linux-next (next-20190614).
Let me know if I need to do something.
Bjorn
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 19/28] docs: powerpc: convert docs to ReST and rename to *.rst
2019-06-14 20:36 ` Jonathan Corbet
2019-06-14 21:30 ` Bjorn Helgaas
@ 2019-06-18 12:39 ` Michael Ellerman
1 sibling, 0 replies; 39+ messages in thread
From: Michael Ellerman @ 2019-06-18 12:39 UTC (permalink / raw)
To: Jonathan Corbet, Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Linas Vepstas, Russell Currey, Sam Bobroff, Oliver O'Halloran,
Bjorn Helgaas, Benjamin Herrenschmidt, Paul Mackerras,
Frederic Barrat, Andrew Donnellan, Manoj N. Kumar,
Matthew R. Ochs, Uma Krishnan, Qiang Zhao, Li Yang,
Greg Kroah-Hartman, Jiri Slaby, linux-pci, linuxppc-dev,
linux-scsi, linux-arm-kernel, Andrew Donnellan
Jonathan Corbet <corbet@lwn.net> writes:
> On Wed, 12 Jun 2019 14:52:55 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
>> Convert docs to ReST and add them to the arch-specific
>> book.
>>
>> The conversion here was trivial, as almost every file there
>> was already using an elegant format close to ReST standard.
>>
>> The changes were mostly to mark literal blocks and add a few
>> missing section title identifiers.
>>
>> One note with regards to "--": on Sphinx, this can't be used
>> to identify a list, as it will format it badly. This can be
>> used, however, to identify a long hyphen - and "---" is an
>> even longer one.
>>
>> At its new index.rst, let's add a :orphan: while this is not linked to
>> the main index.rst file, in order to avoid build warnings.
>>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>> Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
>
> This one fails to apply because ...
>
> [...]
>
>> diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
>> index 83db42092935..acc21ecca322 100644
>> --- a/Documentation/PCI/pci-error-recovery.rst
>> +++ b/Documentation/PCI/pci-error-recovery.rst
>> @@ -422,3 +422,24 @@ That is, the recovery API only requires that:
>> - drivers/net/cxgb3
>> - drivers/net/s2io.c
>> - drivers/net/qlge
>> +
>> +>>> As of this writing, there is a growing list of device drivers with
>> +>>> patches implementing error recovery. Not all of these patches are in
>> +>>> mainline yet. These may be used as "examples":
>> +>>>
>> +>>> drivers/scsi/ipr
>> +>>> drivers/scsi/sym53c8xx_2
>> +>>> drivers/scsi/qla2xxx
>> +>>> drivers/scsi/lpfc
>> +>>> drivers/next/bnx2.c
>> +>>> drivers/next/e100.c
>> +>>> drivers/net/e1000
>> +>>> drivers/net/e1000e
>> +>>> drivers/net/ixgb
>> +>>> drivers/net/ixgbe
>> +>>> drivers/net/cxgb3
>> +>>> drivers/net/s2io.c
>> +>>> drivers/net/qlge
>
> ...of this, which has the look of a set of conflict markers that managed
> to get committed...?
I don't think so.
There's some other uses of >>> in that file, eg about line 162:
>>> The current powerpc implementation assumes that a device driver will
>>> *not* schedule or semaphore in this routine; the current powerpc
>>> implementation uses one kernel thread to notify all devices;
>>> thus, if one device sleeps/schedules, all devices are affected.
>>> Doing better requires complex multi-threaded logic in the error
>>> recovery implementation (e.g. waiting for all notification threads
>>> to "join" before proceeding with recovery.) This seems excessively
>>> complex and not worth implementing.
So it's just an odd choice of emphasis device I think.
cheers
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 00/28] Convert files to ReST - part 1
2019-06-14 20:36 ` [PATCH v4 00/28] Convert files to ReST - part 1 Jonathan Corbet
@ 2019-06-18 14:14 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 39+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-18 14:14 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Palmer Dabbelt, Albert Ou, Alexei Starovoitov, Daniel Borkmann,
Martin KaFai Lau, Song Liu, Yonghong Song, Greentime Hu,
Vincent Chen, linux-riscv, netdev, bpf
Em Fri, 14 Jun 2019 14:36:40 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Wed, 12 Jun 2019 14:52:36 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > This is mostly a rebase of the /33 series v3 I sent, on the top of the latest
> > linux-next (next-20190612).
> >
> > Changes from v3:
> >
> > - dropped cpufreq conversion - documents are too outdated;
> > - infiniband patch is not here anymore - as it should be merged via RDMA;
> > - s390 patches were already merged;
> > - Dropped Geert as Maintainer from fb/framebuffer.rst, as per his request;
> > - Did a minor editorial change at popwerpc/cxl.rst per Andrew Donellan
> > request;
> > - Added acks/reviews;
> > - trivial rebase fixups.
>
> So I had to pull docs-next forward to -rc4, but then I was able to apply
> this set except for parts 5, 6, 14, 18, and 19.
Patch 5 went via Cgroups tree;
Patch 18 went via power tree;
Patch 6 is obsolete, as the cgroups-v1 CBQ chapter was removed;
So, what's left from this series are patches 14 and 19.
I have a rebased version of them on the top of linux-next
on my working tree. Perhaps we should try to push those two late
during the merge window.
> Some progress made, but
> this is somewhat painful work...
Yeah, a change like that is not easy.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v4 23/28] docs: target: convert docs to ReST and rename to *.rst
2019-06-12 17:52 ` [PATCH v4 23/28] docs: target: " Mauro Carvalho Chehab
@ 2019-06-19 3:38 ` Martin K. Petersen
0 siblings, 0 replies; 39+ messages in thread
From: Martin K. Petersen @ 2019-06-19 3:38 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Martin K. Petersen, linux-scsi, target-devel
Mauro,
> Convert the TCM docs to ReST format and add them to the
> bookset.
Looks good to me.
Acked-by: Martin K. Petersen <martin.petersen@oracle.com>
--
Martin K. Petersen Oracle Linux Engineering
^ permalink raw reply [flat|nested] 39+ messages in thread
end of thread, other threads:[~2019-06-19 3:39 UTC | newest]
Thread overview: 39+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-06-12 17:52 [PATCH v4 00/28] Convert files to ReST - part 1 Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 01/28] docs: aoe: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst Mauro Carvalho Chehab
2019-06-14 20:10 ` Jonathan Corbet
2019-06-14 20:34 ` Jonathan Corbet
2019-06-12 17:52 ` [PATCH v4 04/28] docs: cdrom: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 06/28] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 08/28] docs: fault-injection: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 10/28] docs: fpga: " Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 11/28] docs: ide: " Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 13/28] docs: kdump: " Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 14/28] docs: locking: " Mauro Carvalho Chehab
2019-06-14 20:36 ` Jonathan Corbet
2019-06-12 17:52 ` [PATCH v4 15/28] docs: mic: " Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 16/28] docs: netlabel: " Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 17/28] docs: pcmcia: " Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 19/28] docs: powerpc: " Mauro Carvalho Chehab
2019-06-14 20:36 ` Jonathan Corbet
2019-06-14 21:30 ` Bjorn Helgaas
2019-06-18 12:39 ` Michael Ellerman
2019-06-12 17:52 ` [PATCH v4 20/28] docs: pps.txt: convert to ReST and rename to pps.rst Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 21/28] docs: ptp.txt: convert to ReST and move to driver-api Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 22/28] docs: riscv: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 23/28] docs: target: " Mauro Carvalho Chehab
2019-06-19 3:38 ` Martin K. Petersen
2019-06-12 17:53 ` [PATCH v4 24/28] docs: timers: " Mauro Carvalho Chehab
2019-06-12 18:25 ` Mark Brown
2019-06-12 17:53 ` [PATCH v4 25/28] docs: watchdog: " Mauro Carvalho Chehab
2019-06-12 17:53 ` [PATCH v4 26/28] docs: xilinx: convert eemi.txt to eemi.rst Mauro Carvalho Chehab
2019-06-12 17:53 ` [PATCH v4 27/28] docs: scheduler: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 17:53 ` [PATCH v4 28/28] docs: EDID/HOWTO.txt: convert it and rename to howto.rst Mauro Carvalho Chehab
[not found] ` <fac44e1fbab5ea755a93601a4fdfa34fcc57ae9e.1560361364.git.mchehab+samsung@kernel.org>
2019-06-13 0:25 ` [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst Srivatsa S. Bhat
2019-06-13 9:58 ` Mauro Carvalho Chehab
[not found] ` <72d1f8f360d395958dd0b49165fc51b58801f57e.1560420621.git.mchehab+samsung@kernel.org>
2019-06-14 20:36 ` [PATCH v5] docs: power: " Jonathan Corbet
2019-06-14 21:14 ` Bjorn Helgaas
[not found] ` <c1dd623359f44f05863456b8bceba0d8f3e42f38.1560361364.git.mchehab+samsung@kernel.org>
2019-06-14 20:14 ` [PATCH v4 05/28] docs: cgroup-v1: " Jonathan Corbet
2019-06-14 20:30 ` Tejun Heo
2019-06-14 20:36 ` [PATCH v4 00/28] Convert files to ReST - part 1 Jonathan Corbet
2019-06-18 14:14 ` Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).