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
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 (33):
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: cpu-freq: convert docs to ReST and rename to *.rst
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: infiniband: 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: Debugging390.txt: convert table to ascii artwork
docs: s390: convert docs to ReST and rename to *.rst
s390: include/asm/debug.h add kerneldoc markups
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 | 28 +-
.../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 +-
.../arm64/{memory.txt => memory.rst} | 91 +-
...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 -
...{cdrom-standard.tex => cdrom-standard.rst} | 1491 +++++-----
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 +-
.../{amd-powernow.txt => amd-powernow.rst} | 11 +-
Documentation/cpu-freq/{core.txt => core.rst} | 68 +-
.../{cpu-drivers.txt => cpu-drivers.rst} | 217 +-
...pufreq-nforce2.txt => cpufreq-nforce2.rst} | 12 +-
.../{cpufreq-stats.txt => cpufreq-stats.rst} | 141 +-
.../cpu-freq/{index.txt => index.rst} | 44 +-
.../{pcc-cpufreq.txt => pcc-cpufreq.rst} | 102 +-
...{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 +-
.../{dm-uevent.txt => dm-uevent.rst} | 143 +-
.../{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 +-
.../device-mapper/{linear.txt => linear.rst} | 100 +-
.../{log-writes.txt => log-writes.rst} | 91 +-
...ersistent-data.txt => persistent-data.rst} | 4 +
.../{snapshot.txt => snapshot.rst} | 116 +-
.../{statistics.txt => statistics.rst} | 62 +-
.../{striped.txt => striped.rst} | 68 +-
.../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 +-
Documentation/driver-api/s390-drivers.rst | 4 +-
.../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 +-
...injection.txt => nvme-fault-injection.rst} | 174 +-
...rovoke-crashes.txt => provoke-crashes.rst} | 40 +-
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} | 79 +-
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 +-
.../fb/{matroxfb.txt => matroxfb.rst} | 528 ++--
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/{pvr2fb.txt => pvr2fb.rst} | 55 +-
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
.../fb/{sh7760fb.txt => sh7760fb.rst} | 153 +-
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/{sstfb.txt => sstfb.rst} | 231 +-
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.txt => viafb.rst} | 393 +--
.../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 +-
.../{core_locking.txt => core_locking.rst} | 64 +-
Documentation/infiniband/index.rst | 23 +
.../infiniband/{ipoib.txt => ipoib.rst} | 24 +-
.../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +-
.../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
.../{tag_matching.txt => tag_matching.rst} | 5 +
.../infiniband/{user_mad.txt => user_mad.rst} | 33 +-
.../{user_verbs.txt => user_verbs.rst} | 12 +-
...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 +-
.../locking/{lockstat.txt => lockstat.rst} | 221 +-
.../{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 +-
...upply_class.txt => power_supply_class.rst} | 269 +-
.../powercap/{powercap.txt => powercap.rst} | 297 +-
.../regulator/{consumer.txt => consumer.rst} | 141 +-
.../regulator/{design.txt => design.rst} | 9 +-
.../regulator/{machine.txt => machine.rst} | 47 +-
.../regulator/{overview.txt => overview.rst} | 57 +-
.../{regulator.txt => regulator.rst} | 18 +-
.../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 +-
.../power/{swsusp.txt => swsusp.rst} | 639 ++--
.../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 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +-
.../{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 +-
Documentation/s390/{3270.txt => 3270.rst} | 85 +-
Documentation/s390/{cds.txt => cds.rst} | 354 ++-
.../s390/{CommonIO => common_io.rst} | 49 +-
Documentation/s390/{DASD => dasd.rst} | 33 +-
.../{Debugging390.txt => debugging390.rst} | 2599 ++++++++++-------
.../{driver-model.txt => driver-model.rst} | 179 +-
Documentation/s390/index.rst | 30 +
.../s390/{monreader.txt => monreader.rst} | 85 +-
Documentation/s390/{qeth.txt => qeth.rst} | 36 +-
.../s390/{s390dbf.txt => s390dbf.rst} | 616 +---
Documentation/s390/text_files.rst | 11 +
.../s390/{vfio-ap.txt => vfio-ap.rst} | 487 +--
.../s390/{vfio-ccw.txt => vfio-ccw.rst} | 90 +-
.../s390/{zfcpdump.txt => zfcpdump.rst} | 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} | 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 +
...cm_mod_builder.txt => tcm_mod_builder.rst} | 200 +-
.../{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 +-
...parameters.txt => watchdog-parameters.rst} | 672 +++--
.../{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 | 38 +-
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/s390/Kconfig | 4 +-
arch/s390/include/asm/debug.h | 235 +-
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/cpufreq/Kconfig.x86 | 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/infiniband/core/user_mad.c | 2 +-
drivers/infiniband/ulp/ipoib/Kconfig | 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/s390/char/zcore.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 +-
407 files changed, 14319 insertions(+), 10552 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%)
rename Documentation/arm64/{memory.txt => memory.rst} (36%)
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
rename Documentation/cdrom/{cdrom-standard.tex => cdrom-standard.rst} (26%)
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/cpu-freq/{amd-powernow.txt => amd-powernow.rst} (91%)
rename Documentation/cpu-freq/{core.txt => core.rst} (66%)
rename Documentation/cpu-freq/{cpu-drivers.txt => cpu-drivers.rst} (57%)
rename Documentation/cpu-freq/{cpufreq-nforce2.txt => cpufreq-nforce2.rst} (65%)
rename Documentation/cpu-freq/{cpufreq-stats.txt => cpufreq-stats.rst} (31%)
rename Documentation/cpu-freq/{index.txt => index.rst} (37%)
rename Documentation/cpu-freq/{pcc-cpufreq.txt => pcc-cpufreq.rst} (80%)
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%)
rename Documentation/device-mapper/{dm-uevent.txt => dm-uevent.rst} (31%)
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%)
rename Documentation/device-mapper/{linear.txt => linear.rst} (18%)
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%)
rename Documentation/device-mapper/{striped.txt => striped.rst} (32%)
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%)
rename Documentation/fault-injection/{nvme-fault-injection.txt => nvme-fault-injection.rst} (19%)
rename Documentation/fault-injection/{provoke-crashes.txt => provoke-crashes.rst} (45%)
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%)
rename Documentation/fb/{matroxfb.txt => matroxfb.rst} (32%)
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
rename Documentation/fb/{pvr2fb.txt => pvr2fb.rst} (36%)
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
rename Documentation/fb/{sh7760fb.txt => sh7760fb.rst} (39%)
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
rename Documentation/fb/{sstfb.txt => sstfb.rst} (28%)
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%)
rename Documentation/fb/{viafb.txt => viafb.rst} (18%)
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/infiniband/{core_locking.txt => core_locking.rst} (78%)
create mode 100644 Documentation/infiniband/index.rst
rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
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%)
rename Documentation/locking/{lockstat.txt => lockstat.rst} (41%)
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%)
rename Documentation/power/{power_supply_class.txt => power_supply_class.rst} (46%)
rename Documentation/power/powercap/{powercap.txt => powercap.rst} (40%)
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%)
rename Documentation/power/regulator/{regulator.txt => regulator.rst} (49%)
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%)
rename Documentation/power/{swsusp.txt => swsusp.rst} (20%)
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%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
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/s390/{3270.txt => 3270.rst} (90%)
rename Documentation/s390/{cds.txt => cds.rst} (64%)
rename Documentation/s390/{CommonIO => common_io.rst} (87%)
rename Documentation/s390/{DASD => dasd.rst} (92%)
rename Documentation/s390/{Debugging390.txt => debugging390.rst} (43%)
rename Documentation/s390/{driver-model.txt => driver-model.rst} (73%)
create mode 100644 Documentation/s390/index.rst
rename Documentation/s390/{monreader.txt => monreader.rst} (81%)
rename Documentation/s390/{qeth.txt => qeth.rst} (62%)
rename Documentation/s390/{s390dbf.txt => s390dbf.rst} (18%)
create mode 100644 Documentation/s390/text_files.rst
rename Documentation/s390/{vfio-ap.txt => vfio-ap.rst} (72%)
rename Documentation/s390/{vfio-ccw.txt => vfio-ccw.rst} (89%)
rename Documentation/s390/{zfcpdump.txt => zfcpdump.rst} (97%)
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
rename Documentation/target/{tcm_mod_builder.txt => tcm_mod_builder.rst} (22%)
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%)
rename Documentation/watchdog/{watchdog-parameters.txt => watchdog-parameters.rst} (42%)
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
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 <[email protected]>
---
.../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 dce53f6414b6..08efe50266b5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7210,7 +7210,7 @@ F: drivers/net/ethernet/hp/hp100.*
HPET: High Precision Event Timers driver
M: Clemens Ladisch <[email protected]>
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 b1d861caca16..320bbc9761c8 100644
--- a/include/linux/iopoll.h
+++ b/include/linux/iopoll.h
@@ -30,7 +30,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
@@ -69,7 +69,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 daeec7dbd65c..ed5e9d0a1285 100644
--- a/include/linux/regmap.h
+++ b/include/linux/regmap.h
@@ -112,7 +112,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
@@ -154,7 +154,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
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 <[email protected]>
---
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
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 <[email protected]>
---
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 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +++++++++---------
.../{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 +-
25 files changed, 515 insertions(+), 358 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%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
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 <[email protected]>
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..99e704afb09d 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 <------> PSL Version 8 is compliant to the CAIA Version 1.0.
+ - POWER9 <------> PSL Version 9 is 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 <[email protected]>
@@ -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 <[email protected]>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <[email protected]>
- 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 <[email protected]>
+
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 <[email protected]>
- 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 <[email protected]>
+
+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 <[email protected]>
+
Benjamin Herrenschmidt <[email protected]>
+
Bjorn Helgaas <[email protected]>
+
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.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
GDB intends to support the following hardware debug features of BookE
processors:
@@ -12,6 +16,7 @@ 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.
@@ -22,9 +27,9 @@ 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:
+The query will fill the following structure provided by the requesting process::
-struct ppc_debug_info {
+ struct ppc_debug_info {
unit32_t version;
unit32_t num_instruction_bps;
unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
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:
+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
+ #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:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
-struct ppc_hw_breakpoint {
+ 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
+ #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
+ #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))
+ #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
@@ -88,61 +93,61 @@ 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;
+- 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
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 <[email protected]>
diff --git a/MAINTAINERS b/MAINTAINERS
index 65448dae1467..01d9120bb83b 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: [email protected]
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 <[email protected]>
@@ -12187,7 +12187,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
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 <[email protected]>
---
...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 ++-
.../arm64/{memory.txt => memory.rst} | 91 +++---
...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 +-
23 files changed, 651 insertions(+), 427 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%)
rename Documentation/arm64/{memory.txt => memory.rst} (36%)
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 <[email protected]>
-Graeme Gregory <[email protected]>
-Hanjun Guo <[email protected]>
+- Al Stone <[email protected]>
+- Graeme Gregory <[email protected]>
+- Hanjun Guo <[email protected]>
-Grant Likely <[email protected]>, for the "Why ACPI on ARM?" section
+- Grant Likely <[email protected]>, 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 <[email protected]>
+
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 <[email protected]>
@@ -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 <[email protected]>
- *
- * 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 <[email protected]>
+ *
+ * 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.txt b/Documentation/arm64/memory.rst
similarity index 36%
rename from Documentation/arm64/memory.txt
rename to Documentation/arm64/memory.rst
index c5dab30d3389..464b880fc4b7 100644
--- a/Documentation/arm64/memory.txt
+++ b/Documentation/arm64/memory.rst
@@ -1,5 +1,6 @@
- Memory Layout on AArch64 Linux
- ==============================
+==============================
+Memory Layout on AArch64 Linux
+==============================
Author: Catalin Marinas <[email protected]>
@@ -21,69 +22,69 @@ The swapper_pg_dir address is written to TTBR1 and never written to
TTBR0.
-AArch64 Linux memory layout with 4KB pages + 3 levels:
+AArch64 Linux memory layout with 4KB pages + 3 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000007fffffffff 512GB user
-ffffff8000000000 ffffffffffffffff 512GB kernel
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000007fffffffff 512GB user
+ ffffff8000000000 ffffffffffffffff 512GB kernel
-AArch64 Linux memory layout with 4KB pages + 4 levels:
+AArch64 Linux memory layout with 4KB pages + 4 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000ffffffffffff 256TB user
+ ffff000000000000 ffffffffffffffff 256TB kernel
-AArch64 Linux memory layout with 64KB pages + 2 levels:
+AArch64 Linux memory layout with 64KB pages + 2 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 000003ffffffffff 4TB user
-fffffc0000000000 ffffffffffffffff 4TB kernel
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 000003ffffffffff 4TB user
+ fffffc0000000000 ffffffffffffffff 4TB kernel
-AArch64 Linux memory layout with 64KB pages + 3 levels:
+AArch64 Linux memory layout with 64KB pages + 3 levels::
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
+ 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:
+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
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |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:
+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
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |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
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 <[email protected]>
+
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 <[email protected]>
+
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 <[email protected]>
+
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 <[email protected]>
+
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 <[email protected]>
zh_CN: Fu Wei <[email protected]>
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 <[email protected]>
Suzuki K. Poulose <[email protected]>
Chinese maintainer: Fu Wei <[email protected]>
---------------------------------------------------------------------
-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 <[email protected]>
Chinese maintainer: Fu Wei <[email protected]>
---------------------------------------------------------------------
-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 <[email protected]>
zh_CN: Fu Wei <[email protected]>
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 <[email protected]>
Chinese maintainer: Fu Wei <[email protected]>
---------------------------------------------------------------------
-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
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 <[email protected]>
---
Documentation/admin-guide/hw-vuln/l1tf.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 4 +-
.../admin-guide/mm/numa_memory_policy.rst | 2 +-
Documentation/block/bfq-iosched.txt | 2 +-
...io-controller.txt => blkio-controller.rst} | 96 ++--
.../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/filesystems/tmpfs.txt | 2 +-
Documentation/scheduler/sched-deadline.txt | 2 +-
Documentation/scheduler/sched-design-CFS.txt | 2 +-
Documentation/scheduler/sched-rt-group.txt | 2 +-
Documentation/vm/numa.rst | 4 +-
Documentation/vm/page_migration.rst | 2 +-
Documentation/vm/unevictable-lru.rst | 2 +-
.../x86/x86_64/fake-numa-for-cpusets.rst | 4 +-
MAINTAINERS | 2 +-
block/Kconfig | 2 +-
include/linux/cgroup-defs.h | 2 +-
include/uapi/linux/bpf.h | 2 +-
init/Kconfig | 2 +-
kernel/cgroup/cpuset.c | 2 +-
security/device_cgroup.c | 2 +-
tools/include/uapi/linux/bpf.h | 2 +-
34 files changed, 952 insertions(+), 634 deletions(-)
rename Documentation/cgroup-v1/{blkio-controller.txt => blkio-controller.rst} (90%)
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%)
diff --git a/Documentation/admin-guide/hw-vuln/l1tf.rst b/Documentation/admin-guide/hw-vuln/l1tf.rst
index 31653a9f0e1b..656aee262e23 100644
--- a/Documentation/admin-guide/hw-vuln/l1tf.rst
+++ b/Documentation/admin-guide/hw-vuln/l1tf.rst
@@ -241,7 +241,7 @@ Guest mitigation mechanisms
For further information about confining guests to a single or to a group
of cores consult the cpusets documentation:
- https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt
+ https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.rst
.. _interrupt_isolation:
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index c80c670b86e3..a2c36cbad438 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4098,7 +4098,7 @@
relax_domain_level=
[KNL, SMP] Set scheduler's default relax_domain_level.
- See Documentation/cgroup-v1/cpusets.txt.
+ See Documentation/cgroup-v1/cpusets.rst.
reserve= [KNL,BUGS] Force kernel to ignore I/O ports or memory
Format: <base1>,<size1>[,<base2>,<size2>,...]
@@ -4608,7 +4608,7 @@
swapaccount=[0|1]
[KNL] Enable accounting of swap in memory resource
controller if no parameter or 1 is given or disable
- it if 0 is given (See Documentation/cgroup-v1/memory.txt)
+ it if 0 is given (See Documentation/cgroup-v1/memory.rst)
swiotlb= [ARM,IA-64,PPC,MIPS,X86]
Format: { <int> | force | noforce }
diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst
index d78c5b315f72..546f174e5d6a 100644
--- a/Documentation/admin-guide/mm/numa_memory_policy.rst
+++ b/Documentation/admin-guide/mm/numa_memory_policy.rst
@@ -15,7 +15,7 @@ document attempts to describe the concepts and APIs of the 2.6 memory policy
support.
Memory policies should not be confused with cpusets
-(``Documentation/cgroup-v1/cpusets.txt``)
+(``Documentation/cgroup-v1/cpusets.rst``)
which is an administrative mechanism for restricting the nodes from which
memory may be allocated by a set of processes. Memory policies are a
programming interface that a NUMA-aware application can take advantage of. When
diff --git a/Documentation/block/bfq-iosched.txt b/Documentation/block/bfq-iosched.txt
index 1a0f2ac02eb6..b2265cf6c9c3 100644
--- a/Documentation/block/bfq-iosched.txt
+++ b/Documentation/block/bfq-iosched.txt
@@ -539,7 +539,7 @@ As for cgroups-v1 (blkio controller), the exact set of stat files
created, and kept up-to-date by bfq, depends on whether
CONFIG_DEBUG_BLK_CGROUP is set. If it is set, then bfq creates all
the stat files documented in
-Documentation/cgroup-v1/blkio-controller.txt. If, instead,
+Documentation/cgroup-v1/blkio-controller.rst. If, instead,
CONFIG_DEBUG_BLK_CGROUP is not set, then bfq creates only the files
blkio.bfq.io_service_bytes
blkio.bfq.io_service_bytes_recursive
diff --git a/Documentation/cgroup-v1/blkio-controller.txt b/Documentation/cgroup-v1/blkio-controller.rst
similarity index 90%
rename from Documentation/cgroup-v1/blkio-controller.txt
rename to Documentation/cgroup-v1/blkio-controller.rst
index 673dc34d3f78..2c1b907afc14 100644
--- a/Documentation/cgroup-v1/blkio-controller.txt
+++ b/Documentation/cgroup-v1/blkio-controller.rst
@@ -1,5 +1,7 @@
- Block IO Controller
- ===================
+===================
+Block IO Controller
+===================
+
Overview
========
cgroup subsys "blkio" implements the block io controller. There seems to be
@@ -22,28 +24,35 @@ Proportional Weight division of bandwidth
You can do a very simple testing of running two dd threads in two different
cgroups. Here is what you can do.
-- Enable Block IO controller
+- Enable Block IO controller::
+
CONFIG_BLK_CGROUP=y
-- Enable group scheduling in CFQ
+- Enable group scheduling in CFQ:
+
+
CONFIG_CFQ_GROUP_IOSCHED=y
- Compile and boot into kernel and mount IO controller (blkio); see
cgroups.txt, Why are cgroups needed?.
+ ::
+
mount -t tmpfs cgroup_root /sys/fs/cgroup
mkdir /sys/fs/cgroup/blkio
mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
-- Create two cgroups
+- Create two cgroups::
+
mkdir -p /sys/fs/cgroup/blkio/test1/ /sys/fs/cgroup/blkio/test2
-- Set weights of group test1 and test2
+- Set weights of group test1 and test2::
+
echo 1000 > /sys/fs/cgroup/blkio/test1/blkio.weight
echo 500 > /sys/fs/cgroup/blkio/test2/blkio.weight
- Create two same size files (say 512MB each) on same disk (file1, file2) and
- launch two dd threads in different cgroup to read those files.
+ launch two dd threads in different cgroup to read those files::
sync
echo 3 > /proc/sys/vm/drop_caches
@@ -65,24 +74,27 @@ cgroups. Here is what you can do.
Throttling/Upper Limit policy
-----------------------------
-- Enable Block IO controller
+- Enable Block IO controller::
+
CONFIG_BLK_CGROUP=y
-- Enable throttling in block layer
+- Enable throttling in block layer::
+
CONFIG_BLK_DEV_THROTTLING=y
-- Mount blkio controller (see cgroups.txt, Why are cgroups needed?)
+- Mount blkio controller (see cgroups.txt, Why are cgroups needed?)::
+
mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
- Specify a bandwidth rate on particular device for root group. The format
- for policy is "<major>:<minor> <bytes_per_second>".
+ for policy is "<major>:<minor> <bytes_per_second>"::
echo "8:16 1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device
Above will put a limit of 1MB/second on reads happening for root group
on device having major/minor number 8:16.
-- Run dd to read a file and see if rate is throttled to 1MB/s or not.
+- Run dd to read a file and see if rate is throttled to 1MB/s or not::
# dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024
1024+0 records in
@@ -99,7 +111,7 @@ throttling's hierarchy support is enabled iff "sane_behavior" is
enabled from cgroup side, which currently is a development option and
not publicly available.
-If somebody created a hierarchy like as follows.
+If somebody created a hierarchy like as follows::
root
/ \
@@ -115,7 +127,7 @@ directly generated by tasks in that cgroup.
Throttling without "sane_behavior" enabled from cgroup side will
practically treat all groups at same level as if it looks like the
-following.
+following::
pivot
/ / \ \
@@ -152,27 +164,31 @@ Proportional weight policy files
These rules override the default value of group weight as specified
by blkio.weight.
- Following is the format.
+ Following is the format::
- # echo dev_maj:dev_minor weight > blkio.weight_device
- Configure weight=300 on /dev/sdb (8:16) in this cgroup
- # echo 8:16 300 > blkio.weight_device
- # cat blkio.weight_device
- dev weight
- 8:16 300
+ # echo dev_maj:dev_minor weight > blkio.weight_device
- Configure weight=500 on /dev/sda (8:0) in this cgroup
- # echo 8:0 500 > blkio.weight_device
- # cat blkio.weight_device
- dev weight
- 8:0 500
- 8:16 300
+ Configure weight=300 on /dev/sdb (8:16) in this cgroup::
- Remove specific weight for /dev/sda in this cgroup
- # echo 8:0 0 > blkio.weight_device
- # cat blkio.weight_device
- dev weight
- 8:16 300
+ # echo 8:16 300 > blkio.weight_device
+ # cat blkio.weight_device
+ dev weight
+ 8:16 300
+
+ Configure weight=500 on /dev/sda (8:0) in this cgroup::
+
+ # echo 8:0 500 > blkio.weight_device
+ # cat blkio.weight_device
+ dev weight
+ 8:0 500
+ 8:16 300
+
+ Remove specific weight for /dev/sda in this cgroup::
+
+ # echo 8:0 0 > blkio.weight_device
+ # cat blkio.weight_device
+ dev weight
+ 8:16 300
- blkio.leaf_weight[_device]
- Equivalents of blkio.weight[_device] for the purpose of
@@ -297,30 +313,30 @@ Throttling/Upper limit policy files
- blkio.throttle.read_bps_device
- Specifies upper limit on READ rate from the device. IO rate is
specified in bytes per second. Rules are per device. Following is
- the format.
+ the format::
- echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device
+ echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device
- blkio.throttle.write_bps_device
- Specifies upper limit on WRITE rate to the device. IO rate is
specified in bytes per second. Rules are per device. Following is
- the format.
+ the format::
- echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device
+ echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device
- blkio.throttle.read_iops_device
- Specifies upper limit on READ rate from the device. IO rate is
specified in IO per second. Rules are per device. Following is
- the format.
+ the format::
- echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device
+ echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device
- blkio.throttle.write_iops_device
- Specifies upper limit on WRITE rate to the device. IO rate is
specified in io per second. Rules are per device. Following is
- the format.
+ the format::
- echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device
+ echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device
Note: If both BW and IOPS rules are specified for a device, then IO is
subjected to both the constraints.
diff --git a/Documentation/cgroup-v1/cgroups.txt b/Documentation/cgroup-v1/cgroups.rst
similarity index 88%
rename from Documentation/cgroup-v1/cgroups.txt
rename to Documentation/cgroup-v1/cgroups.rst
index 059f7063eea6..46bbe7e022d4 100644
--- a/Documentation/cgroup-v1/cgroups.txt
+++ b/Documentation/cgroup-v1/cgroups.rst
@@ -1,35 +1,39 @@
- CGROUPS
- -------
+==============
+Control Groups
+==============
Written by Paul Menage <[email protected]> based on
-Documentation/cgroup-v1/cpusets.txt
+Documentation/cgroup-v1/cpusets.rst
Original copyright statements from cpusets.txt:
+
Portions Copyright (C) 2004 BULL SA.
+
Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
+
Modified by Paul Jackson <[email protected]>
+
Modified by Christoph Lameter <[email protected]>
-CONTENTS:
-=========
+.. CONTENTS:
-1. Control Groups
- 1.1 What are cgroups ?
- 1.2 Why are cgroups needed ?
- 1.3 How are cgroups implemented ?
- 1.4 What does notify_on_release do ?
- 1.5 What does clone_children do ?
- 1.6 How do I use cgroups ?
-2. Usage Examples and Syntax
- 2.1 Basic Usage
- 2.2 Attaching processes
- 2.3 Mounting hierarchies by name
-3. Kernel API
- 3.1 Overview
- 3.2 Synchronization
- 3.3 Subsystem API
-4. Extended attributes usage
-5. Questions
+ 1. Control Groups
+ 1.1 What are cgroups ?
+ 1.2 Why are cgroups needed ?
+ 1.3 How are cgroups implemented ?
+ 1.4 What does notify_on_release do ?
+ 1.5 What does clone_children do ?
+ 1.6 How do I use cgroups ?
+ 2. Usage Examples and Syntax
+ 2.1 Basic Usage
+ 2.2 Attaching processes
+ 2.3 Mounting hierarchies by name
+ 3. Kernel API
+ 3.1 Overview
+ 3.2 Synchronization
+ 3.3 Subsystem API
+ 4. Extended attributes usage
+ 5. Questions
1. Control Groups
=================
@@ -72,7 +76,7 @@ On their own, the only use for cgroups is for simple job
tracking. The intention is that other subsystems hook into the generic
cgroup support to provide new attributes for cgroups, such as
accounting/limiting the resources which processes in a cgroup can
-access. For example, cpusets (see Documentation/cgroup-v1/cpusets.txt) allow
+access. For example, cpusets (see Documentation/cgroup-v1/cpusets.rst) allow
you to associate a set of CPUs and a set of memory nodes with the
tasks in each cgroup.
@@ -108,7 +112,7 @@ As an example of a scenario (originally proposed by [email protected])
that can benefit from multiple hierarchies, consider a large
university server with various users - students, professors, system
tasks etc. The resource planning for this server could be along the
-following lines:
+following lines::
CPU : "Top cpuset"
/ \
@@ -136,7 +140,7 @@ depending on who launched it (prof/student).
With the ability to classify tasks differently for different resources
(by putting those resource subsystems in different hierarchies),
the admin can easily set up a script which receives exec notifications
-and depending on who is launching the browser he can
+and depending on who is launching the browser he can::
# echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks
@@ -151,7 +155,7 @@ wants to do online gaming :)) OR give one of the student's simulation
apps enhanced CPU power.
With ability to write PIDs directly to resource classes, it's just a
-matter of:
+matter of::
# echo pid > /sys/fs/cgroup/network/<new_class>/tasks
(after some time)
@@ -306,7 +310,7 @@ configuration from the parent during initialization.
--------------------------
To start a new job that is to be contained within a cgroup, using
-the "cpuset" cgroup subsystem, the steps are something like:
+the "cpuset" cgroup subsystem, the steps are something like::
1) mount -t tmpfs cgroup_root /sys/fs/cgroup
2) mkdir /sys/fs/cgroup/cpuset
@@ -320,7 +324,7 @@ the "cpuset" cgroup subsystem, the steps are something like:
For example, the following sequence of commands will setup a cgroup
named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
-and then start a subshell 'sh' in that cgroup:
+and then start a subshell 'sh' in that cgroup::
mount -t tmpfs cgroup_root /sys/fs/cgroup
mkdir /sys/fs/cgroup/cpuset
@@ -345,8 +349,9 @@ and then start a subshell 'sh' in that cgroup:
Creating, modifying, using cgroups can be done through the cgroup
virtual filesystem.
-To mount a cgroup hierarchy with all available subsystems, type:
-# mount -t cgroup xxx /sys/fs/cgroup
+To mount a cgroup hierarchy with all available subsystems, type::
+
+ # mount -t cgroup xxx /sys/fs/cgroup
The "xxx" is not interpreted by the cgroup code, but will appear in
/proc/mounts so may be any useful identifying string that you like.
@@ -355,18 +360,19 @@ Note: Some subsystems do not work without some user input first. For instance,
if cpusets are enabled the user will have to populate the cpus and mems files
for each new cgroup created before that group can be used.
-As explained in section `1.2 Why are cgroups needed?' you should create
+As explained in section `1.2 Why are cgroups needed?` you should create
different hierarchies of cgroups for each single resource or group of
resources you want to control. Therefore, you should mount a tmpfs on
/sys/fs/cgroup and create directories for each cgroup resource or resource
-group.
+group::
-# mount -t tmpfs cgroup_root /sys/fs/cgroup
-# mkdir /sys/fs/cgroup/rg1
+ # mount -t tmpfs cgroup_root /sys/fs/cgroup
+ # mkdir /sys/fs/cgroup/rg1
To mount a cgroup hierarchy with just the cpuset and memory
-subsystems, type:
-# mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1
+subsystems, type::
+
+ # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1
While remounting cgroups is currently supported, it is not recommend
to use it. Remounting allows changing bound subsystems and
@@ -375,9 +381,10 @@ hierarchy is empty and release_agent itself should be replaced with
conventional fsnotify. The support for remounting will be removed in
the future.
-To Specify a hierarchy's release_agent:
-# mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \
- xxx /sys/fs/cgroup/rg1
+To Specify a hierarchy's release_agent::
+
+ # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \
+ xxx /sys/fs/cgroup/rg1
Note that specifying 'release_agent' more than once will return failure.
@@ -390,32 +397,39 @@ Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the
tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1
is the cgroup that holds the whole system.
-If you want to change the value of release_agent:
-# echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent
+If you want to change the value of release_agent::
+
+ # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent
It can also be changed via remount.
-If you want to create a new cgroup under /sys/fs/cgroup/rg1:
-# cd /sys/fs/cgroup/rg1
-# mkdir my_cgroup
+If you want to create a new cgroup under /sys/fs/cgroup/rg1::
-Now you want to do something with this cgroup.
-# cd my_cgroup
+ # cd /sys/fs/cgroup/rg1
+ # mkdir my_cgroup
-In this directory you can find several files:
-# ls
-cgroup.procs notify_on_release tasks
-(plus whatever files added by the attached subsystems)
+Now you want to do something with this cgroup:
-Now attach your shell to this cgroup:
-# /bin/echo $$ > tasks
+ # cd my_cgroup
+
+In this directory you can find several files::
+
+ # ls
+ cgroup.procs notify_on_release tasks
+ (plus whatever files added by the attached subsystems)
+
+Now attach your shell to this cgroup::
+
+ # /bin/echo $$ > tasks
You can also create cgroups inside your cgroup by using mkdir in this
-directory.
-# mkdir my_sub_cs
+directory::
-To remove a cgroup, just use rmdir:
-# rmdir my_sub_cs
+ # mkdir my_sub_cs
+
+To remove a cgroup, just use rmdir::
+
+ # rmdir my_sub_cs
This will fail if the cgroup is in use (has cgroups inside, or
has processes attached, or is held alive by other subsystem-specific
@@ -424,19 +438,21 @@ reference).
2.2 Attaching processes
-----------------------
-# /bin/echo PID > tasks
+::
+
+ # /bin/echo PID > tasks
Note that it is PID, not PIDs. You can only attach ONE task at a time.
-If you have several tasks to attach, you have to do it one after another:
+If you have several tasks to attach, you have to do it one after another::
-# /bin/echo PID1 > tasks
-# /bin/echo PID2 > tasks
- ...
-# /bin/echo PIDn > tasks
+ # /bin/echo PID1 > tasks
+ # /bin/echo PID2 > tasks
+ ...
+ # /bin/echo PIDn > tasks
-You can attach the current shell task by echoing 0:
+You can attach the current shell task by echoing 0::
-# echo 0 > tasks
+ # echo 0 > tasks
You can use the cgroup.procs file instead of the tasks file to move all
threads in a threadgroup at once. Echoing the PID of any task in a
@@ -529,7 +545,7 @@ Each subsystem may export the following methods. The only mandatory
methods are css_alloc/free. Any others that are null are presumed to
be successful no-ops.
-struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)
+``struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)``
(cgroup_mutex held by caller)
Called to allocate a subsystem state object for a cgroup. The
@@ -544,7 +560,7 @@ identified by the passed cgroup object having a NULL parent (since
it's the root of the hierarchy) and may be an appropriate place for
initialization code.
-int css_online(struct cgroup *cgrp)
+``int css_online(struct cgroup *cgrp)``
(cgroup_mutex held by caller)
Called after @cgrp successfully completed all allocations and made
@@ -554,7 +570,7 @@ callback can be used to implement reliable state sharing and
propagation along the hierarchy. See the comment on
cgroup_for_each_descendant_pre() for details.
-void css_offline(struct cgroup *cgrp);
+``void css_offline(struct cgroup *cgrp);``
(cgroup_mutex held by caller)
This is the counterpart of css_online() and called iff css_online()
@@ -564,7 +580,7 @@ all references it's holding on @cgrp. When all references are dropped,
cgroup removal will proceed to the next step - css_free(). After this
callback, @cgrp should be considered dead to the subsystem.
-void css_free(struct cgroup *cgrp)
+``void css_free(struct cgroup *cgrp)``
(cgroup_mutex held by caller)
The cgroup system is about to free @cgrp; the subsystem should free
@@ -573,7 +589,7 @@ is completely unused; @cgrp->parent is still valid. (Note - can also
be called for a newly-created cgroup if an error occurs after this
subsystem's create() method has been called for the new cgroup).
-int can_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)
+``int can_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
(cgroup_mutex held by caller)
Called prior to moving one or more tasks into a cgroup; if the
@@ -594,7 +610,7 @@ fork. If this method returns 0 (success) then this should remain valid
while the caller holds cgroup_mutex and it is ensured that either
attach() or cancel_attach() will be called in future.
-void css_reset(struct cgroup_subsys_state *css)
+``void css_reset(struct cgroup_subsys_state *css)``
(cgroup_mutex held by caller)
An optional operation which should restore @css's configuration to the
@@ -608,7 +624,7 @@ This prevents unexpected resource control from a hidden css and
ensures that the configuration is in the initial state when it is made
visible again later.
-void cancel_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)
+``void cancel_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
(cgroup_mutex held by caller)
Called when a task attach operation has failed after can_attach() has succeeded.
@@ -617,26 +633,26 @@ function, so that the subsystem can implement a rollback. If not, not necessary.
This will be called only about subsystems whose can_attach() operation have
succeeded. The parameters are identical to can_attach().
-void attach(struct cgroup *cgrp, struct cgroup_taskset *tset)
+``void attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
(cgroup_mutex held by caller)
Called after the task has been attached to the cgroup, to allow any
post-attachment activity that requires memory allocations or blocking.
The parameters are identical to can_attach().
-void fork(struct task_struct *task)
+``void fork(struct task_struct *task)``
Called when a task is forked into a cgroup.
-void exit(struct task_struct *task)
+``void exit(struct task_struct *task)``
Called during task exit.
-void free(struct task_struct *task)
+``void free(struct task_struct *task)``
Called when the task_struct is freed.
-void bind(struct cgroup *root)
+``void bind(struct cgroup *root)``
(cgroup_mutex held by caller)
Called when a cgroup subsystem is rebound to a different hierarchy
@@ -649,6 +665,7 @@ that is being created/destroyed (and hence has no sub-cgroups).
cgroup filesystem supports certain types of extended attributes in its
directories and files. The current supported types are:
+
- Trusted (XATTR_TRUSTED)
- Security (XATTR_SECURITY)
@@ -666,12 +683,13 @@ in containers and systemd for assorted meta data like main PID in a cgroup
5. Questions
============
-Q: what's up with this '/bin/echo' ?
-A: bash's builtin 'echo' command does not check calls to write() against
- errors. If you use it in the cgroup file system, you won't be
- able to tell whether a command succeeded or failed.
+::
-Q: When I attach processes, only the first of the line gets really attached !
-A: We can only return one error code per call to write(). So you should also
- put only ONE PID.
+ Q: what's up with this '/bin/echo' ?
+ A: bash's builtin 'echo' command does not check calls to write() against
+ errors. If you use it in the cgroup file system, you won't be
+ able to tell whether a command succeeded or failed.
+ Q: When I attach processes, only the first of the line gets really attached !
+ A: We can only return one error code per call to write(). So you should also
+ put only ONE PID.
diff --git a/Documentation/cgroup-v1/cpuacct.txt b/Documentation/cgroup-v1/cpuacct.rst
similarity index 90%
rename from Documentation/cgroup-v1/cpuacct.txt
rename to Documentation/cgroup-v1/cpuacct.rst
index 9d73cc0cadb9..d30ed81d2ad7 100644
--- a/Documentation/cgroup-v1/cpuacct.txt
+++ b/Documentation/cgroup-v1/cpuacct.rst
@@ -1,5 +1,6 @@
+=========================
CPU Accounting Controller
--------------------------
+=========================
The CPU accounting controller is used to group tasks using cgroups and
account the CPU usage of these groups of tasks.
@@ -8,9 +9,9 @@ The CPU accounting controller supports multi-hierarchy groups. An accounting
group accumulates the CPU usage of all of its child groups and the tasks
directly present in its group.
-Accounting groups can be created by first mounting the cgroup filesystem.
+Accounting groups can be created by first mounting the cgroup filesystem::
-# mount -t cgroup -ocpuacct none /sys/fs/cgroup
+ # mount -t cgroup -ocpuacct none /sys/fs/cgroup
With the above step, the initial or the parent accounting group becomes
visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
@@ -19,11 +20,11 @@ the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
by this group which is essentially the CPU time obtained by all the tasks
in the system.
-New accounting groups can be created under the parent group /sys/fs/cgroup.
+New accounting groups can be created under the parent group /sys/fs/cgroup::
-# cd /sys/fs/cgroup
-# mkdir g1
-# echo $$ > g1/tasks
+ # cd /sys/fs/cgroup
+ # mkdir g1
+ # echo $$ > g1/tasks
The above steps create a new group g1 and move the current shell
process (bash) into it. CPU time consumed by this bash and its children
diff --git a/Documentation/cgroup-v1/cpusets.txt b/Documentation/cgroup-v1/cpusets.rst
similarity index 90%
rename from Documentation/cgroup-v1/cpusets.txt
rename to Documentation/cgroup-v1/cpusets.rst
index 8402dd6de8df..b6a42cdea72b 100644
--- a/Documentation/cgroup-v1/cpusets.txt
+++ b/Documentation/cgroup-v1/cpusets.rst
@@ -1,35 +1,36 @@
- CPUSETS
- -------
+=======
+CPUSETS
+=======
Copyright (C) 2004 BULL SA.
+
Written by [email protected]
-Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
-Modified by Paul Jackson <[email protected]>
-Modified by Christoph Lameter <[email protected]>
-Modified by Paul Menage <[email protected]>
-Modified by Hidetoshi Seto <[email protected]>
+- Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
+- Modified by Paul Jackson <[email protected]>
+- Modified by Christoph Lameter <[email protected]>
+- Modified by Paul Menage <[email protected]>
+- Modified by Hidetoshi Seto <[email protected]>
-CONTENTS:
-=========
+.. CONTENTS:
-1. Cpusets
- 1.1 What are cpusets ?
- 1.2 Why are cpusets needed ?
- 1.3 How are cpusets implemented ?
- 1.4 What are exclusive cpusets ?
- 1.5 What is memory_pressure ?
- 1.6 What is memory spread ?
- 1.7 What is sched_load_balance ?
- 1.8 What is sched_relax_domain_level ?
- 1.9 How do I use cpusets ?
-2. Usage Examples and Syntax
- 2.1 Basic Usage
- 2.2 Adding/removing cpus
- 2.3 Setting flags
- 2.4 Attaching processes
-3. Questions
-4. Contact
+ 1. Cpusets
+ 1.1 What are cpusets ?
+ 1.2 Why are cpusets needed ?
+ 1.3 How are cpusets implemented ?
+ 1.4 What are exclusive cpusets ?
+ 1.5 What is memory_pressure ?
+ 1.6 What is memory spread ?
+ 1.7 What is sched_load_balance ?
+ 1.8 What is sched_relax_domain_level ?
+ 1.9 How do I use cpusets ?
+ 2. Usage Examples and Syntax
+ 2.1 Basic Usage
+ 2.2 Adding/removing cpus
+ 2.3 Setting flags
+ 2.4 Attaching processes
+ 3. Questions
+ 4. Contact
1. Cpusets
==========
@@ -48,7 +49,7 @@ hooks, beyond what is already present, required to manage dynamic
job placement on large systems.
Cpusets use the generic cgroup subsystem described in
-Documentation/cgroup-v1/cgroups.txt.
+Documentation/cgroup-v1/cgroups.rst.
Requests by a task, using the sched_setaffinity(2) system call to
include CPUs in its CPU affinity mask, and using the mbind(2) and
@@ -157,7 +158,7 @@ modifying cpusets is via this cpuset file system.
The /proc/<pid>/status file for each task has four added lines,
displaying the task's cpus_allowed (on which CPUs it may be scheduled)
and mems_allowed (on which Memory Nodes it may obtain memory),
-in the two formats seen in the following example:
+in the two formats seen in the following example::
Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff
Cpus_allowed_list: 0-127
@@ -181,6 +182,7 @@ files describing that cpuset:
- cpuset.sched_relax_domain_level: the searching range when migrating tasks
In addition, only the root cpuset has the following file:
+
- cpuset.memory_pressure_enabled flag: compute memory_pressure?
New cpusets are created using the mkdir system call or shell
@@ -266,7 +268,8 @@ to monitor a cpuset for signs of memory pressure. It's up to the
batch manager or other user code to decide what to do about it and
take action.
-==> Unless this feature is enabled by writing "1" to the special file
+==>
+ Unless this feature is enabled by writing "1" to the special file
/dev/cpuset/memory_pressure_enabled, the hook in the rebalance
code of __alloc_pages() for this metric reduces to simply noticing
that the cpuset_memory_pressure_enabled flag is zero. So only
@@ -399,6 +402,7 @@ have tasks running on them unless explicitly assigned.
This default load balancing across all CPUs is not well suited for
the following two situations:
+
1) On large systems, load balancing across many CPUs is expensive.
If the system is managed using cpusets to place independent jobs
on separate sets of CPUs, full load balancing is unnecessary.
@@ -501,6 +505,7 @@ all the CPUs that must be load balanced.
The cpuset code builds a new such partition and passes it to the
scheduler sched domain setup code, to have the sched domains rebuilt
as necessary, whenever:
+
- the 'cpuset.sched_load_balance' flag of a cpuset with non-empty CPUs changes,
- or CPUs come or go from a cpuset with this flag enabled,
- or 'cpuset.sched_relax_domain_level' value of a cpuset with non-empty CPUs
@@ -553,13 +558,15 @@ this searching range as you like. This file takes int value which
indicates size of searching range in levels ideally as follows,
otherwise initial value -1 that indicates the cpuset has no request.
- -1 : no request. use system default or follow request of others.
- 0 : no search.
- 1 : search siblings (hyperthreads in a core).
- 2 : search cores in a package.
- 3 : search cpus in a node [= system wide on non-NUMA system]
- 4 : search nodes in a chunk of node [on NUMA system]
- 5 : search system wide [on NUMA system]
+====== ===========================================================
+ -1 no request. use system default or follow request of others.
+ 0 no search.
+ 1 search siblings (hyperthreads in a core).
+ 2 search cores in a package.
+ 3 search cpus in a node [= system wide on non-NUMA system]
+ 4 search nodes in a chunk of node [on NUMA system]
+ 5 search system wide [on NUMA system]
+====== ===========================================================
The system default is architecture dependent. The system default
can be changed using the relax_domain_level= boot parameter.
@@ -578,13 +585,14 @@ and whether it is acceptable or not depends on your situation.
Don't modify this file if you are not sure.
If your situation is:
+
- The migration costs between each cpu can be assumed considerably
small(for you) due to your special application's behavior or
special hardware support for CPU cache etc.
- The searching cost doesn't have impact(for you) or you can make
the searching cost enough small by managing cpuset to compact etc.
- The latency is required even it sacrifices cache hit rate etc.
-then increasing 'sched_relax_domain_level' would benefit you.
+ then increasing 'sched_relax_domain_level' would benefit you.
1.9 How do I use cpusets ?
@@ -678,7 +686,7 @@ To start a new job that is to be contained within a cpuset, the steps are:
For example, the following sequence of commands will setup a cpuset
named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
-and then start a subshell 'sh' in that cpuset:
+and then start a subshell 'sh' in that cpuset::
mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
cd /sys/fs/cgroup/cpuset
@@ -693,6 +701,7 @@ and then start a subshell 'sh' in that cpuset:
cat /proc/self/cpuset
There are ways to query or modify cpusets:
+
- via the cpuset file system directly, using the various cd, mkdir, echo,
cat, rmdir commands from the shell, or their equivalent from C.
- via the C library libcpuset.
@@ -722,115 +731,133 @@ Then under /sys/fs/cgroup/cpuset you can find a tree that corresponds to the
tree of the cpusets in the system. For instance, /sys/fs/cgroup/cpuset
is the cpuset that holds the whole system.
-If you want to create a new cpuset under /sys/fs/cgroup/cpuset:
-# cd /sys/fs/cgroup/cpuset
-# mkdir my_cpuset
+If you want to create a new cpuset under /sys/fs/cgroup/cpuset::
-Now you want to do something with this cpuset.
-# cd my_cpuset
+ # cd /sys/fs/cgroup/cpuset
+ # mkdir my_cpuset
-In this directory you can find several files:
-# ls
-cgroup.clone_children cpuset.memory_pressure
-cgroup.event_control cpuset.memory_spread_page
-cgroup.procs cpuset.memory_spread_slab
-cpuset.cpu_exclusive cpuset.mems
-cpuset.cpus cpuset.sched_load_balance
-cpuset.mem_exclusive cpuset.sched_relax_domain_level
-cpuset.mem_hardwall notify_on_release
-cpuset.memory_migrate tasks
+Now you want to do something with this cpuset::
+
+ # cd my_cpuset
+
+In this directory you can find several files::
+
+ # ls
+ cgroup.clone_children cpuset.memory_pressure
+ cgroup.event_control cpuset.memory_spread_page
+ cgroup.procs cpuset.memory_spread_slab
+ cpuset.cpu_exclusive cpuset.mems
+ cpuset.cpus cpuset.sched_load_balance
+ cpuset.mem_exclusive cpuset.sched_relax_domain_level
+ cpuset.mem_hardwall notify_on_release
+ cpuset.memory_migrate tasks
Reading them will give you information about the state of this cpuset:
the CPUs and Memory Nodes it can use, the processes that are using
it, its properties. By writing to these files you can manipulate
the cpuset.
-Set some flags:
-# /bin/echo 1 > cpuset.cpu_exclusive
+Set some flags::
-Add some cpus:
-# /bin/echo 0-7 > cpuset.cpus
+ # /bin/echo 1 > cpuset.cpu_exclusive
-Add some mems:
-# /bin/echo 0-7 > cpuset.mems
+Add some cpus::
-Now attach your shell to this cpuset:
-# /bin/echo $$ > tasks
+ # /bin/echo 0-7 > cpuset.cpus
+
+Add some mems::
+
+ # /bin/echo 0-7 > cpuset.mems
+
+Now attach your shell to this cpuset::
+
+ # /bin/echo $$ > tasks
You can also create cpusets inside your cpuset by using mkdir in this
-directory.
-# mkdir my_sub_cs
+directory::
+
+ # mkdir my_sub_cs
+
+To remove a cpuset, just use rmdir::
+
+ # rmdir my_sub_cs
-To remove a cpuset, just use rmdir:
-# rmdir my_sub_cs
This will fail if the cpuset is in use (has cpusets inside, or has
processes attached).
Note that for legacy reasons, the "cpuset" filesystem exists as a
wrapper around the cgroup filesystem.
-The command
+The command::
-mount -t cpuset X /sys/fs/cgroup/cpuset
+ mount -t cpuset X /sys/fs/cgroup/cpuset
-is equivalent to
+is equivalent to::
-mount -t cgroup -ocpuset,noprefix X /sys/fs/cgroup/cpuset
-echo "/sbin/cpuset_release_agent" > /sys/fs/cgroup/cpuset/release_agent
+ mount -t cgroup -ocpuset,noprefix X /sys/fs/cgroup/cpuset
+ echo "/sbin/cpuset_release_agent" > /sys/fs/cgroup/cpuset/release_agent
2.2 Adding/removing cpus
------------------------
This is the syntax to use when writing in the cpus or mems files
-in cpuset directories:
+in cpuset directories::
-# /bin/echo 1-4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
-# /bin/echo 1,2,3,4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
+ # /bin/echo 1-4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
+ # /bin/echo 1,2,3,4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
To add a CPU to a cpuset, write the new list of CPUs including the
-CPU to be added. To add 6 to the above cpuset:
+CPU to be added. To add 6 to the above cpuset::
-# /bin/echo 1-4,6 > cpuset.cpus -> set cpus list to cpus 1,2,3,4,6
+ # /bin/echo 1-4,6 > cpuset.cpus -> set cpus list to cpus 1,2,3,4,6
Similarly to remove a CPU from a cpuset, write the new list of CPUs
without the CPU to be removed.
-To remove all the CPUs:
+To remove all the CPUs::
-# /bin/echo "" > cpuset.cpus -> clear cpus list
+ # /bin/echo "" > cpuset.cpus -> clear cpus list
2.3 Setting flags
-----------------
-The syntax is very simple:
+The syntax is very simple::
-# /bin/echo 1 > cpuset.cpu_exclusive -> set flag 'cpuset.cpu_exclusive'
-# /bin/echo 0 > cpuset.cpu_exclusive -> unset flag 'cpuset.cpu_exclusive'
+ # /bin/echo 1 > cpuset.cpu_exclusive -> set flag 'cpuset.cpu_exclusive'
+ # /bin/echo 0 > cpuset.cpu_exclusive -> unset flag 'cpuset.cpu_exclusive'
2.4 Attaching processes
-----------------------
-# /bin/echo PID > tasks
+::
+
+ # /bin/echo PID > tasks
Note that it is PID, not PIDs. You can only attach ONE task at a time.
-If you have several tasks to attach, you have to do it one after another:
+If you have several tasks to attach, you have to do it one after another::
-# /bin/echo PID1 > tasks
-# /bin/echo PID2 > tasks
+ # /bin/echo PID1 > tasks
+ # /bin/echo PID2 > tasks
...
-# /bin/echo PIDn > tasks
+ # /bin/echo PIDn > tasks
3. Questions
============
-Q: what's up with this '/bin/echo' ?
-A: bash's builtin 'echo' command does not check calls to write() against
+Q:
+ what's up with this '/bin/echo' ?
+
+A:
+ bash's builtin 'echo' command does not check calls to write() against
errors. If you use it in the cpuset file system, you won't be
able to tell whether a command succeeded or failed.
-Q: When I attach processes, only the first of the line gets really attached !
-A: We can only return one error code per call to write(). So you should also
+Q:
+ When I attach processes, only the first of the line gets really attached !
+
+A:
+ We can only return one error code per call to write(). So you should also
put only ONE pid.
4. Contact
diff --git a/Documentation/cgroup-v1/devices.txt b/Documentation/cgroup-v1/devices.rst
similarity index 88%
rename from Documentation/cgroup-v1/devices.txt
rename to Documentation/cgroup-v1/devices.rst
index 3c1095ca02ea..e1886783961e 100644
--- a/Documentation/cgroup-v1/devices.txt
+++ b/Documentation/cgroup-v1/devices.rst
@@ -1,6 +1,9 @@
+===========================
Device Whitelist Controller
+===========================
-1. Description:
+1. Description
+==============
Implement a cgroup to track and enforce open and mknod restrictions
on device files. A device cgroup associates a device access
@@ -16,24 +19,26 @@ devices from the whitelist or add new entries. A child cgroup can
never receive a device access which is denied by its parent.
2. User Interface
+=================
An entry is added using devices.allow, and removed using
-devices.deny. For instance
+devices.deny. For instance::
echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
allows cgroup 1 to read and mknod the device usually known as
-/dev/null. Doing
+/dev/null. Doing::
echo a > /sys/fs/cgroup/1/devices.deny
-will remove the default 'a *:* rwm' entry. Doing
+will remove the default 'a *:* rwm' entry. Doing::
echo a > /sys/fs/cgroup/1/devices.allow
will add the 'a *:* rwm' entry to the whitelist.
3. Security
+===========
Any task can move itself between cgroups. This clearly won't
suffice, but we can decide the best way to adequately restrict
@@ -50,6 +55,7 @@ A cgroup may not be granted more permissions than the cgroup's
parent has.
4. Hierarchy
+============
device cgroups maintain hierarchy by making sure a cgroup never has more
access permissions than its parent. Every time an entry is written to
@@ -58,7 +64,8 @@ from their whitelist and all the locally set whitelist entries will be
re-evaluated. In case one of the locally set whitelist entries would provide
more access than the cgroup's parent, it'll be removed from the whitelist.
-Example:
+Example::
+
A
/ \
B
@@ -67,10 +74,12 @@ Example:
A allow "b 8:* rwm", "c 116:1 rw"
B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"
-If a device is denied in group A:
+If a device is denied in group A::
+
# echo "c 116:* r" > A/devices.deny
+
it'll propagate down and after revalidating B's entries, the whitelist entry
-"c 116:2 rwm" will be removed:
+"c 116:2 rwm" will be removed::
group whitelist entries denied devices
A all "b 8:* rwm", "c 116:* rw"
@@ -79,7 +88,8 @@ it'll propagate down and after revalidating B's entries, the whitelist entry
In case parent's exceptions change and local exceptions are not allowed
anymore, they'll be deleted.
-Notice that new whitelist entries will not be propagated:
+Notice that new whitelist entries will not be propagated::
+
A
/ \
B
@@ -88,24 +98,30 @@ Notice that new whitelist entries will not be propagated:
A "c 1:3 rwm", "c 1:5 r" all the rest
B "c 1:3 rwm", "c 1:5 r" all the rest
-when adding "c *:3 rwm":
+when adding ``c *:3 rwm``::
+
# echo "c *:3 rwm" >A/devices.allow
-the result:
+the result::
+
group whitelist entries denied devices
A "c *:3 rwm", "c 1:5 r" all the rest
B "c 1:3 rwm", "c 1:5 r" all the rest
-but now it'll be possible to add new entries to B:
+but now it'll be possible to add new entries to B::
+
# echo "c 2:3 rwm" >B/devices.allow
# echo "c 50:3 r" >B/devices.allow
-or even
+
+or even::
+
# echo "c *:3 rwm" >B/devices.allow
Allowing or denying all by writing 'a' to devices.allow or devices.deny will
not be possible once the device cgroups has children.
4.1 Hierarchy (internal implementation)
+---------------------------------------
device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
list of exceptions. The internal state is controlled using the same user
diff --git a/Documentation/cgroup-v1/freezer-subsystem.txt b/Documentation/cgroup-v1/freezer-subsystem.rst
similarity index 95%
rename from Documentation/cgroup-v1/freezer-subsystem.txt
rename to Documentation/cgroup-v1/freezer-subsystem.rst
index e831cb2b8394..582d3427de3f 100644
--- a/Documentation/cgroup-v1/freezer-subsystem.txt
+++ b/Documentation/cgroup-v1/freezer-subsystem.rst
@@ -1,3 +1,7 @@
+==============
+Cgroup Freezer
+==============
+
The cgroup freezer is useful to batch job management system which start
and stop sets of tasks in order to schedule the resources of a machine
according to the desires of a system administrator. This sort of program
@@ -23,7 +27,7 @@ blocked, or ignored it can be seen by waiting or ptracing parent tasks.
SIGCONT is especially unsuitable since it can be caught by the task. Any
programs designed to watch for SIGSTOP and SIGCONT could be broken by
attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can
-demonstrate this problem using nested bash shells:
+demonstrate this problem using nested bash shells::
$ echo $$
16644
@@ -93,19 +97,19 @@ The following cgroupfs files are created by cgroup freezer.
The root cgroup is non-freezable and the above interface files don't
exist.
-* Examples of usage :
+* Examples of usage::
# mkdir /sys/fs/cgroup/freezer
# mount -t cgroup -ofreezer freezer /sys/fs/cgroup/freezer
# mkdir /sys/fs/cgroup/freezer/0
# echo $some_pid > /sys/fs/cgroup/freezer/0/tasks
-to get status of the freezer subsystem :
+to get status of the freezer subsystem::
# cat /sys/fs/cgroup/freezer/0/freezer.state
THAWED
-to freeze all tasks in the container :
+to freeze all tasks in the container::
# echo FROZEN > /sys/fs/cgroup/freezer/0/freezer.state
# cat /sys/fs/cgroup/freezer/0/freezer.state
@@ -113,7 +117,7 @@ to freeze all tasks in the container :
# cat /sys/fs/cgroup/freezer/0/freezer.state
FROZEN
-to unfreeze all tasks in the container :
+to unfreeze all tasks in the container::
# echo THAWED > /sys/fs/cgroup/freezer/0/freezer.state
# cat /sys/fs/cgroup/freezer/0/freezer.state
diff --git a/Documentation/cgroup-v1/hugetlb.txt b/Documentation/cgroup-v1/hugetlb.rst
similarity index 70%
rename from Documentation/cgroup-v1/hugetlb.txt
rename to Documentation/cgroup-v1/hugetlb.rst
index 1260e5369b9b..a3902aa253a9 100644
--- a/Documentation/cgroup-v1/hugetlb.txt
+++ b/Documentation/cgroup-v1/hugetlb.rst
@@ -1,5 +1,6 @@
+==================
HugeTLB Controller
--------------------
+==================
The HugeTLB controller allows to limit the HugeTLB usage per control group and
enforces the controller limit during page fault. Since HugeTLB doesn't
@@ -16,16 +17,16 @@ With the above step, the initial or the parent HugeTLB group becomes
visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
-New groups can be created under the parent group /sys/fs/cgroup.
+New groups can be created under the parent group /sys/fs/cgroup::
-# cd /sys/fs/cgroup
-# mkdir g1
-# echo $$ > g1/tasks
+ # cd /sys/fs/cgroup
+ # mkdir g1
+ # echo $$ > g1/tasks
The above steps create a new group g1 and move the current shell
process (bash) into it.
-Brief summary of control files
+Brief summary of control files::
hugetlb.<hugepagesize>.limit_in_bytes # set/show limit of "hugepagesize" hugetlb usage
hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded
@@ -33,17 +34,17 @@ Brief summary of control files
hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB limit
For a system supporting three hugepage sizes (64k, 32M and 1G), the control
-files include:
+files include::
-hugetlb.1GB.limit_in_bytes
-hugetlb.1GB.max_usage_in_bytes
-hugetlb.1GB.usage_in_bytes
-hugetlb.1GB.failcnt
-hugetlb.64KB.limit_in_bytes
-hugetlb.64KB.max_usage_in_bytes
-hugetlb.64KB.usage_in_bytes
-hugetlb.64KB.failcnt
-hugetlb.32MB.limit_in_bytes
-hugetlb.32MB.max_usage_in_bytes
-hugetlb.32MB.usage_in_bytes
-hugetlb.32MB.failcnt
+ hugetlb.1GB.limit_in_bytes
+ hugetlb.1GB.max_usage_in_bytes
+ hugetlb.1GB.usage_in_bytes
+ hugetlb.1GB.failcnt
+ hugetlb.64KB.limit_in_bytes
+ hugetlb.64KB.max_usage_in_bytes
+ hugetlb.64KB.usage_in_bytes
+ hugetlb.64KB.failcnt
+ hugetlb.32MB.limit_in_bytes
+ hugetlb.32MB.max_usage_in_bytes
+ hugetlb.32MB.usage_in_bytes
+ hugetlb.32MB.failcnt
diff --git a/Documentation/cgroup-v1/index.rst b/Documentation/cgroup-v1/index.rst
new file mode 100644
index 000000000000..fe76d42edc11
--- /dev/null
+++ b/Documentation/cgroup-v1/index.rst
@@ -0,0 +1,30 @@
+:orphan:
+
+========================
+Control Groups version 1
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ cgroups
+
+ blkio-controller
+ cpuacct
+ cpusets
+ devices
+ freezer-subsystem
+ hugetlb
+ memcg_test
+ memory
+ net_cls
+ net_prio
+ pids
+ rdma
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/cgroup-v1/memcg_test.txt b/Documentation/cgroup-v1/memcg_test.rst
similarity index 62%
rename from Documentation/cgroup-v1/memcg_test.txt
rename to Documentation/cgroup-v1/memcg_test.rst
index 621e29ffb358..91bd18c6a514 100644
--- a/Documentation/cgroup-v1/memcg_test.txt
+++ b/Documentation/cgroup-v1/memcg_test.rst
@@ -1,32 +1,43 @@
-Memory Resource Controller(Memcg) Implementation Memo.
+=====================================================
+Memory Resource Controller(Memcg) Implementation Memo
+=====================================================
+
Last Updated: 2010/2
+
Base Kernel Version: based on 2.6.33-rc7-mm(candidate for 34).
Because VM is getting complex (one of reasons is memcg...), memcg's behavior
is complex. This is a document for memcg's internal behavior.
Please note that implementation details can be changed.
-(*) Topics on API should be in Documentation/cgroup-v1/memory.txt)
+(*) Topics on API should be in Documentation/cgroup-v1/memory.rst)
0. How to record usage ?
+========================
+
2 objects are used.
page_cgroup ....an object per page.
+
Allocated at boot or memory hotplug. Freed at memory hot removal.
swap_cgroup ... an entry per swp_entry.
+
Allocated at swapon(). Freed at swapoff().
The page_cgroup has USED bit and double count against a page_cgroup never
occurs. swap_cgroup is used only when a charged page is swapped-out.
1. Charge
+=========
a page/swp_entry may be charged (usage += PAGE_SIZE) at
mem_cgroup_try_charge()
2. Uncharge
+===========
+
a page/swp_entry may be uncharged (usage -= PAGE_SIZE) by
mem_cgroup_uncharge()
@@ -37,9 +48,12 @@ Please note that implementation details can be changed.
disappears.
3. charge-commit-cancel
+=======================
+
Memcg pages are charged in two steps:
- mem_cgroup_try_charge()
- mem_cgroup_commit_charge() or mem_cgroup_cancel_charge()
+
+ - mem_cgroup_try_charge()
+ - mem_cgroup_commit_charge() or mem_cgroup_cancel_charge()
At try_charge(), there are no flags to say "this page is charged".
at this point, usage += PAGE_SIZE.
@@ -51,6 +65,8 @@ Please note that implementation details can be changed.
Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y.
4. Anonymous
+============
+
Anonymous page is newly allocated at
- page fault into MAP_ANONYMOUS mapping.
- Copy-On-Write.
@@ -78,34 +94,45 @@ Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y.
(e) zap_pte() is called and swp_entry's refcnt -=1 -> 0.
5. Page Cache
- Page Cache is charged at
+=============
+
+ Page Cache is charged at
- add_to_page_cache_locked().
The logic is very clear. (About migration, see below)
- Note: __remove_from_page_cache() is called by remove_from_page_cache()
- and __remove_mapping().
+
+ Note:
+ __remove_from_page_cache() is called by remove_from_page_cache()
+ and __remove_mapping().
6. Shmem(tmpfs) Page Cache
+===========================
+
The best way to understand shmem's page state transition is to read
mm/shmem.c.
+
But brief explanation of the behavior of memcg around shmem will be
helpful to understand the logic.
Shmem's page (just leaf page, not direct/indirect block) can be on
+
- radix-tree of shmem's inode.
- SwapCache.
- Both on radix-tree and SwapCache. This happens at swap-in
and swap-out,
It's charged when...
+
- A new page is added to shmem's radix-tree.
- A swp page is read. (move a charge from swap_cgroup to page_cgroup)
7. Page Migration
+=================
mem_cgroup_migrate()
8. LRU
+======
Each memcg has its own private LRU. Now, its handling is under global
VM's control (means that it's handled under global pgdat->lru_lock).
Almost all routines around memcg's LRU is called by global LRU's
@@ -114,163 +141,211 @@ Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y.
A special function is mem_cgroup_isolate_pages(). This scans
memcg's private LRU and call __isolate_lru_page() to extract a page
from LRU.
+
(By __isolate_lru_page(), the page is removed from both of global and
- private LRU.)
+ private LRU.)
9. Typical Tests.
+=================
Tests for racy cases.
- 9.1 Small limit to memcg.
+9.1 Small limit to memcg.
+-------------------------
+
When you do test to do racy case, it's good test to set memcg's limit
to be very small rather than GB. Many races found in the test under
xKB or xxMB limits.
+
(Memory behavior under GB and Memory behavior under MB shows very
- different situation.)
+ different situation.)
+
+9.2 Shmem
+---------
- 9.2 Shmem
Historically, memcg's shmem handling was poor and we saw some amount
of troubles here. This is because shmem is page-cache but can be
SwapCache. Test with shmem/tmpfs is always good test.
- 9.3 Migration
+9.3 Migration
+-------------
+
For NUMA, migration is an another special case. To do easy test, cpuset
- is useful. Following is a sample script to do migration.
+ is useful. Following is a sample script to do migration::
- mount -t cgroup -o cpuset none /opt/cpuset
+ mount -t cgroup -o cpuset none /opt/cpuset
- mkdir /opt/cpuset/01
- echo 1 > /opt/cpuset/01/cpuset.cpus
- echo 0 > /opt/cpuset/01/cpuset.mems
- echo 1 > /opt/cpuset/01/cpuset.memory_migrate
- mkdir /opt/cpuset/02
- echo 1 > /opt/cpuset/02/cpuset.cpus
- echo 1 > /opt/cpuset/02/cpuset.mems
- echo 1 > /opt/cpuset/02/cpuset.memory_migrate
+ mkdir /opt/cpuset/01
+ echo 1 > /opt/cpuset/01/cpuset.cpus
+ echo 0 > /opt/cpuset/01/cpuset.mems
+ echo 1 > /opt/cpuset/01/cpuset.memory_migrate
+ mkdir /opt/cpuset/02
+ echo 1 > /opt/cpuset/02/cpuset.cpus
+ echo 1 > /opt/cpuset/02/cpuset.mems
+ echo 1 > /opt/cpuset/02/cpuset.memory_migrate
In above set, when you moves a task from 01 to 02, page migration to
node 0 to node 1 will occur. Following is a script to migrate all
- under cpuset.
- --
- move_task()
- {
- for pid in $1
- do
- /bin/echo $pid >$2/tasks 2>/dev/null
- echo -n $pid
- echo -n " "
- done
- echo END
- }
+ under cpuset.::
+
+ --
+ move_task()
+ {
+ for pid in $1
+ do
+ /bin/echo $pid >$2/tasks 2>/dev/null
+ echo -n $pid
+ echo -n " "
+ done
+ echo END
+ }
+
+ G1_TASK=`cat ${G1}/tasks`
+ G2_TASK=`cat ${G2}/tasks`
+ move_task "${G1_TASK}" ${G2} &
+ --
+
+9.4 Memory hotplug
+------------------
- G1_TASK=`cat ${G1}/tasks`
- G2_TASK=`cat ${G2}/tasks`
- move_task "${G1_TASK}" ${G2} &
- --
- 9.4 Memory hotplug.
memory hotplug test is one of good test.
- to offline memory, do following.
- # echo offline > /sys/devices/system/memory/memoryXXX/state
+
+ to offline memory, do following::
+
+ # echo offline > /sys/devices/system/memory/memoryXXX/state
+
(XXX is the place of memory)
+
This is an easy way to test page migration, too.
- 9.5 mkdir/rmdir
+9.5 mkdir/rmdir
+---------------
+
When using hierarchy, mkdir/rmdir test should be done.
- Use tests like the following.
+ Use tests like the following::
- echo 1 >/opt/cgroup/01/memory/use_hierarchy
- mkdir /opt/cgroup/01/child_a
- mkdir /opt/cgroup/01/child_b
+ echo 1 >/opt/cgroup/01/memory/use_hierarchy
+ mkdir /opt/cgroup/01/child_a
+ mkdir /opt/cgroup/01/child_b
- set limit to 01.
- add limit to 01/child_b
- run jobs under child_a and child_b
+ set limit to 01.
+ add limit to 01/child_b
+ run jobs under child_a and child_b
- create/delete following groups at random while jobs are running.
- /opt/cgroup/01/child_a/child_aa
- /opt/cgroup/01/child_b/child_bb
- /opt/cgroup/01/child_c
+ create/delete following groups at random while jobs are running::
+
+ /opt/cgroup/01/child_a/child_aa
+ /opt/cgroup/01/child_b/child_bb
+ /opt/cgroup/01/child_c
running new jobs in new group is also good.
- 9.6 Mount with other subsystems.
+9.6 Mount with other subsystems
+-------------------------------
+
Mounting with other subsystems is a good test because there is a
race and lock dependency with other cgroup subsystems.
- example)
- # mount -t cgroup none /cgroup -o cpuset,memory,cpu,devices
+ example::
+
+ # mount -t cgroup none /cgroup -o cpuset,memory,cpu,devices
and do task move, mkdir, rmdir etc...under this.
- 9.7 swapoff.
+9.7 swapoff
+-----------
+
Besides management of swap is one of complicated parts of memcg,
call path of swap-in at swapoff is not same as usual swap-in path..
It's worth to be tested explicitly.
- For example, test like following is good.
- (Shell-A)
- # mount -t cgroup none /cgroup -o memory
- # mkdir /cgroup/test
- # echo 40M > /cgroup/test/memory.limit_in_bytes
- # echo 0 > /cgroup/test/tasks
+ For example, test like following is good:
+
+ (Shell-A)::
+
+ # mount -t cgroup none /cgroup -o memory
+ # mkdir /cgroup/test
+ # echo 40M > /cgroup/test/memory.limit_in_bytes
+ # echo 0 > /cgroup/test/tasks
+
Run malloc(100M) program under this. You'll see 60M of swaps.
- (Shell-B)
- # move all tasks in /cgroup/test to /cgroup
- # /sbin/swapoff -a
- # rmdir /cgroup/test
- # kill malloc task.
+
+ (Shell-B)::
+
+ # move all tasks in /cgroup/test to /cgroup
+ # /sbin/swapoff -a
+ # rmdir /cgroup/test
+ # kill malloc task.
Of course, tmpfs v.s. swapoff test should be tested, too.
- 9.8 OOM-Killer
+9.8 OOM-Killer
+--------------
+
Out-of-memory caused by memcg's limit will kill tasks under
the memcg. When hierarchy is used, a task under hierarchy
will be killed by the kernel.
+
In this case, panic_on_oom shouldn't be invoked and tasks
in other groups shouldn't be killed.
It's not difficult to cause OOM under memcg as following.
- Case A) when you can swapoff
- #swapoff -a
- #echo 50M > /memory.limit_in_bytes
+
+ Case A) when you can swapoff::
+
+ #swapoff -a
+ #echo 50M > /memory.limit_in_bytes
+
run 51M of malloc
- Case B) when you use mem+swap limitation.
- #echo 50M > memory.limit_in_bytes
- #echo 50M > memory.memsw.limit_in_bytes
+ Case B) when you use mem+swap limitation::
+
+ #echo 50M > memory.limit_in_bytes
+ #echo 50M > memory.memsw.limit_in_bytes
+
run 51M of malloc
- 9.9 Move charges at task migration
+9.9 Move charges at task migration
+----------------------------------
+
Charges associated with a task can be moved along with task migration.
- (Shell-A)
- #mkdir /cgroup/A
- #echo $$ >/cgroup/A/tasks
+ (Shell-A)::
+
+ #mkdir /cgroup/A
+ #echo $$ >/cgroup/A/tasks
+
run some programs which uses some amount of memory in /cgroup/A.
- (Shell-B)
- #mkdir /cgroup/B
- #echo 1 >/cgroup/B/memory.move_charge_at_immigrate
- #echo "pid of the program running in group A" >/cgroup/B/tasks
+ (Shell-B)::
- You can see charges have been moved by reading *.usage_in_bytes or
+ #mkdir /cgroup/B
+ #echo 1 >/cgroup/B/memory.move_charge_at_immigrate
+ #echo "pid of the program running in group A" >/cgroup/B/tasks
+
+ You can see charges have been moved by reading ``*.usage_in_bytes`` or
memory.stat of both A and B.
- See 8.2 of Documentation/cgroup-v1/memory.txt to see what value should be
- written to move_charge_at_immigrate.
- 9.10 Memory thresholds
+ See 8.2 of Documentation/cgroup-v1/memory.rst to see what value should
+ be written to move_charge_at_immigrate.
+
+9.10 Memory thresholds
+----------------------
+
Memory controller implements memory thresholds using cgroups notification
API. You can use tools/cgroup/cgroup_event_listener.c to test it.
- (Shell-A) Create cgroup and run event listener
- # mkdir /cgroup/A
- # ./cgroup_event_listener /cgroup/A/memory.usage_in_bytes 5M
+ (Shell-A) Create cgroup and run event listener::
- (Shell-B) Add task to cgroup and try to allocate and free memory
- # echo $$ >/cgroup/A/tasks
- # a="$(dd if=/dev/zero bs=1M count=10)"
- # a=
+ # mkdir /cgroup/A
+ # ./cgroup_event_listener /cgroup/A/memory.usage_in_bytes 5M
+
+ (Shell-B) Add task to cgroup and try to allocate and free memory::
+
+ # echo $$ >/cgroup/A/tasks
+ # a="$(dd if=/dev/zero bs=1M count=10)"
+ # a=
You will see message from cgroup_event_listener every time you cross
the thresholds.
diff --git a/Documentation/cgroup-v1/memory.txt b/Documentation/cgroup-v1/memory.rst
similarity index 71%
rename from Documentation/cgroup-v1/memory.txt
rename to Documentation/cgroup-v1/memory.rst
index a33cedf85427..41bdc038dad9 100644
--- a/Documentation/cgroup-v1/memory.txt
+++ b/Documentation/cgroup-v1/memory.rst
@@ -1,22 +1,26 @@
+==========================
Memory Resource Controller
+==========================
-NOTE: This document is hopelessly outdated and it asks for a complete
+NOTE:
+ This document is hopelessly outdated and it asks for a complete
rewrite. It still contains a useful information so we are keeping it
here but make sure to check the current code if you need a deeper
understanding.
-NOTE: The Memory Resource Controller has generically been referred to as the
+NOTE:
+ The Memory Resource Controller has generically been referred to as the
memory controller in this document. Do not confuse memory controller
used here with the memory controller that is used in hardware.
-(For editors)
-In this document:
+(For editors) In this document:
When we mention a cgroup (cgroupfs's directory) with memory controller,
we call it "memory cgroup". When you see git-log and source code, you'll
see patch's title and function names tend to use "memcg".
In this document, we avoid using it.
Benefits and Purpose of the memory controller
+=============================================
The memory controller isolates the memory behaviour of a group of tasks
from the rest of the system. The article on LWN [12] mentions some probable
@@ -38,6 +42,7 @@ e. There are several other use cases; find one or use the controller just
Current Status: linux-2.6.34-mmotm(development version of 2010/April)
Features:
+
- accounting anonymous pages, file caches, swap caches usage and limiting them.
- pages are linked to per-memcg LRU exclusively, and there is no global LRU.
- optionally, memory+swap usage can be accounted and limited.
@@ -54,41 +59,48 @@ Features:
Brief summary of control files.
- tasks # attach a task(thread) and show list of threads
- cgroup.procs # show list of processes
- cgroup.event_control # an interface for event_fd()
- memory.usage_in_bytes # show current usage for memory
- (See 5.5 for details)
- memory.memsw.usage_in_bytes # show current usage for memory+Swap
- (See 5.5 for details)
- memory.limit_in_bytes # set/show limit of memory usage
- memory.memsw.limit_in_bytes # set/show limit of memory+Swap usage
- memory.failcnt # show the number of memory usage hits limits
- memory.memsw.failcnt # show the number of memory+Swap hits limits
- memory.max_usage_in_bytes # show max memory usage recorded
- memory.memsw.max_usage_in_bytes # show max memory+Swap usage recorded
- memory.soft_limit_in_bytes # set/show soft limit of memory usage
- memory.stat # show various statistics
- memory.use_hierarchy # set/show hierarchical account enabled
- memory.force_empty # trigger forced page reclaim
- memory.pressure_level # set memory pressure notifications
- memory.swappiness # set/show swappiness parameter of vmscan
- (See sysctl's vm.swappiness)
- memory.move_charge_at_immigrate # set/show controls of moving charges
- memory.oom_control # set/show oom controls.
- memory.numa_stat # show the number of memory usage per numa node
+==================================== ==========================================
+ tasks attach a task(thread) and show list of
+ threads
+ cgroup.procs show list of processes
+ cgroup.event_control an interface for event_fd()
+ memory.usage_in_bytes show current usage for memory
+ (See 5.5 for details)
+ memory.memsw.usage_in_bytes show current usage for memory+Swap
+ (See 5.5 for details)
+ memory.limit_in_bytes set/show limit of memory usage
+ memory.memsw.limit_in_bytes set/show limit of memory+Swap usage
+ memory.failcnt show the number of memory usage hits limits
+ memory.memsw.failcnt show the number of memory+Swap hits limits
+ memory.max_usage_in_bytes show max memory usage recorded
+ memory.memsw.max_usage_in_bytes show max memory+Swap usage recorded
+ memory.soft_limit_in_bytes set/show soft limit of memory usage
+ memory.stat show various statistics
+ memory.use_hierarchy set/show hierarchical account enabled
+ memory.force_empty trigger forced page reclaim
+ memory.pressure_level set memory pressure notifications
+ memory.swappiness set/show swappiness parameter of vmscan
+ (See sysctl's vm.swappiness)
+ memory.move_charge_at_immigrate set/show controls of moving charges
+ memory.oom_control set/show oom controls.
+ memory.numa_stat show the number of memory usage per numa
+ node
- memory.kmem.limit_in_bytes # set/show hard limit for kernel memory
- memory.kmem.usage_in_bytes # show current kernel memory allocation
- memory.kmem.failcnt # show the number of kernel memory usage hits limits
- memory.kmem.max_usage_in_bytes # show max kernel memory usage recorded
+ memory.kmem.limit_in_bytes set/show hard limit for kernel memory
+ memory.kmem.usage_in_bytes show current kernel memory allocation
+ memory.kmem.failcnt show the number of kernel memory usage
+ hits limits
+ memory.kmem.max_usage_in_bytes show max kernel memory usage recorded
- memory.kmem.tcp.limit_in_bytes # set/show hard limit for tcp buf memory
- memory.kmem.tcp.usage_in_bytes # show current tcp buf memory allocation
- memory.kmem.tcp.failcnt # show the number of tcp buf memory usage hits limits
- memory.kmem.tcp.max_usage_in_bytes # show max tcp buf memory usage recorded
+ memory.kmem.tcp.limit_in_bytes set/show hard limit for tcp buf memory
+ memory.kmem.tcp.usage_in_bytes show current tcp buf memory allocation
+ memory.kmem.tcp.failcnt show the number of tcp buf memory usage
+ hits limits
+ memory.kmem.tcp.max_usage_in_bytes show max tcp buf memory usage recorded
+==================================== ==========================================
1. History
+==========
The memory controller has a long history. A request for comments for the memory
controller was posted by Balbir Singh [1]. At the time the RFC was posted
@@ -103,6 +115,7 @@ at version 6; it combines both mapped (RSS) and unmapped Page
Cache Control [11].
2. Memory Control
+=================
Memory is a unique resource in the sense that it is present in a limited
amount. If a task requires a lot of CPU processing, the task can spread
@@ -120,6 +133,7 @@ are:
The memory controller is the first controller developed.
2.1. Design
+-----------
The core of the design is a counter called the page_counter. The
page_counter tracks the current memory usage and limit of the group of
@@ -127,6 +141,9 @@ processes associated with the controller. Each cgroup has a memory controller
specific data structure (mem_cgroup) associated with it.
2.2. Accounting
+---------------
+
+::
+--------------------+
| mem_cgroup |
@@ -165,6 +182,7 @@ updated. page_cgroup has its own LRU on cgroup.
(*) page_cgroup structure is allocated at boot/memory-hotplug time.
2.2.1 Accounting details
+------------------------
All mapped anon pages (RSS) and cache pages (Page Cache) are accounted.
Some pages which are never reclaimable and will not be on the LRU
@@ -191,6 +209,7 @@ Note: we just account pages-on-LRU because our purpose is to control amount
of used pages; not-on-LRU pages tend to be out-of-control from VM view.
2.3 Shared Page Accounting
+--------------------------
Shared pages are accounted on the basis of the first touch approach. The
cgroup that first touches a page is accounted for the page. The principle
@@ -207,11 +226,13 @@ be backed into memory in force, charges for pages are accounted against the
caller of swapoff rather than the users of shmem.
2.4 Swap Extension (CONFIG_MEMCG_SWAP)
+--------------------------------------
Swap Extension allows you to record charge for swap. A swapped-in page is
charged back to original page allocator if possible.
When swap is accounted, following files are added.
+
- memory.memsw.usage_in_bytes.
- memory.memsw.limit_in_bytes.
@@ -224,14 +245,16 @@ In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.
By using the memsw limit, you can avoid system OOM which can be caused by swap
shortage.
-* why 'memory+swap' rather than swap.
+**why 'memory+swap' rather than swap**
+
The global LRU(kswapd) can swap out arbitrary pages. Swap-out means
to move account from memory to swap...there is no change in usage of
memory+swap. In other words, when we want to limit the usage of swap without
affecting global LRU, memory+swap limit is better than just limiting swap from
an OS point of view.
-* What happens when a cgroup hits memory.memsw.limit_in_bytes
+**What happens when a cgroup hits memory.memsw.limit_in_bytes**
+
When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out
in this cgroup. Then, swap-out will not be done by cgroup routine and file
caches are dropped. But as mentioned above, global LRU can do swapout memory
@@ -239,6 +262,7 @@ from it for sanity of the system's memory management state. You can't forbid
it by cgroup.
2.5 Reclaim
+-----------
Each cgroup maintains a per cgroup LRU which has the same structure as
global VM. When a cgroup goes over its limit, we first try
@@ -251,29 +275,36 @@ The reclaim algorithm has not been modified for cgroups, except that
pages that are selected for reclaiming come from the per-cgroup LRU
list.
-NOTE: Reclaim does not work for the root cgroup, since we cannot set any
-limits on the root cgroup.
+NOTE:
+ Reclaim does not work for the root cgroup, since we cannot set any
+ limits on the root cgroup.
-Note2: When panic_on_oom is set to "2", the whole system will panic.
+Note2:
+ When panic_on_oom is set to "2", the whole system will panic.
When oom event notifier is registered, event will be delivered.
(See oom_control section)
2.6 Locking
+-----------
lock_page_cgroup()/unlock_page_cgroup() should not be called under
the i_pages lock.
Other lock order is following:
+
PG_locked.
- mm->page_table_lock
- pgdat->lru_lock
- lock_page_cgroup.
+ mm->page_table_lock
+ pgdat->lru_lock
+ lock_page_cgroup.
+
In many cases, just lock_page_cgroup() is called.
+
per-zone-per-cgroup LRU (cgroup's private LRU) is just guarded by
pgdat->lru_lock, it has no lock of its own.
2.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM)
+-----------------------------------------------
With the Kernel memory extension, the Memory Controller is able to limit
the amount of kernel memory used by the system. Kernel memory is fundamentally
@@ -288,6 +319,7 @@ Kernel memory limits are not imposed for the root cgroup. Usage for the root
cgroup may or may not be accounted. The memory used is accumulated into
memory.kmem.usage_in_bytes, or in a separate counter when it makes sense.
(currently only for tcp).
+
The main "kmem" counter is fed into the main counter, so kmem charges will
also be visible from the user counter.
@@ -295,36 +327,42 @@ Currently no soft limit is implemented for kernel memory. It is future work
to trigger slab reclaim when those limits are reached.
2.7.1 Current Kernel Memory resources accounted
+-----------------------------------------------
-* stack pages: every process consumes some stack pages. By accounting into
-kernel memory, we prevent new processes from being created when the kernel
-memory usage is too high.
+stack pages:
+ every process consumes some stack pages. By accounting into
+ kernel memory, we prevent new processes from being created when the kernel
+ memory usage is too high.
-* slab pages: pages allocated by the SLAB or SLUB allocator are tracked. A copy
-of each kmem_cache is created every time the cache is touched by the first time
-from inside the memcg. The creation is done lazily, so some objects can still be
-skipped while the cache is being created. All objects in a slab page should
-belong to the same memcg. This only fails to hold when a task is migrated to a
-different memcg during the page allocation by the cache.
+slab pages:
+ pages allocated by the SLAB or SLUB allocator are tracked. A copy
+ of each kmem_cache is created every time the cache is touched by the first time
+ from inside the memcg. The creation is done lazily, so some objects can still be
+ skipped while the cache is being created. All objects in a slab page should
+ belong to the same memcg. This only fails to hold when a task is migrated to a
+ different memcg during the page allocation by the cache.
-* sockets memory pressure: some sockets protocols have memory pressure
-thresholds. The Memory Controller allows them to be controlled individually
-per cgroup, instead of globally.
+sockets memory pressure:
+ some sockets protocols have memory pressure
+ thresholds. The Memory Controller allows them to be controlled individually
+ per cgroup, instead of globally.
-* tcp memory pressure: sockets memory pressure for the tcp protocol.
+tcp memory pressure:
+ sockets memory pressure for the tcp protocol.
2.7.2 Common use cases
+----------------------
Because the "kmem" counter is fed to the main user counter, kernel memory can
never be limited completely independently of user memory. Say "U" is the user
limit, and "K" the kernel limit. There are three possible ways limits can be
set:
- U != 0, K = unlimited:
+U != 0, K = unlimited:
This is the standard memcg limitation mechanism already present before kmem
accounting. Kernel memory is completely ignored.
- U != 0, K < U:
+U != 0, K < U:
Kernel memory is a subset of the user memory. This setup is useful in
deployments where the total amount of memory per-cgroup is overcommited.
Overcommiting kernel memory limits is definitely not recommended, since the
@@ -332,19 +370,23 @@ set:
In this case, the admin could set up K so that the sum of all groups is
never greater than the total memory, and freely set U at the cost of his
QoS.
- WARNING: In the current implementation, memory reclaim will NOT be
+
+WARNING:
+ In the current implementation, memory reclaim will NOT be
triggered for a cgroup when it hits K while staying below U, which makes
this setup impractical.
- U != 0, K >= U:
+U != 0, K >= U:
Since kmem charges will also be fed to the user counter and reclaim will be
triggered for the cgroup for both kinds of memory. This setup gives the
admin a unified view of memory, and it is also useful for people who just
want to track kernel memory usage.
3. User Interface
+=================
3.0. Configuration
+------------------
a. Enable CONFIG_CGROUPS
b. Enable CONFIG_MEMCG
@@ -352,39 +394,53 @@ c. Enable CONFIG_MEMCG_SWAP (to use swap extension)
d. Enable CONFIG_MEMCG_KMEM (to use kmem extension)
3.1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?)
-# mount -t tmpfs none /sys/fs/cgroup
-# mkdir /sys/fs/cgroup/memory
-# mount -t cgroup none /sys/fs/cgroup/memory -o memory
+-------------------------------------------------------------------
-3.2. Make the new group and move bash into it
-# mkdir /sys/fs/cgroup/memory/0
-# echo $$ > /sys/fs/cgroup/memory/0/tasks
+::
-Since now we're in the 0 cgroup, we can alter the memory limit:
-# echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes
+ # mount -t tmpfs none /sys/fs/cgroup
+ # mkdir /sys/fs/cgroup/memory
+ # mount -t cgroup none /sys/fs/cgroup/memory -o memory
-NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
-mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, Gibibytes.)
+3.2. Make the new group and move bash into it::
-NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited).
-NOTE: We cannot set limits on the root cgroup any more.
+ # mkdir /sys/fs/cgroup/memory/0
+ # echo $$ > /sys/fs/cgroup/memory/0/tasks
-# cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes
-4194304
+Since now we're in the 0 cgroup, we can alter the memory limit::
-We can check the usage:
-# cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
-1216512
+ # echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes
+
+NOTE:
+ We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
+ mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes,
+ Gibibytes.)
+
+NOTE:
+ We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``.
+
+NOTE:
+ We cannot set limits on the root cgroup any more.
+
+::
+
+ # cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes
+ 4194304
+
+We can check the usage::
+
+ # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
+ 1216512
A successful write to this file does not guarantee a successful setting of
this limit to the value written into the file. This can be due to a
number of factors, such as rounding up to page boundaries or the total
availability of memory on the system. The user is required to re-read
-this file after a write to guarantee the value committed by the kernel.
+this file after a write to guarantee the value committed by the kernel::
-# echo 1 > memory.limit_in_bytes
-# cat memory.limit_in_bytes
-4096
+ # echo 1 > memory.limit_in_bytes
+ # cat memory.limit_in_bytes
+ 4096
The memory.failcnt field gives the number of times that the cgroup limit was
exceeded.
@@ -393,6 +449,7 @@ The memory.stat file gives accounting information. Now, the number of
caches, RSS and Active pages/Inactive pages are shown.
4. Testing
+==========
For testing features and implementation, see memcg_test.txt.
@@ -408,6 +465,7 @@ But the above two are testing extreme situations.
Trying usual test under memory controller is always helpful.
4.1 Troubleshooting
+-------------------
Sometimes a user might find that the application under a cgroup is
terminated by the OOM killer. There are several causes for this:
@@ -422,6 +480,7 @@ To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and
seeing what happens will be helpful.
4.2 Task migration
+------------------
When a task migrates from one cgroup to another, its charge is not
carried forward by default. The pages allocated from the original cgroup still
@@ -432,6 +491,7 @@ You can move charges of a task along with task migration.
See 8. "Move charges at task migration"
4.3 Removing a cgroup
+---------------------
A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a
cgroup might have some charge associated with it, even though all
@@ -448,13 +508,15 @@ will be charged as a new owner of it.
About use_hierarchy, see Section 6.
-5. Misc. interfaces.
+5. Misc. interfaces
+===================
5.1 force_empty
+---------------
memory.force_empty interface is provided to make cgroup's memory usage empty.
- When writing anything to this
+ When writing anything to this::
- # echo 0 > memory.force_empty
+ # echo 0 > memory.force_empty
the cgroup will be reclaimed and as many pages reclaimed as possible.
@@ -471,50 +533,61 @@ About use_hierarchy, see Section 6.
About use_hierarchy, see Section 6.
5.2 stat file
+-------------
memory.stat file includes following statistics
-# per-memory cgroup local status
-cache - # of bytes of page cache memory.
-rss - # of bytes of anonymous and swap cache memory (includes
+per-memory cgroup local status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+=============== ===============================================================
+cache # of bytes of page cache memory.
+rss # of bytes of anonymous and swap cache memory (includes
transparent hugepages).
-rss_huge - # of bytes of anonymous transparent hugepages.
-mapped_file - # of bytes of mapped file (includes tmpfs/shmem)
-pgpgin - # of charging events to the memory cgroup. The charging
+rss_huge # of bytes of anonymous transparent hugepages.
+mapped_file # of bytes of mapped file (includes tmpfs/shmem)
+pgpgin # of charging events to the memory cgroup. The charging
event happens each time a page is accounted as either mapped
anon page(RSS) or cache page(Page Cache) to the cgroup.
-pgpgout - # of uncharging events to the memory cgroup. The uncharging
+pgpgout # of uncharging events to the memory cgroup. The uncharging
event happens each time a page is unaccounted from the cgroup.
-swap - # of bytes of swap usage
-dirty - # of bytes that are waiting to get written back to the disk.
-writeback - # of bytes of file/anon cache that are queued for syncing to
+swap # of bytes of swap usage
+dirty # of bytes that are waiting to get written back to the disk.
+writeback # of bytes of file/anon cache that are queued for syncing to
disk.
-inactive_anon - # of bytes of anonymous and swap cache memory on inactive
+inactive_anon # of bytes of anonymous and swap cache memory on inactive
LRU list.
-active_anon - # of bytes of anonymous and swap cache memory on active
+active_anon # of bytes of anonymous and swap cache memory on active
LRU list.
-inactive_file - # of bytes of file-backed memory on inactive LRU list.
-active_file - # of bytes of file-backed memory on active LRU list.
-unevictable - # of bytes of memory that cannot be reclaimed (mlocked etc).
+inactive_file # of bytes of file-backed memory on inactive LRU list.
+active_file # of bytes of file-backed memory on active LRU list.
+unevictable # of bytes of memory that cannot be reclaimed (mlocked etc).
+=============== ===============================================================
-# status considering hierarchy (see memory.use_hierarchy settings)
+status considering hierarchy (see memory.use_hierarchy settings)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-hierarchical_memory_limit - # of bytes of memory limit with regard to hierarchy
- under which the memory cgroup is
-hierarchical_memsw_limit - # of bytes of memory+swap limit with regard to
- hierarchy under which memory cgroup is.
+========================= ===================================================
+hierarchical_memory_limit # of bytes of memory limit with regard to hierarchy
+ under which the memory cgroup is
+hierarchical_memsw_limit # of bytes of memory+swap limit with regard to
+ hierarchy under which memory cgroup is.
-total_<counter> - # hierarchical version of <counter>, which in
- addition to the cgroup's own value includes the
- sum of all hierarchical children's values of
- <counter>, i.e. total_cache
+total_<counter> # hierarchical version of <counter>, which in
+ addition to the cgroup's own value includes the
+ sum of all hierarchical children's values of
+ <counter>, i.e. total_cache
+========================= ===================================================
-# The following additional stats are dependent on CONFIG_DEBUG_VM.
+The following additional stats are dependent on CONFIG_DEBUG_VM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-recent_rotated_anon - VM internal parameter. (see mm/vmscan.c)
-recent_rotated_file - VM internal parameter. (see mm/vmscan.c)
-recent_scanned_anon - VM internal parameter. (see mm/vmscan.c)
-recent_scanned_file - VM internal parameter. (see mm/vmscan.c)
+========================= ========================================
+recent_rotated_anon VM internal parameter. (see mm/vmscan.c)
+recent_rotated_file VM internal parameter. (see mm/vmscan.c)
+recent_scanned_anon VM internal parameter. (see mm/vmscan.c)
+recent_scanned_file VM internal parameter. (see mm/vmscan.c)
+========================= ========================================
Memo:
recent_rotated means recent frequency of LRU rotation.
@@ -525,12 +598,15 @@ Note:
Only anonymous and swap cache memory is listed as part of 'rss' stat.
This should not be confused with the true 'resident set size' or the
amount of physical memory used by the cgroup.
+
'rss + mapped_file" will give you resident set size of cgroup.
+
(Note: file and shmem may be shared among other cgroups. In that case,
- mapped_file is accounted only when the memory cgroup is owner of page
- cache.)
+ mapped_file is accounted only when the memory cgroup is owner of page
+ cache.)
5.3 swappiness
+--------------
Overrides /proc/sys/vm/swappiness for the particular group. The tunable
in the root cgroup corresponds to the global swappiness setting.
@@ -541,16 +617,19 @@ there is a swap storage available. This might lead to memcg OOM killer
if there are no file pages to reclaim.
5.4 failcnt
+-----------
A memory cgroup provides memory.failcnt and memory.memsw.failcnt files.
This failcnt(== failure count) shows the number of times that a usage counter
hit its limit. When a memory cgroup hits a limit, failcnt increases and
memory under it will be reclaimed.
-You can reset failcnt by writing 0 to failcnt file.
-# echo 0 > .../memory.failcnt
+You can reset failcnt by writing 0 to failcnt file::
+
+ # echo 0 > .../memory.failcnt
5.5 usage_in_bytes
+------------------
For efficiency, as other kernel components, memory cgroup uses some optimization
to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the
@@ -560,6 +639,7 @@ If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP)
value in memory.stat(see 5.2).
5.6 numa_stat
+-------------
This is similar to numa_maps but operates on a per-memcg basis. This is
useful for providing visibility into the numa locality information within
@@ -571,22 +651,23 @@ Each memcg's numa_stat file includes "total", "file", "anon" and "unevictable"
per-node page counts including "hierarchical_<counter>" which sums up all
hierarchical children's values in addition to the memcg's own value.
-The output format of memory.numa_stat is:
+The output format of memory.numa_stat is::
-total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ...
-file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ...
-anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
-unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
-hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ...
The "total" count is sum of file + anon + unevictable.
6. Hierarchy support
+====================
The memory controller supports a deep hierarchy and hierarchical accounting.
The hierarchy is created by creating the appropriate cgroups in the
cgroup filesystem. Consider for example, the following cgroup filesystem
-hierarchy
+hierarchy::
root
/ | \
@@ -603,24 +684,28 @@ limit, the reclaim algorithm reclaims from the tasks in the ancestor and the
children of the ancestor.
6.1 Enabling hierarchical accounting and reclaim
+------------------------------------------------
A memory cgroup by default disables the hierarchy feature. Support
-can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup
+can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup::
-# echo 1 > memory.use_hierarchy
+ # echo 1 > memory.use_hierarchy
-The feature can be disabled by
+The feature can be disabled by::
-# echo 0 > memory.use_hierarchy
+ # echo 0 > memory.use_hierarchy
-NOTE1: Enabling/disabling will fail if either the cgroup already has other
+NOTE1:
+ Enabling/disabling will fail if either the cgroup already has other
cgroups created below it, or if the parent cgroup has use_hierarchy
enabled.
-NOTE2: When panic_on_oom is set to "2", the whole system will panic in
+NOTE2:
+ When panic_on_oom is set to "2", the whole system will panic in
case of an OOM event in any cgroup.
7. Soft limits
+==============
Soft limits allow for greater sharing of memory. The idea behind soft limits
is to allow control groups to use as much of the memory as needed, provided
@@ -640,22 +725,26 @@ hints/setup. Currently soft limit based reclaim is set up such that
it gets invoked from balance_pgdat (kswapd).
7.1 Interface
+-------------
Soft limits can be setup by using the following commands (in this example we
-assume a soft limit of 256 MiB)
+assume a soft limit of 256 MiB)::
-# echo 256M > memory.soft_limit_in_bytes
+ # echo 256M > memory.soft_limit_in_bytes
-If we want to change this to 1G, we can at any time use
+If we want to change this to 1G, we can at any time use::
-# echo 1G > memory.soft_limit_in_bytes
+ # echo 1G > memory.soft_limit_in_bytes
-NOTE1: Soft limits take effect over a long period of time, since they involve
+NOTE1:
+ Soft limits take effect over a long period of time, since they involve
reclaiming memory for balancing between memory cgroups
-NOTE2: It is recommended to set the soft limit always below the hard limit,
+NOTE2:
+ It is recommended to set the soft limit always below the hard limit,
otherwise the hard limit will take precedence.
8. Move charges at task migration
+=================================
Users can move charges associated with a task along with task migration, that
is, uncharge task's pages from the old cgroup and charge them to the new cgroup.
@@ -663,60 +752,71 @@ This feature is not supported in !CONFIG_MMU environments because of lack of
page tables.
8.1 Interface
+-------------
This feature is disabled by default. It can be enabled (and disabled again) by
writing to memory.move_charge_at_immigrate of the destination cgroup.
-If you want to enable it:
+If you want to enable it::
-# echo (some positive value) > memory.move_charge_at_immigrate
+ # echo (some positive value) > memory.move_charge_at_immigrate
-Note: Each bits of move_charge_at_immigrate has its own meaning about what type
+Note:
+ Each bits of move_charge_at_immigrate has its own meaning about what type
of charges should be moved. See 8.2 for details.
-Note: Charges are moved only when you move mm->owner, in other words,
+Note:
+ Charges are moved only when you move mm->owner, in other words,
a leader of a thread group.
-Note: If we cannot find enough space for the task in the destination cgroup, we
+Note:
+ If we cannot find enough space for the task in the destination cgroup, we
try to make space by reclaiming memory. Task migration may fail if we
cannot make enough space.
-Note: It can take several seconds if you move charges much.
+Note:
+ It can take several seconds if you move charges much.
-And if you want disable it again:
+And if you want disable it again::
-# echo 0 > memory.move_charge_at_immigrate
+ # echo 0 > memory.move_charge_at_immigrate
8.2 Type of charges which can be moved
+--------------------------------------
Each bit in move_charge_at_immigrate has its own meaning about what type of
charges should be moved. But in any case, it must be noted that an account of
a page or a swap can be moved only when it is charged to the task's current
(old) memory cgroup.
- bit | what type of charges would be moved ?
- -----+------------------------------------------------------------------------
- 0 | A charge of an anonymous page (or swap of it) used by the target task.
- | You must enable Swap Extension (see 2.4) to enable move of swap charges.
- -----+------------------------------------------------------------------------
- 1 | A charge of file pages (normal file, tmpfs file (e.g. ipc shared memory)
- | and swaps of tmpfs file) mmapped by the target task. Unlike the case of
- | anonymous pages, file pages (and swaps) in the range mmapped by the task
- | will be moved even if the task hasn't done page fault, i.e. they might
- | not be the task's "RSS", but other task's "RSS" that maps the same file.
- | And mapcount of the page is ignored (the page can be moved even if
- | page_mapcount(page) > 1). You must enable Swap Extension (see 2.4) to
- | enable move of swap charges.
++---+--------------------------------------------------------------------------+
+|bit| what type of charges would be moved ? |
++===+==========================================================================+
+| 0 | A charge of an anonymous page (or swap of it) used by the target task. |
+| | You must enable Swap Extension (see 2.4) to enable move of swap charges. |
++---+--------------------------------------------------------------------------+
+| 1 | A charge of file pages (normal file, tmpfs file (e.g. ipc shared memory) |
+| | and swaps of tmpfs file) mmapped by the target task. Unlike the case of |
+| | anonymous pages, file pages (and swaps) in the range mmapped by the task |
+| | will be moved even if the task hasn't done page fault, i.e. they might |
+| | not be the task's "RSS", but other task's "RSS" that maps the same file. |
+| | And mapcount of the page is ignored (the page can be moved even if |
+| | page_mapcount(page) > 1). You must enable Swap Extension (see 2.4) to |
+| | enable move of swap charges. |
++---+--------------------------------------------------------------------------+
8.3 TODO
+--------
- All of moving charge operations are done under cgroup_mutex. It's not good
behavior to hold the mutex too long, so we may need some trick.
9. Memory thresholds
+====================
Memory cgroup implements memory thresholds using the cgroups notification
API (see cgroups.txt). It allows to register multiple memory and memsw
thresholds and gets notifications when it crosses.
To register a threshold, an application must:
+
- create an eventfd using eventfd(2);
- open memory.usage_in_bytes or memory.memsw.usage_in_bytes;
- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to
@@ -728,6 +828,7 @@ threshold in any direction.
It's applicable for root and non-root cgroup.
10. OOM Control
+===============
memory.oom_control file is for OOM notification and other controls.
@@ -736,6 +837,7 @@ API (See cgroups.txt). It allows to register multiple OOM notification
delivery and gets notification when OOM happens.
To register a notifier, an application must:
+
- create an eventfd using eventfd(2)
- open memory.oom_control file
- write string like "<event_fd> <fd of memory.oom_control>" to
@@ -752,8 +854,11 @@ If OOM-killer is disabled, tasks under cgroup will hang/sleep
in memory cgroup's OOM-waitqueue when they request accountable memory.
For running them, you have to relax the memory cgroup's OOM status by
+
* enlarge limit or reduce usage.
+
To reduce usage,
+
* kill some tasks.
* move some tasks to other group with account migration.
* remove some files (on tmpfs?)
@@ -761,11 +866,14 @@ To reduce usage,
Then, stopped tasks will work again.
At reading, current status of OOM is shown.
- oom_kill_disable 0 or 1 (if 1, oom-killer is disabled)
- under_oom 0 or 1 (if 1, the memory cgroup is under OOM, tasks may
- be stopped.)
+
+ - oom_kill_disable 0 or 1
+ (if 1, oom-killer is disabled)
+ - under_oom 0 or 1
+ (if 1, the memory cgroup is under OOM, tasks may be stopped.)
11. Memory Pressure
+===================
The pressure level notifications can be used to monitor the memory
allocation cost; based on the pressure, applications can implement
@@ -840,21 +948,22 @@ Test:
Here is a small script example that makes a new cgroup, sets up a
memory limit, sets up a notification in the cgroup and then makes child
- cgroup experience a critical pressure:
+ cgroup experience a critical pressure::
- # cd /sys/fs/cgroup/memory/
- # mkdir foo
- # cd foo
- # cgroup_event_listener memory.pressure_level low,hierarchy &
- # echo 8000000 > memory.limit_in_bytes
- # echo 8000000 > memory.memsw.limit_in_bytes
- # echo $$ > tasks
- # dd if=/dev/zero | read x
+ # cd /sys/fs/cgroup/memory/
+ # mkdir foo
+ # cd foo
+ # cgroup_event_listener memory.pressure_level low,hierarchy &
+ # echo 8000000 > memory.limit_in_bytes
+ # echo 8000000 > memory.memsw.limit_in_bytes
+ # echo $$ > tasks
+ # dd if=/dev/zero | read x
(Expect a bunch of notifications, and eventually, the oom-killer will
trigger.)
12. TODO
+========
1. Make per-cgroup scanner reclaim not-shared pages first
2. Teach controller to account for shared-pages
@@ -862,11 +971,13 @@ Test:
not yet hit but the usage is getting closer
Summary
+=======
Overall, the memory controller has been a stable controller and has been
commented and discussed quite extensively in the community.
References
+==========
1. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/
2. Singh, Balbir. Memory Controller (RSS Control),
diff --git a/Documentation/cgroup-v1/net_cls.txt b/Documentation/cgroup-v1/net_cls.rst
similarity index 50%
rename from Documentation/cgroup-v1/net_cls.txt
rename to Documentation/cgroup-v1/net_cls.rst
index ec182346dea2..a2cf272af7a0 100644
--- a/Documentation/cgroup-v1/net_cls.txt
+++ b/Documentation/cgroup-v1/net_cls.rst
@@ -1,5 +1,6 @@
+=========================
Network classifier cgroup
--------------------------
+=========================
The Network classifier cgroup provides an interface to
tag network packets with a class identifier (classid).
@@ -17,23 +18,27 @@ values is 0xAAAABBBB; AAAA is the major handle number and BBBB
is the minor handle number.
Reading net_cls.classid yields a decimal result.
-Example:
-mkdir /sys/fs/cgroup/net_cls
-mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls
-mkdir /sys/fs/cgroup/net_cls/0
-echo 0x100001 > /sys/fs/cgroup/net_cls/0/net_cls.classid
- - setting a 10:1 handle.
+Example::
-cat /sys/fs/cgroup/net_cls/0/net_cls.classid
-1048577
+ mkdir /sys/fs/cgroup/net_cls
+ mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls
+ mkdir /sys/fs/cgroup/net_cls/0
+ echo 0x100001 > /sys/fs/cgroup/net_cls/0/net_cls.classid
-configuring tc:
-tc qdisc add dev eth0 root handle 10: htb
+- setting a 10:1 handle::
-tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit
- - creating traffic class 10:1
+ cat /sys/fs/cgroup/net_cls/0/net_cls.classid
+ 1048577
-tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup
+- configuring tc::
-configuring iptables, basic example:
-iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP
+ tc qdisc add dev eth0 root handle 10: htb
+ tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit
+
+- creating traffic class 10:1::
+
+ tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup
+
+configuring iptables, basic example::
+
+ iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP
diff --git a/Documentation/cgroup-v1/net_prio.txt b/Documentation/cgroup-v1/net_prio.rst
similarity index 71%
rename from Documentation/cgroup-v1/net_prio.txt
rename to Documentation/cgroup-v1/net_prio.rst
index a82cbd28ea8a..b40905871c64 100644
--- a/Documentation/cgroup-v1/net_prio.txt
+++ b/Documentation/cgroup-v1/net_prio.rst
@@ -1,5 +1,6 @@
+=======================
Network priority cgroup
--------------------------
+=======================
The Network priority cgroup provides an interface to allow an administrator to
dynamically set the priority of network traffic generated by various
@@ -14,9 +15,9 @@ SO_PRIORITY socket option. This however, is not always possible because:
This cgroup allows an administrator to assign a process to a group which defines
the priority of egress traffic on a given interface. Network priority groups can
-be created by first mounting the cgroup filesystem.
+be created by first mounting the cgroup filesystem::
-# mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio
+ # mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio
With the above step, the initial group acting as the parent accounting group
becomes visible at '/sys/fs/cgroup/net_prio'. This group includes all tasks in
@@ -25,17 +26,18 @@ the system. '/sys/fs/cgroup/net_prio/tasks' lists the tasks in this cgroup.
Each net_prio cgroup contains two files that are subsystem specific
net_prio.prioidx
-This file is read-only, and is simply informative. It contains a unique integer
-value that the kernel uses as an internal representation of this cgroup.
+ This file is read-only, and is simply informative. It contains a unique
+ integer value that the kernel uses as an internal representation of this
+ cgroup.
net_prio.ifpriomap
-This file contains a map of the priorities assigned to traffic originating from
-processes in this group and egressing the system on various interfaces. It
-contains a list of tuples in the form <ifname priority>. Contents of this file
-can be modified by echoing a string into the file using the same tuple format.
-for example:
+ This file contains a map of the priorities assigned to traffic originating
+ from processes in this group and egressing the system on various interfaces.
+ It contains a list of tuples in the form <ifname priority>. Contents of this
+ file can be modified by echoing a string into the file using the same tuple
+ format. For example::
-echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap
+ echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap
This command would force any traffic originating from processes belonging to the
iscsi net_prio cgroup and egressing on interface eth0 to have the priority of
diff --git a/Documentation/cgroup-v1/pids.txt b/Documentation/cgroup-v1/pids.rst
similarity index 62%
rename from Documentation/cgroup-v1/pids.txt
rename to Documentation/cgroup-v1/pids.rst
index e105d708ccde..6acebd9e72c8 100644
--- a/Documentation/cgroup-v1/pids.txt
+++ b/Documentation/cgroup-v1/pids.rst
@@ -1,5 +1,6 @@
- Process Number Controller
- =========================
+=========================
+Process Number Controller
+=========================
Abstract
--------
@@ -34,55 +35,58 @@ pids.current tracks all child cgroup hierarchies, so parent/pids.current is a
superset of parent/child/pids.current.
The pids.events file contains event counters:
+
- max: Number of times fork failed because limit was hit.
Example
-------
-First, we mount the pids controller:
-# mkdir -p /sys/fs/cgroup/pids
-# mount -t cgroup -o pids none /sys/fs/cgroup/pids
+First, we mount the pids controller::
-Then we create a hierarchy, set limits and attach processes to it:
-# mkdir -p /sys/fs/cgroup/pids/parent/child
-# echo 2 > /sys/fs/cgroup/pids/parent/pids.max
-# echo $$ > /sys/fs/cgroup/pids/parent/cgroup.procs
-# cat /sys/fs/cgroup/pids/parent/pids.current
-2
-#
+ # mkdir -p /sys/fs/cgroup/pids
+ # mount -t cgroup -o pids none /sys/fs/cgroup/pids
+
+Then we create a hierarchy, set limits and attach processes to it::
+
+ # mkdir -p /sys/fs/cgroup/pids/parent/child
+ # echo 2 > /sys/fs/cgroup/pids/parent/pids.max
+ # echo $$ > /sys/fs/cgroup/pids/parent/cgroup.procs
+ # cat /sys/fs/cgroup/pids/parent/pids.current
+ 2
+ #
It should be noted that attempts to overcome the set limit (2 in this case) will
-fail:
+fail::
-# cat /sys/fs/cgroup/pids/parent/pids.current
-2
-# ( /bin/echo "Here's some processes for you." | cat )
-sh: fork: Resource temporary unavailable
-#
+ # cat /sys/fs/cgroup/pids/parent/pids.current
+ 2
+ # ( /bin/echo "Here's some processes for you." | cat )
+ sh: fork: Resource temporary unavailable
+ #
Even if we migrate to a child cgroup (which doesn't have a set limit), we will
not be able to overcome the most stringent limit in the hierarchy (in this case,
-parent's):
+parent's)::
-# echo $$ > /sys/fs/cgroup/pids/parent/child/cgroup.procs
-# cat /sys/fs/cgroup/pids/parent/pids.current
-2
-# cat /sys/fs/cgroup/pids/parent/child/pids.current
-2
-# cat /sys/fs/cgroup/pids/parent/child/pids.max
-max
-# ( /bin/echo "Here's some processes for you." | cat )
-sh: fork: Resource temporary unavailable
-#
+ # echo $$ > /sys/fs/cgroup/pids/parent/child/cgroup.procs
+ # cat /sys/fs/cgroup/pids/parent/pids.current
+ 2
+ # cat /sys/fs/cgroup/pids/parent/child/pids.current
+ 2
+ # cat /sys/fs/cgroup/pids/parent/child/pids.max
+ max
+ # ( /bin/echo "Here's some processes for you." | cat )
+ sh: fork: Resource temporary unavailable
+ #
We can set a limit that is smaller than pids.current, which will stop any new
processes from being forked at all (note that the shell itself counts towards
-pids.current):
+pids.current)::
-# echo 1 > /sys/fs/cgroup/pids/parent/pids.max
-# /bin/echo "We can't even spawn a single process now."
-sh: fork: Resource temporary unavailable
-# echo 0 > /sys/fs/cgroup/pids/parent/pids.max
-# /bin/echo "We can't even spawn a single process now."
-sh: fork: Resource temporary unavailable
-#
+ # echo 1 > /sys/fs/cgroup/pids/parent/pids.max
+ # /bin/echo "We can't even spawn a single process now."
+ sh: fork: Resource temporary unavailable
+ # echo 0 > /sys/fs/cgroup/pids/parent/pids.max
+ # /bin/echo "We can't even spawn a single process now."
+ sh: fork: Resource temporary unavailable
+ #
diff --git a/Documentation/cgroup-v1/rdma.txt b/Documentation/cgroup-v1/rdma.rst
similarity index 79%
rename from Documentation/cgroup-v1/rdma.txt
rename to Documentation/cgroup-v1/rdma.rst
index 9bdb7fd03f83..2fcb0a9bf790 100644
--- a/Documentation/cgroup-v1/rdma.txt
+++ b/Documentation/cgroup-v1/rdma.rst
@@ -1,16 +1,17 @@
- RDMA Controller
- ----------------
+===============
+RDMA Controller
+===============
-Contents
---------
+.. Contents
-1. Overview
- 1-1. What is RDMA controller?
- 1-2. Why RDMA controller needed?
- 1-3. How is RDMA controller implemented?
-2. Usage Examples
+ 1. Overview
+ 1-1. What is RDMA controller?
+ 1-2. Why RDMA controller needed?
+ 1-3. How is RDMA controller implemented?
+ 2. Usage Examples
1. Overview
+===========
1-1. What is RDMA controller?
-----------------------------
@@ -83,27 +84,34 @@ what is configured by user for a given cgroup and what is supported by
IB device.
Following resources can be accounted by rdma controller.
+
+ ========== =============================
hca_handle Maximum number of HCA Handles
hca_object Maximum number of HCA Objects
+ ========== =============================
2. Usage Examples
------------------
-
-(a) Configure resource limit:
-echo mlx4_0 hca_handle=2 hca_object=2000 > /sys/fs/cgroup/rdma/1/rdma.max
-echo ocrdma1 hca_handle=3 > /sys/fs/cgroup/rdma/2/rdma.max
-
-(b) Query resource limit:
-cat /sys/fs/cgroup/rdma/2/rdma.max
-#Output:
-mlx4_0 hca_handle=2 hca_object=2000
-ocrdma1 hca_handle=3 hca_object=max
-
-(c) Query current usage:
-cat /sys/fs/cgroup/rdma/2/rdma.current
-#Output:
-mlx4_0 hca_handle=1 hca_object=20
-ocrdma1 hca_handle=1 hca_object=23
-
-(d) Delete resource limit:
-echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max
+=================
+
+(a) Configure resource limit::
+
+ echo mlx4_0 hca_handle=2 hca_object=2000 > /sys/fs/cgroup/rdma/1/rdma.max
+ echo ocrdma1 hca_handle=3 > /sys/fs/cgroup/rdma/2/rdma.max
+
+(b) Query resource limit::
+
+ cat /sys/fs/cgroup/rdma/2/rdma.max
+ #Output:
+ mlx4_0 hca_handle=2 hca_object=2000
+ ocrdma1 hca_handle=3 hca_object=max
+
+(c) Query current usage::
+
+ cat /sys/fs/cgroup/rdma/2/rdma.current
+ #Output:
+ mlx4_0 hca_handle=1 hca_object=20
+ ocrdma1 hca_handle=1 hca_object=23
+
+(d) Delete resource limit::
+
+ echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max
diff --git a/Documentation/filesystems/tmpfs.txt b/Documentation/filesystems/tmpfs.txt
index d06e9a59a9f4..cad797a8a39e 100644
--- a/Documentation/filesystems/tmpfs.txt
+++ b/Documentation/filesystems/tmpfs.txt
@@ -98,7 +98,7 @@ A memory policy with a valid NodeList will be saved, as specified, for
use at file creation time. When a task allocates a file in the file
system, the mount option memory policy will be applied with a NodeList,
if any, modified by the calling task's cpuset constraints
-[See Documentation/cgroup-v1/cpusets.txt] and any optional flags, listed
+[See Documentation/cgroup-v1/cpusets.rst] and any optional flags, listed
below. If the resulting NodeLists is the empty set, the effective memory
policy for the file will revert to "default" policy.
diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt
index b14e03ff3528..a7514343b660 100644
--- a/Documentation/scheduler/sched-deadline.txt
+++ b/Documentation/scheduler/sched-deadline.txt
@@ -652,7 +652,7 @@ CONTENTS
-deadline tasks cannot have an affinity mask smaller that the entire
root_domain they are created on. However, affinities can be specified
- through the cpuset facility (Documentation/cgroup-v1/cpusets.txt).
+ through the cpuset facility (Documentation/cgroup-v1/cpusets.rst).
5.1 SCHED_DEADLINE and cpusets HOWTO
------------------------------------
diff --git a/Documentation/scheduler/sched-design-CFS.txt b/Documentation/scheduler/sched-design-CFS.txt
index edd861c94c1b..d1328890ef28 100644
--- a/Documentation/scheduler/sched-design-CFS.txt
+++ b/Documentation/scheduler/sched-design-CFS.txt
@@ -215,7 +215,7 @@ SCHED_BATCH) tasks.
These options need CONFIG_CGROUPS to be defined, and let the administrator
create arbitrary groups of tasks, using the "cgroup" pseudo filesystem. See
- Documentation/cgroup-v1/cgroups.txt for more information about this filesystem.
+ Documentation/cgroup-v1/cgroups.rst for more information about this filesystem.
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
diff --git a/Documentation/scheduler/sched-rt-group.txt b/Documentation/scheduler/sched-rt-group.txt
index d8fce3e78457..c09f7a3fee66 100644
--- a/Documentation/scheduler/sched-rt-group.txt
+++ b/Documentation/scheduler/sched-rt-group.txt
@@ -133,7 +133,7 @@ This uses the cgroup virtual file system and "<cgroup>/cpu.rt_runtime_us"
to control the CPU time reserved for each control group.
For more information on working with control groups, you should read
-Documentation/cgroup-v1/cgroups.txt as well.
+Documentation/cgroup-v1/cgroups.rst as well.
Group settings are checked against the following limits in order to keep the
configuration schedulable:
diff --git a/Documentation/vm/numa.rst b/Documentation/vm/numa.rst
index 5cae13e9a08b..0d830edae8fe 100644
--- a/Documentation/vm/numa.rst
+++ b/Documentation/vm/numa.rst
@@ -67,7 +67,7 @@ nodes. Each emulated node will manage a fraction of the underlying cells'
physical memory. NUMA emluation is useful for testing NUMA kernel and
application features on non-NUMA platforms, and as a sort of memory resource
management mechanism when used together with cpusets.
-[see Documentation/cgroup-v1/cpusets.txt]
+[see Documentation/cgroup-v1/cpusets.rst]
For each node with memory, Linux constructs an independent memory management
subsystem, complete with its own free page lists, in-use page lists, usage
@@ -114,7 +114,7 @@ allocation behavior using Linux NUMA memory policy. [see
System administrators can restrict the CPUs and nodes' memories that a non-
privileged user can specify in the scheduling or NUMA commands and functions
-using control groups and CPUsets. [see Documentation/cgroup-v1/cpusets.txt]
+using control groups and CPUsets. [see Documentation/cgroup-v1/cpusets.rst]
On architectures that do not hide memoryless nodes, Linux will include only
zones [nodes] with memory in the zonelists. This means that for a memoryless
diff --git a/Documentation/vm/page_migration.rst b/Documentation/vm/page_migration.rst
index f68d61335abb..35bba27d5fff 100644
--- a/Documentation/vm/page_migration.rst
+++ b/Documentation/vm/page_migration.rst
@@ -41,7 +41,7 @@ locations.
Larger installations usually partition the system using cpusets into
sections of nodes. Paul Jackson has equipped cpusets with the ability to
move pages when a task is moved to another cpuset (See
-Documentation/cgroup-v1/cpusets.txt).
+Documentation/cgroup-v1/cpusets.rst).
Cpusets allows the automation of process locality. If a task is moved to
a new cpuset then also all its pages are moved with it so that the
performance of the process does not sink dramatically. Also the pages
diff --git a/Documentation/vm/unevictable-lru.rst b/Documentation/vm/unevictable-lru.rst
index b8e29f977f2d..c6d94118fbcc 100644
--- a/Documentation/vm/unevictable-lru.rst
+++ b/Documentation/vm/unevictable-lru.rst
@@ -98,7 +98,7 @@ Memory Control Group Interaction
--------------------------------
The unevictable LRU facility interacts with the memory control group [aka
-memory controller; see Documentation/cgroup-v1/memory.txt] by extending the
+memory controller; see Documentation/cgroup-v1/memory.rst] by extending the
lru_list enum.
The memory controller data structure automatically gets a per-zone unevictable
diff --git a/Documentation/x86/x86_64/fake-numa-for-cpusets.rst b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst
index 04df57b9aa3f..30108684ae87 100644
--- a/Documentation/x86/x86_64/fake-numa-for-cpusets.rst
+++ b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst
@@ -15,7 +15,7 @@ assign them to cpusets and their attached tasks. This is a way of limiting the
amount of system memory that are available to a certain class of tasks.
For more information on the features of cpusets, see
-Documentation/cgroup-v1/cpusets.txt.
+Documentation/cgroup-v1/cpusets.rst.
There are a number of different configurations you can use for your needs. For
more information on the numa=fake command line option and its various ways of
configuring fake nodes, see Documentation/x86/x86_64/boot-options.rst.
@@ -40,7 +40,7 @@ A machine may be split as follows with "numa=fake=4*512," as reported by dmesg::
On node 3 totalpages: 131072
Now following the instructions for mounting the cpusets filesystem from
-Documentation/cgroup-v1/cpusets.txt, you can assign fake nodes (i.e. contiguous memory
+Documentation/cgroup-v1/cpusets.rst, you can assign fake nodes (i.e. contiguous memory
address spaces) to individual cpusets::
[root@xroads /]# mkdir exampleset
diff --git a/MAINTAINERS b/MAINTAINERS
index fd40fa26f062..8dece99b5502 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4116,7 +4116,7 @@ W: http://www.bullopensource.org/cpuset/
W: http://oss.sgi.com/projects/cpusets/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup.git
S: Maintained
-F: Documentation/cgroup-v1/cpusets.txt
+F: Documentation/cgroup-v1/cpusets.rst
F: include/linux/cpuset.h
F: kernel/cgroup/cpuset.c
diff --git a/block/Kconfig b/block/Kconfig
index 1b220101a9cb..78374cb03114 100644
--- a/block/Kconfig
+++ b/block/Kconfig
@@ -88,7 +88,7 @@ config BLK_DEV_THROTTLING
one needs to mount and use blkio cgroup controller for creating
cgroups and specifying per device IO rate policies.
- See Documentation/cgroup-v1/blkio-controller.txt for more information.
+ See Documentation/cgroup-v1/blkio-controller.rst for more information.
config BLK_DEV_THROTTLING_LOW
bool "Block throttling .low limit interface support (EXPERIMENTAL)"
diff --git a/include/linux/cgroup-defs.h b/include/linux/cgroup-defs.h
index b4e766e93f6e..c5311935239d 100644
--- a/include/linux/cgroup-defs.h
+++ b/include/linux/cgroup-defs.h
@@ -624,7 +624,7 @@ struct cftype {
/*
* Control Group subsystem type.
- * See Documentation/cgroup-v1/cgroups.txt for details
+ * See Documentation/cgroup-v1/cgroups.rst for details
*/
struct cgroup_subsys {
struct cgroup_subsys_state *(*css_alloc)(struct cgroup_subsys_state *parent_css);
diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 7c6aef253173..63a7a5edb546 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -801,7 +801,7 @@ union bpf_attr {
* based on a user-provided identifier for all traffic coming from
* the tasks belonging to the related cgroup. See also the related
* kernel documentation, available from the Linux sources in file
- * *Documentation/cgroup-v1/net_cls.txt*.
+ * *Documentation/cgroup-v1/net_cls.rst*.
*
* The Linux kernel has two versions for cgroups: there are
* cgroups v1 and cgroups v2. Both are available to users, who can
diff --git a/init/Kconfig b/init/Kconfig
index 2f7f52c5efb8..ab41ffa08d79 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -797,7 +797,7 @@ config BLK_CGROUP
CONFIG_CFQ_GROUP_IOSCHED=y; for enabling throttling policy, set
CONFIG_BLK_DEV_THROTTLING=y.
- See Documentation/cgroup-v1/blkio-controller.txt for more information.
+ See Documentation/cgroup-v1/blkio-controller.rst for more information.
config DEBUG_BLK_CGROUP
bool "IO controller debugging"
diff --git a/kernel/cgroup/cpuset.c b/kernel/cgroup/cpuset.c
index fe90fa1899e6..92c515885f93 100644
--- a/kernel/cgroup/cpuset.c
+++ b/kernel/cgroup/cpuset.c
@@ -729,7 +729,7 @@ static inline int nr_cpusets(void)
* load balancing domains (sched domains) as specified by that partial
* partition.
*
- * See "What is sched_load_balance" in Documentation/cgroup-v1/cpusets.txt
+ * See "What is sched_load_balance" in Documentation/cgroup-v1/cpusets.rst
* for a background explanation of this.
*
* Does not return errors, on the theory that the callers of this
diff --git a/security/device_cgroup.c b/security/device_cgroup.c
index dc28914fa72e..c07196502577 100644
--- a/security/device_cgroup.c
+++ b/security/device_cgroup.c
@@ -509,7 +509,7 @@ static inline int may_allow_all(struct dev_cgroup *parent)
* This is one of the three key functions for hierarchy implementation.
* This function is responsible for re-evaluating all the cgroup's active
* exceptions due to a parent's exception change.
- * Refer to Documentation/cgroup-v1/devices.txt for more details.
+ * Refer to Documentation/cgroup-v1/devices.rst for more details.
*/
static void revalidate_active_exceptions(struct dev_cgroup *devcg)
{
diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h
index 7c6aef253173..63a7a5edb546 100644
--- a/tools/include/uapi/linux/bpf.h
+++ b/tools/include/uapi/linux/bpf.h
@@ -801,7 +801,7 @@ union bpf_attr {
* based on a user-provided identifier for all traffic coming from
* the tasks belonging to the related cgroup. See also the related
* kernel documentation, available from the Linux sources in file
- * *Documentation/cgroup-v1/net_cls.txt*.
+ * *Documentation/cgroup-v1/net_cls.rst*.
*
* The Linux kernel has two versions for cgroups: there are
* cgroups v1 and cgroups v2. Both are available to users, who can
--
2.21.0
Convert all text files with s390 documentation to ReST format.
Tried to preserve as much as possible the original document
format. Still, some of the files required some work in order
for it to be visible on both plain text and after converted
to 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 <[email protected]>
---
.../admin-guide/kernel-parameters.txt | 4 +-
Documentation/driver-api/s390-drivers.rst | 4 +-
Documentation/s390/{3270.txt => 3270.rst} | 85 +-
Documentation/s390/{cds.txt => cds.rst} | 354 ++-
.../s390/{CommonIO => common_io.rst} | 49 +-
Documentation/s390/{DASD => dasd.rst} | 33 +-
.../{Debugging390.txt => debugging390.rst} | 2389 ++++++++++-------
.../{driver-model.txt => driver-model.rst} | 179 +-
Documentation/s390/index.rst | 30 +
.../s390/{monreader.txt => monreader.rst} | 85 +-
Documentation/s390/{qeth.txt => qeth.rst} | 36 +-
.../s390/{s390dbf.txt => s390dbf.rst} | 798 +++---
Documentation/s390/text_files.rst | 11 +
.../s390/{vfio-ap.txt => vfio-ap.rst} | 487 ++--
.../s390/{vfio-ccw.txt => vfio-ccw.rst} | 90 +-
.../s390/{zfcpdump.txt => zfcpdump.rst} | 2 +
MAINTAINERS | 4 +-
arch/s390/Kconfig | 4 +-
arch/s390/include/asm/debug.h | 4 +-
drivers/s390/char/zcore.c | 2 +-
20 files changed, 2753 insertions(+), 1897 deletions(-)
rename Documentation/s390/{3270.txt => 3270.rst} (90%)
rename Documentation/s390/{cds.txt => cds.rst} (64%)
rename Documentation/s390/{CommonIO => common_io.rst} (87%)
rename Documentation/s390/{DASD => dasd.rst} (92%)
rename Documentation/s390/{Debugging390.txt => debugging390.rst} (53%)
rename Documentation/s390/{driver-model.txt => driver-model.rst} (73%)
create mode 100644 Documentation/s390/index.rst
rename Documentation/s390/{monreader.txt => monreader.rst} (81%)
rename Documentation/s390/{qeth.txt => qeth.rst} (62%)
rename Documentation/s390/{s390dbf.txt => s390dbf.rst} (43%)
create mode 100644 Documentation/s390/text_files.rst
rename Documentation/s390/{vfio-ap.txt => vfio-ap.rst} (72%)
rename Documentation/s390/{vfio-ccw.txt => vfio-ccw.rst} (89%)
rename Documentation/s390/{zfcpdump.txt => zfcpdump.rst} (97%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index df96a896fafa..0092a453f7dc 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -478,7 +478,7 @@
others).
ccw_timeout_log [S390]
- See Documentation/s390/CommonIO for details.
+ See Documentation/s390/common_io.rst for details.
cgroup_disable= [KNL] Disable a particular controller
Format: {name of the controller(s) to disable}
@@ -516,7 +516,7 @@
/selinux/checkreqprot.
cio_ignore= [S390]
- See Documentation/s390/CommonIO for details.
+ See Documentation/s390/common_io.rst for details.
clk_ignore_unused
[CLK]
Prevents the clock framework from automatically gating
diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst
index 30e6aa7e160b..5158577bc29b 100644
--- a/Documentation/driver-api/s390-drivers.rst
+++ b/Documentation/driver-api/s390-drivers.rst
@@ -27,7 +27,7 @@ not strictly considered I/O devices. They are considered here as well,
although they are not the focus of this document.
Some additional information can also be found in the kernel source under
-Documentation/s390/driver-model.txt.
+Documentation/s390/driver-model.rst.
The css bus
===========
@@ -38,7 +38,7 @@ into several categories:
* Standard I/O subchannels, for use by the system. They have a child
device on the ccw bus and are described below.
* I/O subchannels bound to the vfio-ccw driver. See
- Documentation/s390/vfio-ccw.txt.
+ Documentation/s390/vfio-ccw.rst.
* Message subchannels. No Linux driver currently exists.
* CHSC subchannels (at most one). The chsc subchannel driver can be used
to send asynchronous chsc commands.
diff --git a/Documentation/s390/3270.txt b/Documentation/s390/3270.rst
similarity index 90%
rename from Documentation/s390/3270.txt
rename to Documentation/s390/3270.rst
index 7c715de99774..e09e77954238 100644
--- a/Documentation/s390/3270.txt
+++ b/Documentation/s390/3270.rst
@@ -1,13 +1,17 @@
+===============================
IBM 3270 Display System support
+===============================
This file describes the driver that supports local channel attachment
of IBM 3270 devices. It consists of three sections:
+
* Introduction
* Installation
* Operation
-INTRODUCTION.
+Introduction
+============
This paper describes installing and operating 3270 devices under
Linux/390. A 3270 device is a block-mode rows-and-columns terminal of
@@ -17,12 +21,12 @@ twenty and thirty years ago.
You may have 3270s in-house and not know it. If you're using the
VM-ESA operating system, define a 3270 to your virtual machine by using
the command "DEF GRAF <hex-address>" This paper presumes you will be
-defining four 3270s with the CP/CMS commands
+defining four 3270s with the CP/CMS commands:
- DEF GRAF 620
- DEF GRAF 621
- DEF GRAF 622
- DEF GRAF 623
+ - DEF GRAF 620
+ - DEF GRAF 621
+ - DEF GRAF 622
+ - DEF GRAF 623
Your network connection from VM-ESA allows you to use x3270, tn3270, or
another 3270 emulator, started from an xterm window on your PC or
@@ -34,7 +38,8 @@ This paper covers installation of the driver and operation of a
dialed-in x3270.
-INSTALLATION.
+Installation
+============
You install the driver by installing a patch, doing a kernel build, and
running the configuration script (config3270.sh, in this directory).
@@ -59,13 +64,15 @@ Use #CP TERM CONMODE 3270 to change it to 3270. If you generate only
at boot time to a 3270 if it is a 3215.
In brief, these are the steps:
+
1. Install the tub3270 patch
- 2. (If a module) add a line to a file in /etc/modprobe.d/*.conf
+ 2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf`
3. (If VM) define devices with DEF GRAF
4. Reboot
5. Configure
To test that everything works, assuming VM and x3270,
+
1. Bring up an x3270 window.
2. Use the DIAL command in that window.
3. You should immediately see a Linux login screen.
@@ -74,7 +81,8 @@ Here are the installation steps in detail:
1. The 3270 driver is a part of the official Linux kernel
source. Build a tree with the kernel source and any necessary
- patches. Then do
+ patches. Then do::
+
make oldconfig
(If you wish to disable 3215 console support, edit
.config; change CONFIG_TN3215's value to "n";
@@ -84,20 +92,22 @@ Here are the installation steps in detail:
make modules_install
2. (Perform this step only if you have configured tub3270 as a
- module.) Add a line to a file /etc/modprobe.d/*.conf to automatically
+ module.) Add a line to a file `/etc/modprobe.d/*.conf` to automatically
load the driver when it's needed. With this line added, you will see
login prompts appear on your 3270s as soon as boot is complete (or
with emulated 3270s, as soon as you dial into your vm guest using the
command "DIAL <vmguestname>"). Since the line-mode major number is
- 227, the line to add should be:
+ 227, the line to add should be::
+
alias char-major-227 tub3270
3. Define graphic devices to your vm guest machine, if you
haven't already. Define them before you reboot (reipl):
- DEFINE GRAF 620
- DEFINE GRAF 621
- DEFINE GRAF 622
- DEFINE GRAF 623
+
+ - DEFINE GRAF 620
+ - DEFINE GRAF 621
+ - DEFINE GRAF 622
+ - DEFINE GRAF 623
4. Reboot. The reboot process scans hardware devices, including
3270s, and this enables the tub3270 driver once loaded to respond
@@ -107,21 +117,23 @@ Here are the installation steps in detail:
5. Run the 3270 configuration script config3270. It is
distributed in this same directory, Documentation/s390, as
- config3270.sh. Inspect the output script it produces,
+ config3270.sh. Inspect the output script it produces,
/tmp/mkdev3270, and then run that script. This will create the
necessary character special device files and make the necessary
changes to /etc/inittab.
Then notify /sbin/init that /etc/inittab has changed, by issuing
- the telinit command with the q operand:
+ the telinit command with the q operand::
+
cd Documentation/s390
sh config3270.sh
sh /tmp/mkdev3270
telinit q
- This should be sufficient for your first time. If your 3270
+ This should be sufficient for your first time. If your 3270
configuration has changed and you're reusing config3270, you
- should follow these steps:
+ should follow these steps::
+
Change 3270 configuration
Reboot
Run config3270 and /tmp/mkdev3270
@@ -132,8 +144,10 @@ Here are the testing steps in detail:
1. Bring up an x3270 window, or use an actual hardware 3278 or
3279, or use the 3270 emulator of your choice. You would be
running the emulator on your PC or workstation. You would use
- the command, for example,
+ the command, for example::
+
x3270 vm-esa-domain-name &
+
if you wanted a 3278 Model 4 with 43 rows of 80 columns, the
default model number. The driver does not take advantage of
extended attributes.
@@ -144,7 +158,8 @@ Here are the testing steps in detail:
2. Use the DIAL command instead of the LOGIN command to connect
to one of the virtual 3270s you defined with the DEF GRAF
- commands:
+ commands::
+
dial my-vm-guest-name
3. You should immediately see a login prompt from your
@@ -171,14 +186,17 @@ Here are the testing steps in detail:
Wrong major number? Wrong minor number? There's your
problem!
- D. Do you get the message
+ D. Do you get the message::
+
"HCPDIA047E my-vm-guest-name 0620 does not exist"?
+
If so, you must issue the command "DEF GRAF 620" from your VM
3215 console and then reboot the system.
OPERATION.
+==========
The driver defines three areas on the 3270 screen: the log area, the
input area, and the status area.
@@ -203,8 +221,10 @@ which indicates no scrolling will occur. (If you hit ENTER with "Linux
Running" and nothing typed, the application receives a newline.)
You may change the scrolling timeout value. For example, the following
-command line:
+command line::
+
echo scrolltime=60 > /proc/tty/driver/tty3270
+
changes the scrolling timeout value to 60 sec. Set scrolltime to 0 if
you wish to prevent scrolling entirely.
@@ -228,7 +248,8 @@ cause an EOF also by typing "^D" and hitting ENTER.
No PF key is preassigned to cause a job suspension, but you may cause a
job suspension by typing "^Z" and hitting ENTER. You may wish to
assign this function to a PF key. To make PF7 cause job suspension,
-execute the command:
+execute the command::
+
echo pf7=^z > /proc/tty/driver/tty3270
If the input you type does not end with the two characters "^n", the
@@ -243,8 +264,10 @@ command is entered into the stack only when the input area is not made
invisible (such as for password entry) and it is not identical to the
current top entry. PF10 rotates backward through the command stack;
PF11 rotates forward. You may assign the backward function to any PF
-key (or PA key, for that matter), say, PA3, with the command:
+key (or PA key, for that matter), say, PA3, with the command::
+
echo -e pa3=\\033k > /proc/tty/driver/tty3270
+
This assigns the string ESC-k to PA3. Similarly, the string ESC-j
performs the forward function. (Rationale: In bash with vi-mode line
editing, ESC-k and ESC-j retrieve backward and forward history.
@@ -252,15 +275,19 @@ Suggestions welcome.)
Is a stack size of twenty commands not to your liking? Change it on
the fly. To change to saving the last 100 commands, execute the
-command:
+command::
+
echo recallsize=100 > /proc/tty/driver/tty3270
Have a command you issue frequently? Assign it to a PF or PA key! Use
-the command
- echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
+the command::
+
+ echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
+
to execute the commands mkdir foobar and cd foobar immediately when you
hit PF24. Want to see the command line first, before you execute it?
-Use the -n option of the echo command:
+Use the -n option of the echo command::
+
echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.rst
similarity index 64%
rename from Documentation/s390/cds.txt
rename to Documentation/s390/cds.rst
index 480a78ef5a1e..7006d8209d2e 100644
--- a/Documentation/s390/cds.txt
+++ b/Documentation/s390/cds.rst
@@ -1,14 +1,18 @@
+===========================
Linux for S/390 and zSeries
+===========================
Common Device Support (CDS)
Device Driver I/O Support Routines
-Authors : Ingo Adlung
- Cornelia Huck
+Authors:
+ - Ingo Adlung
+ - Cornelia Huck
Copyright, IBM Corp. 1999-2002
Introduction
+============
This document describes the common device support routines for Linux/390.
Different than other hardware architectures, ESA/390 has defined a unified
@@ -27,18 +31,20 @@ Operation manual (IBM Form. No. SA22-7201).
In order to build common device support for ESA/390 I/O interfaces, a
functional layer was introduced that provides generic I/O access methods to
-the hardware.
+the hardware.
-The common device support layer comprises the I/O support routines defined
-below. Some of them implement common Linux device driver interfaces, while
+The common device support layer comprises the I/O support routines defined
+below. Some of them implement common Linux device driver interfaces, while
some of them are ESA/390 platform specific.
Note:
-In order to write a driver for S/390, you also need to look into the interface
-described in Documentation/s390/driver-model.txt.
+ In order to write a driver for S/390, you also need to look into the interface
+ described in Documentation/s390/driver-model.rst.
Note for porting drivers from 2.4:
+
The major changes are:
+
* The functions use a ccw_device instead of an irq (subchannel).
* All drivers must define a ccw_driver (see driver-model.txt) and the associated
functions.
@@ -57,19 +63,16 @@ The major changes are:
ccw_device_get_ciw()
get commands from extended sense data.
-ccw_device_start()
-ccw_device_start_timeout()
-ccw_device_start_key()
-ccw_device_start_key_timeout()
+ccw_device_start(), ccw_device_start_timeout(), ccw_device_start_key(), ccw_device_start_key_timeout()
initiate an I/O request.
ccw_device_resume()
resume channel program execution.
-ccw_device_halt()
+ccw_device_halt()
terminate the current I/O request processed on the device.
-do_IRQ()
+do_IRQ()
generic interrupt routine. This function is called by the interrupt entry
routine whenever an I/O interrupt is presented to the system. The do_IRQ()
routine determines the interrupt status and calls the device specific
@@ -82,12 +85,15 @@ first level interrupt handler only and does not comprise a device driver
callable interface. Instead, the functional description of do_IO() also
describes the input to the device specific interrupt handler.
-Note: All explanations apply also to the 64 bit architecture s390x.
+Note:
+ All explanations apply also to the 64 bit architecture s390x.
Common Device Support (CDS) for Linux/390 Device Drivers
+========================================================
General Information
+-------------------
The following chapters describe the I/O related interface routines the
Linux/390 common device support (CDS) provides to allow for device specific
@@ -101,6 +107,7 @@ can be found in the architecture specific C header file
linux/arch/s390/include/asm/irq.h.
Overview of CDS interface concepts
+----------------------------------
Different to other hardware platforms, the ESA/390 architecture doesn't define
interrupt lines managed by a specific interrupt controller and bus systems
@@ -126,7 +133,7 @@ has to call every single device driver registered on this IRQ in order to
determine the device driver owning the device that raised the interrupt.
Up to kernel 2.4, Linux/390 used to provide interfaces via the IRQ (subchannel).
-For internal use of the common I/O layer, these are still there. However,
+For internal use of the common I/O layer, these are still there. However,
device drivers should use the new calling interface via the ccw_device only.
During its startup the Linux/390 system checks for peripheral devices. Each
@@ -134,7 +141,7 @@ of those devices is uniquely defined by a so called subchannel by the ESA/390
channel subsystem. While the subchannel numbers are system generated, each
subchannel also takes a user defined attribute, the so called device number.
Both subchannel number and device number cannot exceed 65535. During sysfs
-initialisation, the information about control unit type and device types that
+initialisation, the information about control unit type and device types that
imply specific I/O commands (channel command words - CCWs) in order to operate
the device are gathered. Device drivers can retrieve this set of hardware
information during their initialization step to recognize the devices they
@@ -164,18 +171,26 @@ get_ciw() - get command information word
This call enables a device driver to get information about supported commands
from the extended SenseID data.
-struct ciw *
-ccw_device_get_ciw(struct ccw_device *cdev, __u32 cmd);
+::
-cdev - The ccw_device for which the command is to be retrieved.
-cmd - The command type to be retrieved.
+ struct ciw *
+ ccw_device_get_ciw(struct ccw_device *cdev, __u32 cmd);
+
+==== ========================================================
+cdev The ccw_device for which the command is to be retrieved.
+cmd The command type to be retrieved.
+==== ========================================================
ccw_device_get_ciw() returns:
-NULL - No extended data available, invalid device or command not found.
-!NULL - The command requested.
+===== ================================================================
+ NULL No extended data available, invalid device or command not found.
+!NULL The command requested.
+===== ================================================================
-ccw_device_start() - Initiate I/O Request
+::
+
+ ccw_device_start() - Initiate I/O Request
The ccw_device_start() routines is the I/O request front-end processor. All
device driver I/O requests must be issued using this routine. A device driver
@@ -186,93 +201,105 @@ This description also covers the status information passed to the device
driver's interrupt handler as this is related to the rules (flags) defined
with the associated I/O request when calling ccw_device_start().
-int ccw_device_start(struct ccw_device *cdev,
- struct ccw1 *cpa,
- unsigned long intparm,
- __u8 lpm,
- unsigned long flags);
-int ccw_device_start_timeout(struct ccw_device *cdev,
- struct ccw1 *cpa,
- unsigned long intparm,
- __u8 lpm,
- unsigned long flags,
- int expires);
-int ccw_device_start_key(struct ccw_device *cdev,
- struct ccw1 *cpa,
- unsigned long intparm,
- __u8 lpm,
- __u8 key,
- unsigned long flags);
-int ccw_device_start_key_timeout(struct ccw_device *cdev,
- struct ccw1 *cpa,
- unsigned long intparm,
- __u8 lpm,
- __u8 key,
- unsigned long flags,
- int expires);
+::
-cdev : ccw_device the I/O is destined for
-cpa : logical start address of channel program
-user_intparm : user specific interrupt information; will be presented
- back to the device driver's interrupt handler. Allows a
- device driver to associate the interrupt with a
- particular I/O request.
-lpm : defines the channel path to be used for a specific I/O
- request. A value of 0 will make cio use the opm.
-key : the storage key to use for the I/O (useful for operating on a
- storage with a storage key != default key)
-flag : defines the action to be performed for I/O processing
-expires : timeout value in jiffies. The common I/O layer will terminate
- the running program after this and call the interrupt handler
- with ERR_PTR(-ETIMEDOUT) as irb.
+ int ccw_device_start(struct ccw_device *cdev,
+ struct ccw1 *cpa,
+ unsigned long intparm,
+ __u8 lpm,
+ unsigned long flags);
+ int ccw_device_start_timeout(struct ccw_device *cdev,
+ struct ccw1 *cpa,
+ unsigned long intparm,
+ __u8 lpm,
+ unsigned long flags,
+ int expires);
+ int ccw_device_start_key(struct ccw_device *cdev,
+ struct ccw1 *cpa,
+ unsigned long intparm,
+ __u8 lpm,
+ __u8 key,
+ unsigned long flags);
+ int ccw_device_start_key_timeout(struct ccw_device *cdev,
+ struct ccw1 *cpa,
+ unsigned long intparm,
+ __u8 lpm,
+ __u8 key,
+ unsigned long flags,
+ int expires);
-Possible flag values are :
+============= =============================================================
+cdev ccw_device the I/O is destined for
+cpa logical start address of channel program
+user_intparm user specific interrupt information; will be presented
+ back to the device driver's interrupt handler. Allows a
+ device driver to associate the interrupt with a
+ particular I/O request.
+lpm defines the channel path to be used for a specific I/O
+ request. A value of 0 will make cio use the opm.
+key the storage key to use for the I/O (useful for operating on a
+ storage with a storage key != default key)
+flag defines the action to be performed for I/O processing
+expires timeout value in jiffies. The common I/O layer will terminate
+ the running program after this and call the interrupt handler
+ with ERR_PTR(-ETIMEDOUT) as irb.
+============= =============================================================
-DOIO_ALLOW_SUSPEND - channel program may become suspended
-DOIO_DENY_PREFETCH - don't allow for CCW prefetch; usually
- this implies the channel program might
- become modified
-DOIO_SUPPRESS_INTER - don't call the handler on intermediate status
+Possible flag values are:
-The cpa parameter points to the first format 1 CCW of a channel program :
+========================= =============================================
+DOIO_ALLOW_SUSPEND channel program may become suspended
+DOIO_DENY_PREFETCH don't allow for CCW prefetch; usually
+ this implies the channel program might
+ become modified
+DOIO_SUPPRESS_INTER don't call the handler on intermediate status
+========================= =============================================
-struct ccw1 {
- __u8 cmd_code;/* command code */
- __u8 flags; /* flags, like IDA addressing, etc. */
- __u16 count; /* byte count */
- __u32 cda; /* data address */
-} __attribute__ ((packed,aligned(8)));
+The cpa parameter points to the first format 1 CCW of a channel program::
-with the following CCW flags values defined :
+ struct ccw1 {
+ __u8 cmd_code;/* command code */
+ __u8 flags; /* flags, like IDA addressing, etc. */
+ __u16 count; /* byte count */
+ __u32 cda; /* data address */
+ } __attribute__ ((packed,aligned(8)));
-CCW_FLAG_DC - data chaining
-CCW_FLAG_CC - command chaining
-CCW_FLAG_SLI - suppress incorrect length
-CCW_FLAG_SKIP - skip
-CCW_FLAG_PCI - PCI
-CCW_FLAG_IDA - indirect addressing
-CCW_FLAG_SUSPEND - suspend
+with the following CCW flags values defined:
+
+=================== =========================
+CCW_FLAG_DC data chaining
+CCW_FLAG_CC command chaining
+CCW_FLAG_SLI suppress incorrect length
+CCW_FLAG_SKIP skip
+CCW_FLAG_PCI PCI
+CCW_FLAG_IDA indirect addressing
+CCW_FLAG_SUSPEND suspend
+=================== =========================
Via ccw_device_set_options(), the device driver may specify the following
options for the device:
-DOIO_EARLY_NOTIFICATION - allow for early interrupt notification
-DOIO_REPORT_ALL - report all interrupt conditions
+========================= ======================================
+DOIO_EARLY_NOTIFICATION allow for early interrupt notification
+DOIO_REPORT_ALL report all interrupt conditions
+========================= ======================================
-The ccw_device_start() function returns :
+The ccw_device_start() function returns:
- 0 - successful completion or request successfully initiated
--EBUSY - The device is currently processing a previous I/O request, or there is
- a status pending at the device.
--ENODEV - cdev is invalid, the device is not operational or the ccw_device is
- not online.
+======== ======================================================================
+ 0 successful completion or request successfully initiated
+ -EBUSY The device is currently processing a previous I/O request, or there is
+ a status pending at the device.
+-ENODEV cdev is invalid, the device is not operational or the ccw_device is
+ not online.
+======== ======================================================================
When the I/O request completes, the CDS first level interrupt handler will
accumulate the status in a struct irb and then call the device interrupt handler.
-The intparm field will contain the value the device driver has associated with a
-particular I/O request. If a pending device status was recognized,
+The intparm field will contain the value the device driver has associated with a
+particular I/O request. If a pending device status was recognized,
intparm will be set to 0 (zero). This may happen during I/O initiation or delayed
by an alert status notification. In any case this status is not related to the
current (last) I/O request. In case of a delayed status notification no special
@@ -282,9 +309,11 @@ never started, even though ccw_device_start() returned with successful completio
The irb may contain an error value, and the device driver should check for this
first:
--ETIMEDOUT: the common I/O layer terminated the request after the specified
- timeout value
--EIO: the common I/O layer terminated the request due to an error state
+========== =================================================================
+-ETIMEDOUT the common I/O layer terminated the request after the specified
+ timeout value
+-EIO the common I/O layer terminated the request due to an error state
+========== =================================================================
If the concurrent sense flag in the extended status word (esw) in the irb is
set, the field erw.scnt in the esw describes the number of device specific
@@ -294,6 +323,7 @@ sensing by the device driver itself is required.
The device interrupt handler can use the following definitions to investigate
the primary unit check source coded in sense byte 0 :
+======================= ====
SNS0_CMD_REJECT 0x80
SNS0_INTERVENTION_REQ 0x40
SNS0_BUS_OUT_CHECK 0x20
@@ -301,36 +331,41 @@ SNS0_EQUIPMENT_CHECK 0x10
SNS0_DATA_CHECK 0x08
SNS0_OVERRUN 0x04
SNS0_INCOMPL_DOMAIN 0x01
+======================= ====
Depending on the device status, multiple of those values may be set together.
Please refer to the device specific documentation for details.
The irb->scsw.cstat field provides the (accumulated) subchannel status :
-SCHN_STAT_PCI - program controlled interrupt
-SCHN_STAT_INCORR_LEN - incorrect length
-SCHN_STAT_PROG_CHECK - program check
-SCHN_STAT_PROT_CHECK - protection check
-SCHN_STAT_CHN_DATA_CHK - channel data check
-SCHN_STAT_CHN_CTRL_CHK - channel control check
-SCHN_STAT_INTF_CTRL_CHK - interface control check
-SCHN_STAT_CHAIN_CHECK - chaining check
+========================= ============================
+SCHN_STAT_PCI program controlled interrupt
+SCHN_STAT_INCORR_LEN incorrect length
+SCHN_STAT_PROG_CHECK program check
+SCHN_STAT_PROT_CHECK protection check
+SCHN_STAT_CHN_DATA_CHK channel data check
+SCHN_STAT_CHN_CTRL_CHK channel control check
+SCHN_STAT_INTF_CTRL_CHK interface control check
+SCHN_STAT_CHAIN_CHECK chaining check
+========================= ============================
The irb->scsw.dstat field provides the (accumulated) device status :
-DEV_STAT_ATTENTION - attention
-DEV_STAT_STAT_MOD - status modifier
-DEV_STAT_CU_END - control unit end
-DEV_STAT_BUSY - busy
-DEV_STAT_CHN_END - channel end
-DEV_STAT_DEV_END - device end
-DEV_STAT_UNIT_CHECK - unit check
-DEV_STAT_UNIT_EXCEP - unit exception
+===================== =================
+DEV_STAT_ATTENTION attention
+DEV_STAT_STAT_MOD status modifier
+DEV_STAT_CU_END control unit end
+DEV_STAT_BUSY busy
+DEV_STAT_CHN_END channel end
+DEV_STAT_DEV_END device end
+DEV_STAT_UNIT_CHECK unit check
+DEV_STAT_UNIT_EXCEP unit exception
+===================== =================
Please see the ESA/390 Principles of Operation manual for details on the
individual flag meanings.
-Usage Notes :
+Usage Notes:
ccw_device_start() must be called disabled and with the ccw device lock held.
@@ -374,32 +409,39 @@ secondary status without error (alert status) is presented, this indicates
successful completion for all overlapping ccw_device_start() requests that have
been issued since the last secondary (final) status.
-Channel programs that intend to set the suspend flag on a channel command word
-(CCW) must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the
-suspend flag will cause a channel program check. At the time the channel program
-becomes suspended an intermediate interrupt will be generated by the channel
+Channel programs that intend to set the suspend flag on a channel command word
+(CCW) must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the
+suspend flag will cause a channel program check. At the time the channel program
+becomes suspended an intermediate interrupt will be generated by the channel
subsystem.
-ccw_device_resume() - Resume Channel Program Execution
+ccw_device_resume() - Resume Channel Program Execution
-If a device driver chooses to suspend the current channel program execution by
-setting the CCW suspend flag on a particular CCW, the channel program execution
-is suspended. In order to resume channel program execution the CIO layer
-provides the ccw_device_resume() routine.
+If a device driver chooses to suspend the current channel program execution by
+setting the CCW suspend flag on a particular CCW, the channel program execution
+is suspended. In order to resume channel program execution the CIO layer
+provides the ccw_device_resume() routine.
-int ccw_device_resume(struct ccw_device *cdev);
+::
-cdev - ccw_device the resume operation is requested for
+ int ccw_device_resume(struct ccw_device *cdev);
+
+==== ================================================
+cdev ccw_device the resume operation is requested for
+==== ================================================
The ccw_device_resume() function returns:
- 0 - suspended channel program is resumed
--EBUSY - status pending
--ENODEV - cdev invalid or not-operational subchannel
--EINVAL - resume function not applicable
--ENOTCONN - there is no I/O request pending for completion
+========= ==============================================
+ 0 suspended channel program is resumed
+ -EBUSY status pending
+ -ENODEV cdev invalid or not-operational subchannel
+ -EINVAL resume function not applicable
+-ENOTCONN there is no I/O request pending for completion
+========= ==============================================
Usage Notes:
+
Please have a look at the ccw_device_start() usage notes for more details on
suspended channel programs.
@@ -412,22 +454,28 @@ command is provided.
ccw_device_halt() must be called disabled and with the ccw device lock held.
-int ccw_device_halt(struct ccw_device *cdev,
- unsigned long intparm);
+::
-cdev : ccw_device the halt operation is requested for
-intparm : interruption parameter; value is only used if no I/O
- is outstanding, otherwise the intparm associated with
- the I/O request is returned
+ int ccw_device_halt(struct ccw_device *cdev,
+ unsigned long intparm);
-The ccw_device_halt() function returns :
+======= =====================================================
+cdev ccw_device the halt operation is requested for
+intparm interruption parameter; value is only used if no I/O
+ is outstanding, otherwise the intparm associated with
+ the I/O request is returned
+======= =====================================================
- 0 - request successfully initiated
--EBUSY - the device is currently busy, or status pending.
--ENODEV - cdev invalid.
--EINVAL - The device is not operational or the ccw device is not online.
+The ccw_device_halt() function returns:
-Usage Notes :
+======= ==============================================================
+ 0 request successfully initiated
+-EBUSY the device is currently busy, or status pending.
+-ENODEV cdev invalid.
+-EINVAL The device is not operational or the ccw device is not online.
+======= ==============================================================
+
+Usage Notes:
A device driver may write a never-ending channel program by writing a channel
program that at its end loops back to its beginning by means of a transfer in
@@ -438,25 +486,34 @@ can then perform an appropriate action. Prior to interrupt of an outstanding
read to a network device (with or without PCI flag) a ccw_device_halt()
is required to end the pending operation.
-ccw_device_clear() - Terminage I/O Request Processing
+::
+
+ ccw_device_clear() - Terminage I/O Request Processing
In order to terminate all I/O processing at the subchannel, the clear subchannel
(CSCH) command is used. It can be issued via ccw_device_clear().
ccw_device_clear() must be called disabled and with the ccw device lock held.
-int ccw_device_clear(struct ccw_device *cdev, unsigned long intparm);
+::
-cdev: ccw_device the clear operation is requested for
-intparm: interruption parameter (see ccw_device_halt())
+ int ccw_device_clear(struct ccw_device *cdev, unsigned long intparm);
+
+======= ===============================================
+cdev ccw_device the clear operation is requested for
+intparm interruption parameter (see ccw_device_halt())
+======= ===============================================
The ccw_device_clear() function returns:
- 0 - request successfully initiated
--ENODEV - cdev invalid
--EINVAL - The device is not operational or the ccw device is not online.
+======= ==============================================================
+ 0 request successfully initiated
+-ENODEV cdev invalid
+-EINVAL The device is not operational or the ccw device is not online.
+======= ==============================================================
Miscellaneous Support Routines
+------------------------------
This chapter describes various routines to be used in a Linux/390 device
driver programming environment.
@@ -466,7 +523,8 @@ get_ccwdev_lock()
Get the address of the device specific lock. This is then used in
spin_lock() / spin_unlock() calls.
+::
-__u8 ccw_device_get_path_mask(struct ccw_device *cdev);
+ __u8 ccw_device_get_path_mask(struct ccw_device *cdev);
Get the mask of the path currently available for cdev.
diff --git a/Documentation/s390/CommonIO b/Documentation/s390/common_io.rst
similarity index 87%
rename from Documentation/s390/CommonIO
rename to Documentation/s390/common_io.rst
index 6e0f63f343b4..846485681ce7 100644
--- a/Documentation/s390/CommonIO
+++ b/Documentation/s390/common_io.rst
@@ -1,5 +1,9 @@
-S/390 common I/O-Layer - command line parameters, procfs and debugfs entries
-============================================================================
+======================
+S/390 common I/O-Layer
+======================
+
+command line parameters, procfs and debugfs entries
+===================================================
Command line parameters
-----------------------
@@ -13,7 +17,7 @@ Command line parameters
device := {all | [!]ipldev | [!]condev | [!]<devno> | [!]<devno>-<devno>}
The given devices will be ignored by the common I/O-layer; no detection
- and device sensing will be done on any of those devices. The subchannel to
+ and device sensing will be done on any of those devices. The subchannel to
which the device in question is attached will be treated as if no device was
attached.
@@ -28,14 +32,20 @@ Command line parameters
keywords can be used to refer to the CCW based boot device and CCW console
device respectively (these are probably useful only when combined with the '!'
operator). The '!' operator will cause the I/O-layer to _not_ ignore a device.
- The command line is parsed from left to right.
+ The command line
+ is parsed from left to right.
+
+ For example::
- For example,
cio_ignore=0.0.0023-0.0.0042,0.0.4711
+
will ignore all devices ranging from 0.0.0023 to 0.0.0042 and the device
0.0.4711, if detected.
- As another example,
+
+ As another example::
+
cio_ignore=all,!0.0.4711,!0.0.fd00-0.0.fd02
+
will ignore all devices but 0.0.4711, 0.0.fd00, 0.0.fd01, 0.0.fd02.
By default, no devices are ignored.
@@ -48,40 +58,45 @@ Command line parameters
Lists the ranges of devices (by bus id) which are ignored by common I/O.
- You can un-ignore certain or all devices by piping to /proc/cio_ignore.
- "free all" will un-ignore all ignored devices,
+ You can un-ignore certain or all devices by piping to /proc/cio_ignore.
+ "free all" will un-ignore all ignored devices,
"free <device range>, <device range>, ..." will un-ignore the specified
devices.
For example, if devices 0.0.0023 to 0.0.0042 and 0.0.4711 are ignored,
+
- echo free 0.0.0030-0.0.0032 > /proc/cio_ignore
will un-ignore devices 0.0.0030 to 0.0.0032 and will leave devices 0.0.0023
to 0.0.002f, 0.0.0033 to 0.0.0042 and 0.0.4711 ignored;
- echo free 0.0.0041 > /proc/cio_ignore will furthermore un-ignore device
0.0.0041;
- - echo free all > /proc/cio_ignore will un-ignore all remaining ignored
+ - echo free all > /proc/cio_ignore will un-ignore all remaining ignored
devices.
- When a device is un-ignored, device recognition and sensing is performed and
+ When a device is un-ignored, device recognition and sensing is performed and
the device driver will be notified if possible, so the device will become
available to the system. Note that un-ignoring is performed asynchronously.
- You can also add ranges of devices to be ignored by piping to
+ You can also add ranges of devices to be ignored by piping to
/proc/cio_ignore; "add <device range>, <device range>, ..." will ignore the
specified devices.
Note: While already known devices can be added to the list of devices to be
- ignored, there will be no effect on then. However, if such a device
+ ignored, there will be no effect on then. However, if such a device
disappears and then reappears, it will then be ignored. To make
known devices go away, you need the "purge" command (see below).
- For example,
+ For example::
+
"echo add 0.0.a000-0.0.accc, 0.0.af00-0.0.afff > /proc/cio_ignore"
+
will add 0.0.a000-0.0.accc and 0.0.af00-0.0.afff to the list of ignored
devices.
- You can remove already known but now ignored devices via
+ You can remove already known but now ignored devices via::
+
"echo purge > /proc/cio_ignore"
+
All devices ignored but still registered and not online (= not in use)
will be deregistered and thus removed from the system.
@@ -115,11 +130,11 @@ debugfs entries
Various debug messages from the common I/O-layer.
- /sys/kernel/debug/s390dbf/cio_trace/hex_ascii
- Logs the calling of functions in the common I/O-layer and, if applicable,
+ Logs the calling of functions in the common I/O-layer and, if applicable,
which subchannel they were called for, as well as dumps of some data
structures (like irb in an error case).
- The level of logging can be changed to be more or less verbose by piping to
+ The level of logging can be changed to be more or less verbose by piping to
/sys/kernel/debug/s390dbf/cio_*/level a number between 0 and 6; see the
- documentation on the S/390 debug feature (Documentation/s390/s390dbf.txt)
+ documentation on the S/390 debug feature (Documentation/s390/s390dbf.rst)
for details.
diff --git a/Documentation/s390/DASD b/Documentation/s390/dasd.rst
similarity index 92%
rename from Documentation/s390/DASD
rename to Documentation/s390/dasd.rst
index 9963f1e9c98a..9e22247285c8 100644
--- a/Documentation/s390/DASD
+++ b/Documentation/s390/dasd.rst
@@ -1,4 +1,6 @@
+==================
DASD device driver
+==================
S/390's disk devices (DASDs) are managed by Linux via the DASD device
driver. It is valid for all types of DASDs and represents them to
@@ -14,14 +16,14 @@ parameters are to be given in hexadecimal notation without a leading
If you supply kernel parameters the different instances are processed
in order of appearance and a minor number is reserved for any device
covered by the supplied range up to 64 volumes. Additional DASDs are
-ignored. If you do not supply the 'dasd=' kernel parameter at all, the
+ignored. If you do not supply the 'dasd=' kernel parameter at all, the
DASD driver registers all supported DASDs of your system to a minor
number in ascending order of the subchannel number.
The driver currently supports ECKD-devices and there are stubs for
support of the FBA and CKD architectures. For the FBA architecture
only some smart data structures are missing to make the support
-complete.
+complete.
We performed our testing on 3380 and 3390 type disks of different
sizes, under VM and on the bare hardware (LPAR), using internal disks
of the multiprise as well as a RAMAC virtual array. Disks exported by
@@ -34,19 +36,22 @@ accessibility of the DASD from other OSs. In a later stage we will
provide support of partitions, maybe VTOC oriented or using a kind of
partition table in the label record.
-USAGE
+Usage
+=====
-Low-level format (?CKD only)
For using an ECKD-DASD as a Linux harddisk you have to low-level
format the tracks by issuing the BLKDASDFORMAT-ioctl on that
device. This will erase any data on that volume including IBM volume
-labels, VTOCs etc. The ioctl may take a 'struct format_data *' or
-'NULL' as an argument.
-typedef struct {
+labels, VTOCs etc. The ioctl may take a `struct format_data *` or
+'NULL' as an argument::
+
+ typedef struct {
int start_unit;
int stop_unit;
int blksize;
-} format_data_t;
+ } format_data_t;
+
When a NULL argument is passed to the BLKDASDFORMAT ioctl the whole
disk is formatted to a blocksize of 1024 bytes. Otherwise start_unit
and stop_unit are the first and last track to be formatted. If
@@ -56,17 +61,23 @@ up to the last track. blksize can be any power of two between 512 and
1kB blocks anyway and you gain approx. 50% of capacity increasing your
blksize from 512 byte to 1kB.
--Make a filesystem
+Make a filesystem
+=================
+
Then you can mk??fs the filesystem of your choice on that volume or
partition. For reasons of sanity you should build your filesystem on
-the partition /dev/dd?1 instead of the whole volume. You only lose 3kB
+the partition /dev/dd?1 instead of the whole volume. You only lose 3kB
but may be sure that you can reuse your data after introduction of a
real partition table.
-BUGS:
+Bugs
+====
+
- Performance sometimes is rather low because we don't fully exploit clustering
-TODO-List:
+TODO-List
+=========
+
- Add IBM'S Disk layout to genhd
- Enhance driver to use more than one major number
- Enable usage as a module
diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/debugging390.rst
similarity index 53%
rename from Documentation/s390/Debugging390.txt
rename to Documentation/s390/debugging390.rst
index c35804c238ad..d49305fd5e1a 100644
--- a/Documentation/s390/Debugging390.txt
+++ b/Documentation/s390/debugging390.rst
@@ -1,9 +1,12 @@
+=============================================
+Debugging on Linux for s/390 & z/Architecture
+=============================================
- Debugging on Linux for s/390 & z/Architecture
- by
- Denis Joseph Barrow ([email protected],[email protected])
- Copyright (C) 2000-2001 IBM Deutschland Entwicklung GmbH, IBM Corporation
- Best viewed with fixed width fonts
+Denis Joseph Barrow ([email protected],[email protected])
+
+Copyright (C) 2000-2001 IBM Deutschland Entwicklung GmbH, IBM Corporation
+
+.. Best viewed with fixed width fonts
Overview of Document:
=====================
@@ -17,32 +20,32 @@ It is intended like the Enterprise Systems Architecture/390 Reference Summary
to be printed out & used as a quick cheat sheet self help style reference when
problems occur.
-Contents
-========
-Register Set
-Address Spaces on Intel Linux
-Address Spaces on Linux for s/390 & z/Architecture
-The Linux for s/390 & z/Architecture Kernel Task Structure
-Register Usage & Stackframes on Linux for s/390 & z/Architecture
-A sample program with comments
-Compiling programs for debugging on Linux for s/390 & z/Architecture
-Debugging under VM
-s/390 & z/Architecture IO Overview
-Debugging IO on s/390 & z/Architecture under VM
-GDB on s/390 & z/Architecture
-Stack chaining in gdb by hand
-Examining core dumps
-ldd
-Debugging modules
-The proc file system
-SysRq
-References
-Special Thanks
+.. Contents
+ ========
+ Register Set
+ Address Spaces on Intel Linux
+ Address Spaces on Linux for s/390 & z/Architecture
+ The Linux for s/390 & z/Architecture Kernel Task Structure
+ Register Usage & Stackframes on Linux for s/390 & z/Architecture
+ A sample program with comments
+ Compiling programs for debugging on Linux for s/390 & z/Architecture
+ Debugging under VM
+ s/390 & z/Architecture IO Overview
+ Debugging IO on s/390 & z/Architecture under VM
+ GDB on s/390 & z/Architecture
+ Stack chaining in gdb by hand
+ Examining core dumps
+ ldd
+ Debugging modules
+ The proc file system
+ SysRq
+ References
+ Special Thanks
Register Set
============
The current architectures have the following registers.
-
+
16 General propose registers, 32 bit on s/390 and 64 bit on z/Architecture,
r0-r15 (or gpr0-gpr15), used for arithmetic and addressing.
@@ -59,20 +62,22 @@ Access register 0 (and access register 1 on z/Architecture, which needs a
64 bit pointer) is currently used by the pthread library as a pointer to
the current running threads private area.
-16 64 bit floating point registers (fp0-fp15 ) IEEE & HFP floating
-point format compliant on G5 upwards & a Floating point control reg (FPC)
-4 64 bit registers (fp0,fp2,fp4 & fp6) HFP only on older machines.
+16 64-bit floating point registers (fp0-fp15 ) IEEE & HFP floating
+point format compliant on G5 upwards & a Floating point control reg (FPC)
+
+4 64-bit registers (fp0,fp2,fp4 & fp6) HFP only on older machines.
+
Note:
-Linux (currently) always uses IEEE & emulates G5 IEEE format on older machines,
-( provided the kernel is configured for this ).
+ Linux (currently) always uses IEEE & emulates G5 IEEE format on older
+ machines, ( provided the kernel is configured for this ).
The PSW is the most important register on the machine it
-is 64 bit on s/390 & 128 bit on z/Architecture & serves the roles of
+is 64 bit on s/390 & 128 bit on z/Architecture & serves the roles of
a program counter (pc), condition code register,memory space designator.
In IBM standard notation I am counting bit 0 as the MSB.
It has several advantages over a normal program counter
-in that you can change address translation & program counter
+in that you can change address translation & program counter
in a single instruction. To change address translation,
e.g. switching address translation off requires that you
have a logical=physical mapping for the address you are
@@ -206,14 +211,18 @@ It exists between the real addresses 0-4096 on s/390 and between 0-8192 on
z/Architecture and is exchanged with one page on s/390 or two pages on
z/Architecture in absolute storage by the set prefix instruction during Linux
startup.
+
This page is mapped to a different prefix for each processor in an SMP
configuration (assuming the OS designer is sane of course).
+
Bytes 0-512 (200 hex) on s/390 and 0-512, 4096-4544, 4604-5119 currently on
z/Architecture are used by the processor itself for holding such information
as exception indications and entry points for exceptions.
+
Bytes after 0xc00 hex are used by linux for per processor globals on s/390 and
z/Architecture (there is a gap on z/Architecture currently between 0xc00 and
0x1000, too, which is used by Linux).
+
The closest thing to this on traditional architectures is the interrupt
vector table. This is a good thing & does simplify some of the kernel coding
however it means that we now cannot catch stray NULL pointers in the
@@ -225,27 +234,29 @@ Address Spaces on Intel Linux
=============================
The traditional Intel Linux is approximately mapped as follows forgive
-the ascii art.
-0xFFFFFFFF 4GB Himem *****************
- * *
- * Kernel Space *
- * *
- ***************** ****************
-User Space Himem * User Stack * * *
-(typically 0xC0000000 3GB ) ***************** * *
- * Shared Libs * * Next Process *
- ***************** * to *
- * * <== * Run * <==
- * User Program * * *
- * Data BSS * * *
- * Text * * *
- * Sections * * *
-0x00000000 ***************** ****************
+the ascii art::
+
+ 0xFFFFFFFF 4GB Himem *****************
+ * *
+ * Kernel Space *
+ * *
+ ***************** ****************
+ User Space Himem * User Stack * * *
+ (typically 0xC0000000 3GB ) ***************** * *
+ * Shared Libs * * Next Process *
+ ***************** * to *
+ * * <== * Run * <==
+ * User Program * * *
+ * Data BSS * * *
+ * Text * * *
+ * Sections * * *
+ 0x00000000 ***************** ****************
Now it is easy to see that on Intel it is quite easy to recognise a kernel
address as being one greater than user space himem (in this case 0xC0000000),
and addresses of less than this are the ones in the current running program on
this processor (if an smp box).
+
If using the virtual machine ( VM ) as a debugger it is quite difficult to
know which user process is running as the address space you are looking at
could be from any process in the run queue.
@@ -256,6 +267,7 @@ of Real Address=Virtual Address-User Space Himem.
This means that on Intel the kernel linux can typically only address
Himem=0xFFFFFFFF-0xC0000000=1GB & this is all the RAM these machines
can typically use.
+
They can lower User Himem to 2GB or lower & thus be
able to use 2GB of RAM however this shrinks the maximum size
of User Space from 3GB to 2GB they have a no win limit of 4GB unless
@@ -264,31 +276,31 @@ they go to 64 Bit.
On 390 our limitations & strengths make us slightly different.
For backward compatibility we are only allowed use 31 bits (2GB)
-of our 32 bit addresses, however, we use entirely separate address
+of our 32 bit addresses, however, we use entirely separate address
spaces for the user & kernel.
This means we can support 2GB of non Extended RAM on s/390, & more
-with the Extended memory management swap device &
+with the Extended memory management swap device &
currently 4TB of physical memory currently on z/Architecture.
Address Spaces on Linux for s/390 & z/Architecture
==================================================
-Our addressing scheme is basically as follows:
+Our addressing scheme is basically as follows::
- Primary Space Home Space
-Himem 0x7fffffff 2GB on s/390 ***************** ****************
-currently 0x3ffffffffff (2^42)-1 * User Stack * * *
-on z/Architecture. ***************** * *
- * Shared Libs * * *
- ***************** * *
- * * * Kernel *
- * User Program * * *
- * Data BSS * * *
- * Text * * *
- * Sections * * *
-0x00000000 ***************** ****************
+ Primary Space Home Space
+ Himem 0x7fffffff 2GB on s/390 ***************** ****************
+ currently 0x3ffffffffff (2^42)-1 * User Stack * * *
+ on z/Architecture. ***************** * *
+ * Shared Libs * * *
+ ***************** * *
+ * * * Kernel *
+ * User Program * * *
+ * Data BSS * * *
+ * Text * * *
+ * Sections * * *
+ 0x00000000 ***************** ****************
This also means that we need to look at the PSW problem state bit and the
addressing mode to decide whether we are looking at user or kernel space.
@@ -304,20 +316,25 @@ instruction on a user space address is performed.
When also looking at the ASCE control registers, this means:
User space:
+
- runs in primary or access register mode
- cr1 contains the user asce
- cr7 contains the user asce
- cr13 contains the kernel asce
Kernel space:
+
- runs in home space mode
- cr1 contains the user or kernel asce
- -> the kernel asce is loaded when a uaccess requires primary or
- secondary address mode
+
+ - the kernel asce is loaded when a uaccess requires primary or
+ secondary address mode
+
- cr7 contains the user or kernel asce, (changed with set_fs())
- cr13 contains the kernel asce
In case of uaccess the kernel changes to:
+
- primary space mode in case of a uaccess (copy_to_user) and uses
e.g. the mvcp instruction to access user space. However the kernel
will stay in home space mode if the mvcos instruction is available
@@ -337,41 +354,44 @@ Virtual Addresses on s/390 & z/Architecture
A virtual address on s/390 is made up of 3 parts
The SX (segment index, roughly corresponding to the PGD & PMD in Linux
terminology) being bits 1-11.
+
The PX (page index, corresponding to the page table entry (pte) in Linux
terminology) being bits 12-19.
+
The remaining bits BX (the byte index are the offset in the page )
i.e. bits 20 to 31.
On z/Architecture in linux we currently make up an address from 4 parts.
-The region index bits (RX) 0-32 we currently use bits 22-32
-The segment index (SX) being bits 33-43
-The page index (PX) being bits 44-51
-The byte index (BX) being bits 52-63
+
+- The region index bits (RX) 0-32 we currently use bits 22-32
+- The segment index (SX) being bits 33-43
+- The page index (PX) being bits 44-51
+- The byte index (BX) being bits 52-63
Notes:
-1) s/390 has no PMD so the PMD is really the PGD also.
-A lot of this stuff is defined in pgtable.h.
+ 1) s/390 has no PMD so the PMD is really the PGD also.
+ A lot of this stuff is defined in pgtable.h.
-2) Also seeing as s/390's page indexes are only 1k in size
-(bits 12-19 x 4 bytes per pte ) we use 1 ( page 4k )
-to make the best use of memory by updating 4 segment indices
-entries each time we mess with a PMD & use offsets
-0,1024,2048 & 3072 in this page as for our segment indexes.
-On z/Architecture our page indexes are now 2k in size
-( bits 12-19 x 8 bytes per pte ) we do a similar trick
-but only mess with 2 segment indices each time we mess with
-a PMD.
+ 2) Also seeing as s/390's page indexes are only 1k in size
+ (bits 12-19 x 4 bytes per pte ) we use 1 ( page 4k )
+ to make the best use of memory by updating 4 segment indices
+ entries each time we mess with a PMD & use offsets
+ 0,1024,2048 & 3072 in this page as for our segment indexes.
+ On z/Architecture our page indexes are now 2k in size
+ ( bits 12-19 x 8 bytes per pte ) we do a similar trick
+ but only mess with 2 segment indices each time we mess with
+ a PMD.
+
+ 3) As z/Architecture supports up to a massive 5-level page table lookup we
+ can only use 3 currently on Linux ( as this is all the generic kernel
+ currently supports ) however this may change in future
+ this allows us to access ( according to my sums )
+ 4TB of virtual storage per process i.e.
+ 4096*512(PTES)*1024(PMDS)*2048(PGD) = 4398046511104 bytes,
+ enough for another 2 or 3 of years I think :-).
+ to do this we use a region-third-table designation type in
+ our address space control registers.
-3) As z/Architecture supports up to a massive 5-level page table lookup we
-can only use 3 currently on Linux ( as this is all the generic kernel
-currently supports ) however this may change in future
-this allows us to access ( according to my sums )
-4TB of virtual storage per process i.e.
-4096*512(PTES)*1024(PMDS)*2048(PGD) = 4398046511104 bytes,
-enough for another 2 or 3 of years I think :-).
-to do this we use a region-third-table designation type in
-our address space control registers.
-
The Linux for s/390 & z/Architecture Kernel Task Structure
==========================================================
@@ -382,42 +402,43 @@ the __LC_KERNEL_STACK variable in the spare prefix area for this cpu
(which we use for per-processor globals).
The kernel stack pointer is intimately tied with the task structure for
-each processor as follows.
+each processor as follows::
- s/390
- ************************
- * 1 page kernel stack *
- * ( 4K ) *
- ************************
- * 1 page task_struct *
- * ( 4K ) *
-8K aligned ************************
+ s/390
+ ************************
+ * 1 page kernel stack *
+ * ( 4K ) *
+ ************************
+ * 1 page task_struct *
+ * ( 4K ) *
+ 8K aligned ************************
- z/Architecture
- ************************
- * 2 page kernel stack *
- * ( 8K ) *
- ************************
- * 2 page task_struct *
- * ( 8K ) *
-16K aligned ************************
+ z/Architecture
+ ************************
+ * 2 page kernel stack *
+ * ( 8K ) *
+ ************************
+ * 2 page task_struct *
+ * ( 8K ) *
+ 16K aligned ************************
What this means is that we don't need to dedicate any register or global
variable to point to the current running process & can retrieve it with the
-following very simple construct for s/390 & one very similar for z/Architecture.
+following very simple construct for s/390 & one very similar for
+z/Architecture::
-static inline struct task_struct * get_current(void)
-{
- struct task_struct *current;
- __asm__("lhi %0,-8192\n\t"
- "nr %0,15"
- : "=r" (current) );
- return current;
-}
+ static inline struct task_struct * get_current(void)
+ {
+ struct task_struct *current;
+ __asm__("lhi %0,-8192\n\t"
+ "nr %0,15"
+ : "=r" (current) );
+ return current;
+ }
i.e. just anding the current kernel stack pointer with the mask -8192.
Thankfully because Linux doesn't have support for nested IO interrupts
-& our devices have large buffers can survive interrupts being shut for
+& our devices have large buffers can survive interrupts being shut for
short amounts of time we don't need a separate stack for interrupts.
@@ -428,7 +449,7 @@ Register Usage & Stackframes on Linux for s/390 & z/Architecture
Overview:
---------
This is the code that gcc produces at the top & the bottom of
-each function. It usually is fairly consistent & similar from
+each function. It usually is fairly consistent & similar from
function to function & if you know its layout you can probably
make some headway in finding the ultimate cause of a problem
after a crash without a source level debugger.
@@ -443,87 +464,95 @@ didn't have to maintain compatibility with older linkage formats.
Glossary:
---------
alloca:
-This is a built in compiler function for runtime allocation
-of extra space on the callers stack which is obviously freed
-up on function exit ( e.g. the caller may choose to allocate nothing
-of a buffer of 4k if required for temporary purposes ), it generates
-very efficient code ( a few cycles ) when compared to alternatives
-like malloc.
+ This is a built in compiler function for runtime allocation
+ of extra space on the callers stack which is obviously freed
+ up on function exit ( e.g. the caller may choose to allocate nothing
+ of a buffer of 4k if required for temporary purposes ), it generates
+ very efficient code ( a few cycles ) when compared to alternatives
+ like malloc.
-automatics: These are local variables on the stack,
-i.e they aren't in registers & they aren't static.
+automatics:
+ These are local variables on the stack, i.e they aren't in registers &
+ they aren't static.
back-chain:
-This is a pointer to the stack pointer before entering a
-framed functions ( see frameless function ) prologue got by
-dereferencing the address of the current stack pointer,
- i.e. got by accessing the 32 bit value at the stack pointers
-current location.
+ This is a pointer to the stack pointer before entering a
+ framed functions ( see frameless function ) prologue got by
+ dereferencing the address of the current stack pointer,
+ i.e. got by accessing the 32 bit value at the stack pointers
+ current location.
base-pointer:
-This is a pointer to the back of the literal pool which
-is an area just behind each procedure used to store constants
-in each function.
+ This is a pointer to the back of the literal pool which
+ is an area just behind each procedure used to store constants
+ in each function.
-call-clobbered: The caller probably needs to save these registers if there
-is something of value in them, on the stack or elsewhere before making a
-call to another procedure so that it can restore it later.
+call-clobbered:
+ The caller probably needs to save these registers if there
+ is something of value in them, on the stack or elsewhere before making a
+ call to another procedure so that it can restore it later.
epilogue:
-The code generated by the compiler to return to the caller.
+ The code generated by the compiler to return to the caller.
-frameless-function
-A frameless function in Linux for s390 & z/Architecture is one which doesn't
-need more than the register save area (96 bytes on s/390, 160 on z/Architecture)
-given to it by the caller.
-A frameless function never:
-1) Sets up a back chain.
-2) Calls alloca.
-3) Calls other normal functions
-4) Has automatics.
+frameless-function:
+ A frameless function in Linux for s390 & z/Architecture is one which doesn't
+ need more than the register save area (96 bytes on s/390, 160 on z/Architecture)
+ given to it by the caller.
+
+ A frameless function never:
+
+ 1) Sets up a back chain.
+ 2) Calls alloca.
+ 3) Calls other normal functions
+ 4) Has automatics.
GOT-pointer:
-This is a pointer to the global-offset-table in ELF
-( Executable Linkable Format, Linux'es most common executable format ),
-all globals & shared library objects are found using this pointer.
+ This is a pointer to the global-offset-table in ELF
+ ( Executable Linkable Format, Linux'es most common executable format ),
+ all globals & shared library objects are found using this pointer.
lazy-binding
-ELF shared libraries are typically only loaded when routines in the shared
-library are actually first called at runtime. This is lazy binding.
+ ELF shared libraries are typically only loaded when routines in the shared
+ library are actually first called at runtime. This is lazy binding.
procedure-linkage-table
-This is a table found from the GOT which contains pointers to routines
-in other shared libraries which can't be called to by easier means.
+ This is a table found from the GOT which contains pointers to routines
+ in other shared libraries which can't be called to by easier means.
prologue:
-The code generated by the compiler to set up the stack frame.
+ The code generated by the compiler to set up the stack frame.
outgoing-args:
-This is extra area allocated on the stack of the calling function if the
-parameters for the callee's cannot all be put in registers, the same
-area can be reused by each function the caller calls.
+ This is extra area allocated on the stack of the calling function if the
+ parameters for the callee's cannot all be put in registers, the same
+ area can be reused by each function the caller calls.
routine-descriptor:
-A COFF executable format based concept of a procedure reference
-actually being 8 bytes or more as opposed to a simple pointer to the routine.
-This is typically defined as follows
-Routine Descriptor offset 0=Pointer to Function
-Routine Descriptor offset 4=Pointer to Table of Contents
-The table of contents/TOC is roughly equivalent to a GOT pointer.
-& it means that shared libraries etc. can be shared between several
-environments each with their own TOC.
+ A COFF executable format based concept of a procedure reference
+ actually being 8 bytes or more as opposed to a simple pointer to the routine.
+ This is typically defined as follows:
-
-static-chain: This is used in nested functions a concept adopted from pascal
-by gcc not used in ansi C or C++ ( although quite useful ), basically it
-is a pointer used to reference local variables of enclosing functions.
-You might come across this stuff once or twice in your lifetime.
+ - Routine Descriptor offset 0=Pointer to Function
+ - Routine Descriptor offset 4=Pointer to Table of Contents
-e.g.
-The function below should return 11 though gcc may get upset & toss warnings
-about unused variables.
-int FunctionA(int a)
-{
+ The table of contents/TOC is roughly equivalent to a GOT pointer.
+ & it means that shared libraries etc. can be shared between several
+ environments each with their own TOC.
+
+static-chain:
+ This is used in nested functions a concept adopted from pascal
+ by gcc not used in ansi C or C++ ( although quite useful ), basically it
+ is a pointer used to reference local variables of enclosing functions.
+ You might come across this stuff once or twice in your lifetime.
+
+ e.g.
+
+ The function below should return 11 though gcc may get upset & toss warnings
+ about unused variables::
+
+ int FunctionA(int a)
+ {
int b;
FunctionC(int c)
{
@@ -531,19 +560,21 @@ int FunctionA(int a)
}
FunctionC(10);
return(b);
-}
+ }
s/390 & z/Architecture Register usage
=====================================
+
+======== ========================================== ===============
r0 used by syscalls/assembly call-clobbered
-r1 used by syscalls/assembly call-clobbered
+r1 used by syscalls/assembly call-clobbered
r2 argument 0 / return value 0 call-clobbered
r3 argument 1 / return value 1 (if long long) call-clobbered
r4 argument 2 call-clobbered
r5 argument 3 call-clobbered
-r6 argument 4 saved
-r7 pointer-to arguments 5 to ... saved
+r6 argument 4 saved
+r7 pointer-to arguments 5 to ... saved
r8 this & that saved
r9 this & that saved
r10 static-chain ( if nested function ) saved
@@ -557,65 +588,74 @@ f0 argument 0 / return value ( float/double ) call-clobbered
f2 argument 1 call-clobbered
f4 z/Architecture argument 2 saved
f6 z/Architecture argument 3 saved
+======== ========================================== ===============
+
The remaining floating points
f1,f3,f5 f7-f15 are call-clobbered.
Notes:
------
1) The only requirement is that registers which are used
-by the callee are saved, e.g. the compiler is perfectly
-capable of using r11 for purposes other than a frame a
-frame pointer if a frame pointer is not needed.
-2) In functions with variable arguments e.g. printf the calling procedure
-is identical to one without variable arguments & the same number of
-parameters. However, the prologue of this function is somewhat more
-hairy owing to it having to move these parameters to the stack to
-get va_start, va_arg & va_end to work.
+ by the callee are saved, e.g. the compiler is perfectly
+ capable of using r11 for purposes other than a frame a
+ frame pointer if a frame pointer is not needed.
+2) In functions with variable arguments e.g. printf the calling procedure
+ is identical to one without variable arguments & the same number of
+ parameters. However, the prologue of this function is somewhat more
+ hairy owing to it having to move these parameters to the stack to
+ get va_start, va_arg & va_end to work.
3) Access registers are currently unused by gcc but are used in
-the kernel. Possibilities exist to use them at the moment for
-temporary storage but it isn't recommended.
+ the kernel. Possibilities exist to use them at the moment for
+ temporary storage but it isn't recommended.
4) Only 4 of the floating point registers are used for
-parameter passing as older machines such as G3 only have only 4
-& it keeps the stack frame compatible with other compilers.
-However with IEEE floating point emulation under linux on the
-older machines you are free to use the other 12.
-5) A long long or double parameter cannot be have the
-first 4 bytes in a register & the second four bytes in the
-outgoing args area. It must be purely in the outgoing args
-area if crossing this boundary.
+ parameter passing as older machines such as G3 only have only 4
+ & it keeps the stack frame compatible with other compilers.
+ However with IEEE floating point emulation under linux on the
+ older machines you are free to use the other 12.
+5) A long long or double parameter cannot be have the
+ first 4 bytes in a register & the second four bytes in the
+ outgoing args area. It must be purely in the outgoing args
+ area if crossing this boundary.
6) Floating point parameters are mixed with outgoing args
-on the outgoing args area in the order the are passed in as parameters.
-7) Floating point arguments 2 & 3 are saved in the outgoing args area for
-z/Architecture
+ on the outgoing args area in the order the are passed in as parameters.
+7) Floating point arguments 2 & 3 are saved in the outgoing args area for
+ z/Architecture
Stack Frame Layout
------------------
+
+========= ============== ======================================================
s/390 z/Architecture
-0 0 back chain ( a 0 here signifies end of back chain )
-4 8 eos ( end of stack, not used on Linux for S390 used in other linkage formats )
-8 16 glue used in other s/390 linkage formats for saved routine descriptors etc.
-12 24 glue used in other s/390 linkage formats for saved routine descriptors etc.
-16 32 scratch area
-20 40 scratch area
-24 48 saved r6 of caller function
-28 56 saved r7 of caller function
-32 64 saved r8 of caller function
-36 72 saved r9 of caller function
-40 80 saved r10 of caller function
-44 88 saved r11 of caller function
-48 96 saved r12 of caller function
-52 104 saved r13 of caller function
-56 112 saved r14 of caller function
-60 120 saved r15 of caller function
-64 128 saved f4 of caller function
-72 132 saved f6 of caller function
-80 undefined
-96 160 outgoing args passed from caller to callee
-96+x 160+x possible stack alignment ( 8 bytes desirable )
-96+x+y 160+x+y alloca space of caller ( if used )
-96+x+y+z 160+x+y+z automatics of caller ( if used )
-0 back-chain
+========= ============== ======================================================
+0 0 back chain ( a 0 here signifies end of back chain )
+4 8 eos ( end of stack, not used on Linux for S390 used
+ in other linkage formats )
+8 16 glue used in other s/390 linkage formats for saved
+ routine descriptors etc.
+12 24 glue used in other s/390 linkage formats for saved
+ routine descriptors etc.
+16 32 scratch area
+20 40 scratch area
+24 48 saved r6 of caller function
+28 56 saved r7 of caller function
+32 64 saved r8 of caller function
+36 72 saved r9 of caller function
+40 80 saved r10 of caller function
+44 88 saved r11 of caller function
+48 96 saved r12 of caller function
+52 104 saved r13 of caller function
+56 112 saved r14 of caller function
+60 120 saved r15 of caller function
+64 128 saved f4 of caller function
+72 132 saved f6 of caller function
+80 undefined
+96 160 outgoing args passed from caller to callee
+96+x 160+x possible stack alignment ( 8 bytes desirable )
+96+x+y 160+x+y alloca space of caller ( if used )
+96+x+y+z 160+x+y+z automatics of caller ( if used )
+0 back-chain
+========= ============== ======================================================
A sample program with comments.
===============================
@@ -623,82 +663,86 @@ A sample program with comments.
Comments on the function test
-----------------------------
1) It didn't need to set up a pointer to the constant pool gpr13 as it is not
-used ( :-( ).
+ used ( :-( ).
2) This is a frameless function & no stack is bought.
3) The compiler was clever enough to recognise that it could return the
-value in r2 as well as use it for the passed in parameter ( :-) ).
-4) The basr ( branch relative & save ) trick works as follows the instruction
-has a special case with r0,r0 with some instruction operands is understood as
-the literal value 0, some risc architectures also do this ). So now
-we are branching to the next address & the address new program counter is
-in r13,so now we subtract the size of the function prologue we have executed
-+ the size of the literal pool to get to the top of the literal pool
-0040037c int test(int b)
-{ # Function prologue below
- 40037c: 90 de f0 34 stm %r13,%r14,52(%r15) # Save registers r13 & r14
- 400380: 0d d0 basr %r13,%r0 # Set up pointer to constant pool using
- 400382: a7 da ff fa ahi %r13,-6 # basr trick
+ value in r2 as well as use it for the passed in parameter ( :-) ).
+4) The basr ( branch relative & save ) trick works as follows the instruction
+ has a special case with r0,r0 with some instruction operands is understood as
+ the literal value 0, some risc architectures also do this ). So now
+ we are branching to the next address & the address new program counter is
+ in r13,so now we subtract the size of the function prologue we have executed
+ the size of the literal pool to get to the top of the literal pool::
+
+
+ 0040037c int test(int b)
+ { # Function prologue below
+ 40037c: 90 de f0 34 stm %r13,%r14,52(%r15) # Save registers r13 & r14
+ 400380: 0d d0 basr %r13,%r0 # Set up pointer to constant pool using
+ 400382: a7 da ff fa ahi %r13,-6 # basr trick
return(5+b);
- # Huge main program
- 400386: a7 2a 00 05 ahi %r2,5 # add 5 to r2
+ # Huge main program
+ 400386: a7 2a 00 05 ahi %r2,5 # add 5 to r2
- # Function epilogue below
- 40038a: 98 de f0 34 lm %r13,%r14,52(%r15) # restore registers r13 & 14
- 40038e: 07 fe br %r14 # return
-}
+ # Function epilogue below
+ 40038a: 98 de f0 34 lm %r13,%r14,52(%r15) # restore registers r13 & 14
+ 40038e: 07 fe br %r14 # return
+ }
Comments on the function main
-----------------------------
-1) The compiler did this function optimally ( 8-) )
+1) The compiler did this function optimally ( 8-) )::
-Literal pool for main.
-400390: ff ff ff ec .long 0xffffffec
-main(int argc,char *argv[])
-{ # Function prologue below
- 400394: 90 bf f0 2c stm %r11,%r15,44(%r15) # Save necessary registers
- 400398: 18 0f lr %r0,%r15 # copy stack pointer to r0
- 40039a: a7 fa ff a0 ahi %r15,-96 # Make area for callee saving
- 40039e: 0d d0 basr %r13,%r0 # Set up r13 to point to
- 4003a0: a7 da ff f0 ahi %r13,-16 # literal pool
- 4003a4: 50 00 f0 00 st %r0,0(%r15) # Save backchain
+ Literal pool for main.
+ 400390: ff ff ff ec .long 0xffffffec
+ main(int argc,char *argv[])
+ { # Function prologue below
+ 400394: 90 bf f0 2c stm %r11,%r15,44(%r15) # Save necessary registers
+ 400398: 18 0f lr %r0,%r15 # copy stack pointer to r0
+ 40039a: a7 fa ff a0 ahi %r15,-96 # Make area for callee saving
+ 40039e: 0d d0 basr %r13,%r0 # Set up r13 to point to
+ 4003a0: a7 da ff f0 ahi %r13,-16 # literal pool
+ 4003a4: 50 00 f0 00 st %r0,0(%r15) # Save backchain
return(test(5)); # Main Program Below
- 4003a8: 58 e0 d0 00 l %r14,0(%r13) # load relative address of test from
- # literal pool
- 4003ac: a7 28 00 05 lhi %r2,5 # Set first parameter to 5
- 4003b0: 4d ee d0 00 bas %r14,0(%r14,%r13) # jump to test setting r14 as return
+ 4003a8: 58 e0 d0 00 l %r14,0(%r13) # load relative address of test from
+ # literal pool
+ 4003ac: a7 28 00 05 lhi %r2,5 # Set first parameter to 5
+ 4003b0: 4d ee d0 00 bas %r14,0(%r14,%r13) # jump to test setting r14 as return
# address using branch & save instruction.
# Function Epilogue below
- 4003b4: 98 bf f0 8c lm %r11,%r15,140(%r15)# Restore necessary registers.
- 4003b8: 07 fe br %r14 # return to do program exit
-}
+ 4003b4: 98 bf f0 8c lm %r11,%r15,140(%r15)# Restore necessary registers.
+ 4003b8: 07 fe br %r14 # return to do program exit
+ }
Compiler updates
----------------
-main(int argc,char *argv[])
-{
- 4004fc: 90 7f f0 1c stm %r7,%r15,28(%r15)
- 400500: a7 d5 00 04 bras %r13,400508 <main+0xc>
- 400504: 00 40 04 f4 .long 0x004004f4
- # compiler now puts constant pool in code to so it saves an instruction
- 400508: 18 0f lr %r0,%r15
- 40050a: a7 fa ff a0 ahi %r15,-96
- 40050e: 50 00 f0 00 st %r0,0(%r15)
+::
+
+ main(int argc,char *argv[])
+ {
+ 4004fc: 90 7f f0 1c stm %r7,%r15,28(%r15)
+ 400500: a7 d5 00 04 bras %r13,400508 <main+0xc>
+ 400504: 00 40 04 f4 .long 0x004004f4
+ # compiler now puts constant pool in code to so it saves an instruction
+ 400508: 18 0f lr %r0,%r15
+ 40050a: a7 fa ff a0 ahi %r15,-96
+ 40050e: 50 00 f0 00 st %r0,0(%r15)
return(test(5));
- 400512: 58 10 d0 00 l %r1,0(%r13)
- 400516: a7 28 00 05 lhi %r2,5
- 40051a: 0d e1 basr %r14,%r1
- # compiler adds 1 extra instruction to epilogue this is done to
- # avoid processor pipeline stalls owing to data dependencies on g5 &
- # above as register 14 in the old code was needed directly after being loaded
- # by the lm %r11,%r15,140(%r15) for the br %14.
- 40051c: 58 40 f0 98 l %r4,152(%r15)
- 400520: 98 7f f0 7c lm %r7,%r15,124(%r15)
- 400524: 07 f4 br %r4
-}
+ 400512: 58 10 d0 00 l %r1,0(%r13)
+ 400516: a7 28 00 05 lhi %r2,5
+ 40051a: 0d e1 basr %r14,%r1
+ # compiler adds 1 extra instruction to epilogue this is done to
+ # avoid processor pipeline stalls owing to data dependencies on g5 &
+ # above as register 14 in the old code was needed directly after being loaded
+ # by the lm %r11,%r15,140(%r15) for the br %14.
+ 40051c: 58 40 f0 98 l %r4,152(%r15)
+ 400520: 98 7f f0 7c lm %r7,%r15,124(%r15)
+ 400524: 07 f4 br %r4
+ }
Hartmut ( our compiler developer ) also has been threatening to take out the
@@ -709,38 +753,39 @@ have been warned.
--------------------------------------
If you understand the stuff above you'll understand the stuff
-below too so I'll avoid repeating myself & just say that
+below too so I'll avoid repeating myself & just say that
some of the instructions have g's on the end of them to indicate
-they are 64 bit & the stack offsets are a bigger,
+they are 64 bit & the stack offsets are a bigger,
the only other difference you'll find between 32 & 64 bit is that
-we now use f4 & f6 for floating point arguments on 64 bit.
-00000000800005b0 <test>:
-int test(int b)
-{
+we now use f4 & f6 for floating point arguments on 64 bit::
+
+ 00000000800005b0 <test>:
+ int test(int b)
+ {
return(5+b);
- 800005b0: a7 2a 00 05 ahi %r2,5
- 800005b4: b9 14 00 22 lgfr %r2,%r2 # downcast to integer
- 800005b8: 07 fe br %r14
- 800005ba: 07 07 bcr 0,%r7
+ 800005b0: a7 2a 00 05 ahi %r2,5
+ 800005b4: b9 14 00 22 lgfr %r2,%r2 # downcast to integer
+ 800005b8: 07 fe br %r14
+ 800005ba: 07 07 bcr 0,%r7
-}
+ }
-00000000800005bc <main>:
-main(int argc,char *argv[])
-{
- 800005bc: eb bf f0 58 00 24 stmg %r11,%r15,88(%r15)
- 800005c2: b9 04 00 1f lgr %r1,%r15
- 800005c6: a7 fb ff 60 aghi %r15,-160
- 800005ca: e3 10 f0 00 00 24 stg %r1,0(%r15)
+ 00000000800005bc <main>:
+ main(int argc,char *argv[])
+ {
+ 800005bc: eb bf f0 58 00 24 stmg %r11,%r15,88(%r15)
+ 800005c2: b9 04 00 1f lgr %r1,%r15
+ 800005c6: a7 fb ff 60 aghi %r15,-160
+ 800005ca: e3 10 f0 00 00 24 stg %r1,0(%r15)
return(test(5));
- 800005d0: a7 29 00 05 lghi %r2,5
- # brasl allows jumps > 64k & is overkill here bras would do fune
- 800005d4: c0 e5 ff ff ff ee brasl %r14,800005b0 <test>
- 800005da: e3 40 f1 10 00 04 lg %r4,272(%r15)
- 800005e0: eb bf f0 f8 00 04 lmg %r11,%r15,248(%r15)
- 800005e6: 07 f4 br %r4
-}
+ 800005d0: a7 29 00 05 lghi %r2,5
+ # brasl allows jumps > 64k & is overkill here bras would do fune
+ 800005d4: c0 e5 ff ff ff ee brasl %r14,800005b0 <test>
+ 800005da: e3 40 f1 10 00 04 lg %r4,272(%r15)
+ 800005e0: eb bf f0 f8 00 04 lmg %r11,%r15,248(%r15)
+ 800005e6: 07 f4 br %r4
+ }
@@ -749,15 +794,15 @@ Compiling programs for debugging on Linux for s/390 & z/Architecture
-gdwarf-2 now works it should be considered the default debugging
format for s/390 & z/Architecture as it is more reliable for debugging
shared libraries, normal -g debugging works much better now
-Thanks to the IBM java compiler developers bug reports.
+Thanks to the IBM java compiler developers bug reports.
-This is typically done adding/appending the flags -g or -gdwarf-2 to the
+This is typically done adding/appending the flags -g or -gdwarf-2 to the
CFLAGS & LDFLAGS variables Makefile of the program concerned.
If using gdb & you would like accurate displays of registers &
- stack traces compile without optimisation i.e make sure
+stack traces compile without optimisation i.e make sure
that there is no -O2 or similar on the CFLAGS line of the Makefile &
-the emitted gcc commands, obviously this will produce worse code
+the emitted gcc commands, obviously this will produce worse code
( not advisable for shipment ) but it is an aid to the debugging process.
This aids debugging because the compiler will copy parameters passed in
@@ -766,7 +811,7 @@ parameters will work, however some larger programs which use inline functions
will not compile without optimisation.
Debugging with optimisation has since much improved after fixing
-some bugs, please make sure you are using gdb-5.0 or later developed
+some bugs, please make sure you are using gdb-5.0 or later developed
after Nov'2000.
@@ -779,7 +824,7 @@ Notes
Addresses & values in the VM debugger are always hex never decimal
Address ranges are of the format <HexValue1>-<HexValue2> or
<HexValue1>.<HexValue2>
-For example, the address range 0x2000 to 0x3000 can be described as 2000-3000
+For example, the address range 0x2000 to 0x3000 can be described as 2000-3000
or 2000.1000
The VM Debugger is case insensitive.
@@ -798,27 +843,31 @@ operands are nibble (half byte aligned).
So if you have an objdump listing by hand, it is quite easy to follow, and if
you don't have an objdump listing keep a copy of the s/390 Reference Summary
or alternatively the s/390 principles of operation next to you.
-e.g. even I can guess that
+e.g. even I can guess that
0001AFF8' LR 180F CC 0
-is a ( load register ) lr r0,r15
+is a ( load register ) lr r0,r15
Also it is very easy to tell the length of a 390 instruction from the 2 most
significant bits in the instruction (not that this info is really useful except
if you are trying to make sense of a hexdump of code).
Here is a table
+
+======================= ==================
Bits Instruction Length
-------------------------------------------
+======================= ==================
00 2 Bytes
01 4 Bytes
10 4 Bytes
11 6 Bytes
+======================= ==================
The debugger also displays other useful info on the same line such as the
addresses being operated on destination addresses of branches & condition codes.
-e.g.
-00019736' AHI A7DAFF0E CC 1
-000198BA' BRC A7840004 -> 000198C2' CC 0
-000198CE' STM 900EF068 >> 0FA95E78 CC 2
+e.g.::
+
+ 00019736' AHI A7DAFF0E CC 1
+ 000198BA' BRC A7840004 -> 000198C2' CC 0
+ 000198CE' STM 900EF068 >> 0FA95E78 CC 2
@@ -826,54 +875,79 @@ Useful VM debugger commands
---------------------------
I suppose I'd better mention this before I start
-to list the current active traces do
-Q TR
+to list the current active traces do::
+
+ Q TR
+
there can be a maximum of 255 of these per set
( more about trace sets later ).
-To stop traces issue a
-TR END.
-To delete a particular breakpoint issue
-TR DEL <breakpoint number>
+
+To stop traces issue a::
+
+ TR END.
+
+To delete a particular breakpoint issue::
+
+ TR DEL <breakpoint number>
The PA1 key drops to CP mode so you can issue debugger commands,
-Doing alt c (on my 3270 console at least ) clears the screen.
+Doing alt c (on my 3270 console at least ) clears the screen.
+
hitting b <enter> comes back to the running operating system
from cp mode ( in our case linux ).
+
It is typically useful to add shortcuts to your profile.exec file
if you have one ( this is roughly equivalent to autoexec.bat in DOS ).
-file here are a few from mine.
-/* this gives me command history on issuing f12 */
-set pf12 retrieve
-/* this continues */
-set pf8 imm b
-/* goes to trace set a */
-set pf1 imm tr goto a
-/* goes to trace set b */
-set pf2 imm tr goto b
-/* goes to trace set c */
-set pf3 imm tr goto c
+file here are a few from mine::
+
+ /* this gives me command history on issuing f12 */
+ set pf12 retrieve
+ /* this continues */
+ set pf8 imm b
+ /* goes to trace set a */
+ set pf1 imm tr goto a
+ /* goes to trace set b */
+ set pf2 imm tr goto b
+ /* goes to trace set c */
+ set pf3 imm tr goto c
Instruction Tracing
-------------------
-Setting a simple breakpoint
-TR I PSWA <address>
-To debug a particular function try
-TR I R <function address range>
-TR I on its own will single step.
-TR I DATA <MNEMONIC> <OPTIONAL RANGE> will trace for particular mnemonics
-e.g.
-TR I DATA 4D R 0197BC.4000
+Setting a simple breakpoint::
+
+ TR I PSWA <address>
+
+To debug a particular function try::
+
+ TR I R <function address range>
+ TR I on its own will single step.
+ TR I DATA <MNEMONIC> <OPTIONAL RANGE> will trace for particular mnemonics
+
+e.g.::
+
+ TR I DATA 4D R 0197BC.4000
+
will trace for BAS'es ( opcode 4D ) in the range 0197BC.4000
+
if you were inclined you could add traces for all branch instructions &
-suffix them with the run prefix so you would have a backtrace on screen
-when a program crashes.
-TR BR <INTO OR FROM> will trace branches into or out of an address.
-e.g.
-TR BR INTO 0 is often quite useful if a program is getting awkward & deciding
+suffix them with the run prefix so you would have a backtrace on screen
+when a program crashes::
+
+ TR BR <INTO OR FROM> will trace branches into or out of an address.
+
+e.g.::
+
+ TR BR INTO 0
+
+is often quite useful if a program is getting awkward & deciding
to branch to 0 & crashing as this will stop at the address before in jumps to 0.
-TR I R <address range> RUN cmd d g
+
+::
+
+ TR I R <address range> RUN cmd d g
+
single steps a range of addresses but stays running &
displays the gprs on each step.
@@ -881,93 +955,129 @@ displays the gprs on each step.
Displaying & modifying Registers
--------------------------------
-D G will display all the gprs
-Adding a extra G to all the commands is necessary to access the full 64 bit
+D G
+ will display all the gprs
+
+Adding a extra G to all the commands is necessary to access the full 64 bit
content in VM on z/Architecture. Obviously this isn't required for access
registers as these are still 32 bit.
-e.g. DGG instead of DG
-D X will display all the control registers
-D AR will display all the access registers
-D AR4-7 will display access registers 4 to 7
-CPU ALL D G will display the GRPS of all CPUS in the configuration
-D PSW will display the current PSW
-st PSW 2000 will put the value 2000 into the PSW &
-cause crash your machine.
-D PREFIX displays the prefix offset
+
+e.g.
+
+DGG
+ instead of DG
+
+D X
+ will display all the control registers
+D AR
+ will display all the access registers
+D AR4-7
+ will display access registers 4 to 7
+CPU ALL D G
+ will display the GRPS of all CPUS in the configuration
+D PSW
+ will display the current PSW
+st PSW 2000
+ will put the value 2000 into the PSW & cause crash your machine.
+D PREFIX
+ displays the prefix offset
Displaying Memory
-----------------
-To display memory mapped using the current PSW's mapping try
-D <range>
+To display memory mapped using the current PSW's mapping try::
+
+ D <range>
+
To make VM display a message each time it hits a particular address and
-continue try
-D I<range> will disassemble/display a range of instructions.
-ST addr 32 bit word will store a 32 bit aligned address
-D T<range> will display the EBCDIC in an address (if you are that way inclined)
-D R<range> will display real addresses ( without DAT ) but with prefixing.
+continue try:
+
+D I<range>
+ will disassemble/display a range of instructions.
+
+ST addr 32 bit word
+ will store a 32 bit aligned address
+D T<range>
+ will display the EBCDIC in an address (if you are that way inclined)
+D R<range>
+ will display real addresses ( without DAT ) but with prefixing.
+
There are other complex options to display if you need to get at say home space
but are in primary space the easiest thing to do is to temporarily
modify the PSW to the other addressing mode, display the stuff & then
restore it.
-
+
Hints
-----
If you want to issue a debugger command without halting your virtual machine
-with the PA1 key try prefixing the command with #CP e.g.
-#cp tr i pswa 2000
+with the PA1 key try prefixing the command with #CP e.g.::
+
+ #cp tr i pswa 2000
+
also suffixing most debugger commands with RUN will cause them not
to stop just display the mnemonic at the current instruction on the console.
+
If you have several breakpoints you want to put into your program &
you get fed up of cross referencing with System.map
you can do the following trick for several symbols.
-grep do_signal System.map
-which emits the following among other things
-0001f4e0 T do_signal
-now you can do
-TR I PSWA 0001f4e0 cmd msg * do_signal
+::
+
+ grep do_signal System.map
+
+which emits the following among other things::
+
+ 0001f4e0 T do_signal
+
+now you can do::
+
+ TR I PSWA 0001f4e0 cmd msg * do_signal
+
This sends a message to your own console each time do_signal is entered.
( As an aside I wrote a perl script once which automatically generated a REXX
script with breakpoints on every kernel procedure, this isn't a good idea
because there are thousands of these routines & VM can only set 255 breakpoints
-at a time so you nearly had to spend as long pruning the file down as you would
+at a time so you nearly had to spend as long pruning the file down as you would
entering the msgs by hand), however, the trick might be useful for a single
object file. In the 3270 terminal emulator x3270 there is a very useful option
in the file menu called "Save Screen In File" - this is very good for keeping a
copy of traces.
-From CMS help <command name> will give you online help on a particular command.
-e.g.
-HELP DISPLAY
+From CMS help <command name> will give you online help on a particular command.
+e.g.::
+
+ HELP DISPLAY
Also CP has a file called profile.exec which automatically gets called
on startup of CMS ( like autoexec.bat ), keeping on a DOS analogy session
CP has a feature similar to doskey, it may be useful for you to
-use profile.exec to define some keystrokes.
-e.g.
+use profile.exec to define some keystrokes.
+
SET PF9 IMM B
-This does a single step in VM on pressing F8.
+ This does a single step in VM on pressing F8.
+
SET PF10 ^
-This sets up the ^ key.
-which can be used for ^c (ctrl-c),^z (ctrl-z) which can't be typed directly
-into some 3270 consoles.
+ This sets up the ^ key.
+ which can be used for ^c (ctrl-c),^z (ctrl-z) which can't be typed
+ directly into some 3270 consoles.
+
SET PF11 ^-
-This types the starting keystrokes for a sysrq see SysRq below.
+ This types the starting keystrokes for a sysrq see SysRq below.
SET PF12 RETRIEVE
-This retrieves command history on pressing F12.
+ This retrieves command history on pressing F12.
Sometimes in VM the display is set up to scroll automatically this
can be very annoying if there are messages you wish to look at
to stop this do
+
TERM MORE 255 255
-This will nearly stop automatic screen updates, however it will
-cause a denial of service if lots of messages go to the 3270 console,
-so it would be foolish to use this as the default on a production machine.
-
+ This will nearly stop automatic screen updates, however it will
+ cause a denial of service if lots of messages go to the 3270 console,
+ so it would be foolish to use this as the default on a production machine.
+
Tracing particular processes
----------------------------
@@ -976,69 +1086,116 @@ very seldom collide with text segments of user programs ( thanks Martin ),
this simplifies debugging the kernel.
However it is quite common for user processes to have addresses which collide
this can make debugging a particular process under VM painful under normal
-circumstances as the process may change when doing a
-TR I R <address range>.
+circumstances as the process may change when doing a::
+
+ TR I R <address range>.
+
Thankfully after reading VM's online help I figured out how to debug
I particular process.
Your first problem is to find the STD ( segment table designation )
of the program you wish to debug.
There are several ways you can do this here are a few
-1) objdump --syms <program to be debugged> | grep main
-To get the address of main in the program.
-tr i pswa <address of main>
+
+Run::
+
+ objdump --syms <program to be debugged> | grep main
+
+To get the address of main in the program. Then::
+
+ tr i pswa <address of main>
+
Start the program, if VM drops to CP on what looks like the entry
point of the main function this is most likely the process you wish to debug.
Now do a D X13 or D XG13 on z/Architecture.
-On 31 bit the STD is bits 1-19 ( the STO segment table origin )
+
+On 31 bit the STD is bits 1-19 ( the STO segment table origin )
& 25-31 ( the STL segment table length ) of CR13.
-now type
-TR I R STD <CR13's value> 0.7fffffff
-e.g.
-TR I R STD 8F32E1FF 0.7fffffff
-Another very useful variation is
-TR STORE INTO STD <CR13's value> <address range>
+
+now type::
+
+ TR I R STD <CR13's value> 0.7fffffff
+
+e.g.::
+
+ TR I R STD 8F32E1FF 0.7fffffff
+
+Another very useful variation is::
+
+ TR STORE INTO STD <CR13's value> <address range>
+
for finding out when a particular variable changes.
-An alternative way of finding the STD of a currently running process
+An alternative way of finding the STD of a currently running process
is to do the following, ( this method is more complex but
could be quite convenient if you aren't updating the kernel much &
so your kernel structures will stay constant for a reasonable period of
time ).
-grep task /proc/<pid>/status
-from this you should see something like
-task: 0f160000 ksp: 0f161de8 pt_regs: 0f161f68
+::
+
+ grep task /proc/<pid>/status
+
+from this you should see something like::
+
+ task: 0f160000 ksp: 0f161de8 pt_regs: 0f161f68
+
This now gives you a pointer to the task structure.
-Now make CC:="s390-gcc -g" kernel/sched.s
+
+Now make::
+
+ CC:="s390-gcc -g" kernel/sched.s
+
To get the task_struct stabinfo.
+
( task_struct is defined in include/linux/sched.h ).
+
Now we want to look at
task->active_mm->pgd
+
on my machine the active_mm in the task structure stab is
active_mm:(4,12),672,32
+
its offset is 672/8=84=0x54
+
the pgd member in the mm_struct stab is
pgd:(4,6)=*(29,5),96,32
so its offset is 96/8=12=0xc
-so we'll
-hexdump -s 0xf160054 /dev/mem | more
+so we'll::
+
+ hexdump -s 0xf160054 /dev/mem | more
+
i.e. task_struct+active_mm offset
-to look at the active_mm member
-f160054 0fee cc60 0019 e334 0000 0000 0000 0011
-hexdump -s 0x0feecc6c /dev/mem | more
-i.e. active_mm+pgd offset
-feecc6c 0f2c 0000 0000 0001 0000 0001 0000 0010
+to look at the active_mm member::
+
+ f160054 0fee cc60 0019 e334 0000 0000 0000 0011
+
+::
+
+ hexdump -s 0x0feecc6c /dev/mem | more
+
+i.e. active_mm+pgd offset::
+
+ feecc6c 0f2c 0000 0000 0001 0000 0001 0000 0010
+
we get something like
-now do
-TR I R STD <pgd|0x7f> 0.7fffffff
+now do::
+
+ TR I R STD <pgd|0x7f> 0.7fffffff
+
i.e. the 0x7f is added because the pgd only
gives the page table origin & we need to set the low bits
to the maximum possible segment table length.
-TR I R STD 0f2c007f 0.7fffffff
-on z/Architecture you'll probably need to do
-TR I R STD <pgd|0x7> 0.ffffffffffffffff
+
+::
+
+ TR I R STD 0f2c007f 0.7fffffff
+
+on z/Architecture you'll probably need to do::
+
+ TR I R STD <pgd|0x7> 0.ffffffffffffffff
+
to set the TableType to 0x1 & the Table length to 3.
@@ -1051,40 +1208,51 @@ You can restart linux & trace these using the tr prog <range or value> trace
option.
-The most common ones you will normally be tracing for is
-1=operation exception
-2=privileged operation exception
-4=protection exception
-5=addressing exception
-6=specification exception
-10=segment translation exception
-11=page translation exception
+The most common ones you will normally be tracing for is:
+
+- 1=operation exception
+- 2=privileged operation exception
+- 4=protection exception
+- 5=addressing exception
+- 6=specification exception
+- 10=segment translation exception
+- 11=page translation exception
The full list of these is on page 22 of the current s/390 Reference Summary.
e.g.
+
tr prog 10 will trace segment translation exceptions.
+
tr prog on its own will trace all program interruption codes.
Trace Sets
----------
On starting VM you are initially in the INITIAL trace set.
You can do a Q TR to verify this.
-If you have a complex tracing situation where you wish to wait for instance
+If you have a complex tracing situation where you wish to wait for instance
till a driver is open before you start tracing IO, but know in your
heart that you are going to have to make several runs through the code till you
-have a clue whats going on.
+have a clue whats going on.
+
+What you can do is::
+
+ TR I PSWA <Driver open address>
-What you can do is
-TR I PSWA <Driver open address>
hit b to continue till breakpoint
+
reach the breakpoint
-now do your
-TR GOTO B
-TR IO 7c08-7c09 inst int run
+
+now do your::
+
+ TR GOTO B
+ TR IO 7c08-7c09 inst int run
+
or whatever the IO channels you wish to trace are & hit b
-To got back to the initial trace set do
-TR GOTO INITIAL
+To got back to the initial trace set do::
+
+ TR GOTO INITIAL
+
& the TR I PSWA <Driver open address> will be the only active breakpoint again.
@@ -1093,11 +1261,14 @@ Tracing linux syscalls under VM
Syscalls are implemented on Linux for S390 by the Supervisor call instruction
(SVC). There 256 possibilities of these as the instruction is made up of a 0xA
opcode and the second byte being the syscall number. They are traced using the
-simple command:
-TR SVC <Optional value or range>
+simple command::
+
+ TR SVC <Optional value or range>
+
the syscalls are defined in linux/arch/s390/include/asm/unistd.h
-e.g. to trace all file opens just do
-TR SVC 5 ( as this is the syscall number of open )
+e.g. to trace all file opens just do::
+
+ TR SVC 5 ( as this is the syscall number of open )
SMP Specific commands
@@ -1105,33 +1276,51 @@ SMP Specific commands
To find out how many cpus you have
Q CPUS displays all the CPU's available to your virtual machine
To find the cpu that the current cpu VM debugger commands are being directed at
-do Q CPU to change the current cpu VM debugger commands are being directed at do
-CPU <desired cpu no>
+do Q CPU to change the current cpu VM debugger commands are being directed at
+do::
+
+ CPU <desired cpu no>
On a SMP guest issue a command to all CPUs try prefixing the command with cpu
-all. To issue a command to a particular cpu try cpu <cpu number> e.g.
-CPU 01 TR I R 2000.3000
+all. To issue a command to a particular cpu try cpu <cpu number> e.g.::
+
+ CPU 01 TR I R 2000.3000
+
If you are running on a guest with several cpus & you have a IO related problem
& cannot follow the flow of code but you know it isn't smp related.
-from the bash prompt issue
-shutdown -h now or halt.
-do a Q CPUS to find out how many cpus you have
-detach each one of them from cp except cpu 0
-by issuing a
-DETACH CPU 01-(number of cpus in configuration)
+
+from the bash prompt issue::
+
+ shutdown -h now or halt.
+
+do a::
+
+ Q CPUS
+
+to find out how many cpus you have detach each one of them from cp except
+cpu 0 by issuing a::
+
+ DETACH CPU 01-(number of cpus in configuration)
+
& boot linux again.
-TR SIGP will trace inter processor signal processor instructions.
-DEFINE CPU 01-(number in configuration)
-will get your guests cpus back.
+
+TR SIGP
+ will trace inter processor signal processor instructions.
+
+DEFINE CPU 01-(number in configuration)
+ will get your guests cpus back.
Help for displaying ascii textstrings
-------------------------------------
On the very latest VM Nucleus'es VM can now display ascii
-( thanks Neale for the hint ) by doing
-D TX<lowaddr>.<len>
-e.g.
-D TX0.100
+( thanks Neale for the hint ) by doing::
+
+ D TX<lowaddr>.<len>
+
+e.g.::
+
+ D TX0.100
Alternatively
=============
@@ -1143,66 +1332,85 @@ to your xterm if you are debugging from a linuxbox.
This is quite useful when looking at a parameter passed in as a text string
under VM ( unless you are good at decoding ASCII in your head ).
-e.g. consider tracing an open syscall
-TR SVC 5
-We have stopped at a breakpoint
-000151B0' SVC 0A05 -> 0001909A' CC 0
+e.g. consider tracing an open syscall::
+
+ TR SVC 5
+
+We have stopped at a breakpoint::
+
+ 000151B0' SVC 0A05 -> 0001909A' CC 0
D 20.8 to check the SVC old psw in the prefix area and see was it from userspace
(for the layout of the prefix area consult the "Fixed Storage Locations"
chapter of the s/390 Reference Summary if you have it available).
-V00000020 070C2000 800151B2
+
+::
+
+ V00000020 070C2000 800151B2
+
The problem state bit wasn't set & it's also too early in the boot sequence
-for it to be a userspace SVC if it was we would have to temporarily switch the
+for it to be a userspace SVC if it was we would have to temporarily switch the
psw to user space addressing so we could get at the first parameter of the open
in gpr2.
-Next do a
-D G2
-GPR 2 = 00014CB4
-Now display what gpr2 is pointing to
-D 00014CB4.20
-V00014CB4 2F646576 2F636F6E 736F6C65 00001BF5
-V00014CC4 FC00014C B4001001 E0001000 B8070707
+
+Next do a::
+
+ D G2
+ GPR 2 = 00014CB4
+
+Now display what gpr2 is pointing to::
+
+ D 00014CB4.20
+ V00014CB4 2F646576 2F636F6E 736F6C65 00001BF5
+ V00014CC4 FC00014C B4001001 E0001000 B8070707
+
Now copy the text till the first 00 hex ( which is the end of the string
-to an xterm & do hex2ascii on it.
-hex2ascii 2F646576 2F636F6E 736F6C65 00
-outputs
-Decoded Hex:=/ d e v / c o n s o l e 0x00
+to an xterm & do hex2ascii on it::
+
+ hex2ascii 2F646576 2F636F6E 736F6C65 00
+
+outputs::
+
+ Decoded Hex:=/ d e v / c o n s o l e 0x00
+
We were opening the console device,
You can compile the code below yourself for practice :-),
-/*
- * hex2ascii.c
- * a useful little tool for converting a hexadecimal command line to ascii
- *
- * Author(s): Denis Joseph Barrow ([email protected],[email protected])
- * (C) 2000 IBM Deutschland Entwicklung GmbH, IBM Corporation.
- */
-#include <stdio.h>
-int main(int argc,char *argv[])
-{
- int cnt1,cnt2,len,toggle=0;
- int startcnt=1;
- unsigned char c,hex;
-
- if(argc>1&&(strcmp(argv[1],"-a")==0))
- startcnt=2;
- printf("Decoded Hex:=");
- for(cnt1=startcnt;cnt1<argc;cnt1++)
+::
+
+ /*
+ * hex2ascii.c
+ * a useful little tool for converting a hexadecimal command line to ascii
+ *
+ * Author(s): Denis Joseph Barrow ([email protected],[email protected])
+ * (C) 2000 IBM Deutschland Entwicklung GmbH, IBM Corporation.
+ */
+ #include <stdio.h>
+
+ int main(int argc,char *argv[])
{
- len=strlen(argv[cnt1]);
- for(cnt2=0;cnt2<len;cnt2++)
+ int cnt1,cnt2,len,toggle=0;
+ int startcnt=1;
+ unsigned char c,hex;
+
+ if(argc>1&&(strcmp(argv[1],"-a")==0))
+ startcnt=2;
+ printf("Decoded Hex:=");
+ for(cnt1=startcnt;cnt1<argc;cnt1++)
{
- c=argv[cnt1][cnt2];
- if(c>='0'&&c<='9')
+ len=strlen(argv[cnt1]);
+ for(cnt2=0;cnt2<len;cnt2++)
+ {
+ c=argv[cnt1][cnt2];
+ if(c>='0'&&c<='9')
c=c-'0';
- if(c>='A'&&c<='F')
+ if(c>='A'&&c<='F')
c=c-'A'+10;
- if(c>='a'&&c<='f')
+ if(c>='a'&&c<='f')
c=c-'a'+10;
- switch(toggle)
- {
+ switch(toggle)
+ {
case 0:
hex=c<<4;
toggle=1;
@@ -1224,11 +1432,11 @@ int main(int argc,char *argv[])
}
toggle=0;
break;
- }
+ }
+ }
}
+ printf("\n");
}
- printf("\n");
-}
@@ -1248,48 +1456,58 @@ should be able to sniff further back if you follow the following tricks.
1) A kernel address should be easy to recognise since it is in
primary space & the problem state bit isn't set & also
The Hi bit of the address is set.
-2) Another backchain should also be easy to recognise since it is an
+2) Another backchain should also be easy to recognise since it is an
address pointing to another address approximately 100 bytes or 0x70 hex
behind the current stackpointer.
Here is some practice.
+
boot the kernel & hit PA1 at some random time
-d g to display the gprs, this should display something like
-GPR 0 = 00000001 00156018 0014359C 00000000
-GPR 4 = 00000001 001B8888 000003E0 00000000
-GPR 8 = 00100080 00100084 00000000 000FE000
-GPR 12 = 00010400 8001B2DC 8001B36A 000FFED8
+
+d g to display the gprs, this should display something like::
+
+ GPR 0 = 00000001 00156018 0014359C 00000000
+ GPR 4 = 00000001 001B8888 000003E0 00000000
+ GPR 8 = 00100080 00100084 00000000 000FE000
+ GPR 12 = 00010400 8001B2DC 8001B36A 000FFED8
+
Note that GPR14 is a return address but as we are real men we are going to
trace the stack.
-display 0x40 bytes after the stack pointer.
+display 0x40 bytes after the stack pointer::
-V000FFED8 000FFF38 8001B838 80014C8E 000FFF38
-V000FFEE8 00000000 00000000 000003E0 00000000
-V000FFEF8 00100080 00100084 00000000 000FE000
-V000FFF08 00010400 8001B2DC 8001B36A 000FFED8
+ V000FFED8 000FFF38 8001B838 80014C8E 000FFF38
+ V000FFEE8 00000000 00000000 000003E0 00000000
+ V000FFEF8 00100080 00100084 00000000 000FE000
+ V000FFF08 00010400 8001B2DC 8001B36A 000FFED8
Ah now look at whats in sp+56 (sp+0x38) this is 8001B36A our saved r14 if
you look above at our stackframe & also agrees with GPR14.
-now backchain
-d 000FFF38.40
-we now are taking the contents of SP to get our first backchain.
+now backchain::
-V000FFF38 000FFFA0 00000000 00014995 00147094
-V000FFF48 00147090 001470A0 000003E0 00000000
-V000FFF58 00100080 00100084 00000000 001BF1D0
-V000FFF68 00010400 800149BA 80014CA6 000FFF38
+ d 000FFF38.40
+
+we now are taking the contents of SP to get our first backchain::
+
+ V000FFF38 000FFFA0 00000000 00014995 00147094
+ V000FFF48 00147090 001470A0 000003E0 00000000
+ V000FFF58 00100080 00100084 00000000 001BF1D0
+ V000FFF68 00010400 800149BA 80014CA6 000FFF38
This displays a 2nd return address of 80014CA6
-now do d 000FFFA0.40 for our 3rd backchain
+now do::
-V000FFFA0 04B52002 0001107F 00000000 00000000
-V000FFFB0 00000000 00000000 FF000000 0001107F
-V000FFFC0 00000000 00000000 00000000 00000000
-V000FFFD0 00010400 80010802 8001085A 000FFFA0
+ d 000FFFA0.40
+
+for our 3rd backchain::
+
+ V000FFFA0 04B52002 0001107F 00000000 00000000
+ V000FFFB0 00000000 00000000 FF000000 0001107F
+ V000FFFC0 00000000 00000000 00000000 00000000
+ V000FFFD0 00010400 80010802 8001085A 000FFFA0
our 3rd return address is 8001085A
@@ -1297,23 +1515,35 @@ our 3rd return address is 8001085A
as the 04B52002 looks suspiciously like rubbish it is fair to assume that the
kernel entry routines for the sake of optimisation don't set up a backchain.
-now look at System.map to see if the addresses make any sense.
+now look at System.map to see if the addresses make any sense::
+
+ grep -i 0001b3 System.map
+
+outputs among other things::
+
+ 0001b304 T cpu_idle
-grep -i 0001b3 System.map
-outputs among other things
-0001b304 T cpu_idle
so 8001B36A
is cpu_idle+0x66 ( quiet the cpu is asleep, don't wake it )
+::
+
+ grep -i 00014 System.map
+
+produces among other things::
+
+ 00014a78 T start_kernel
-grep -i 00014 System.map
-produces among other things
-00014a78 T start_kernel
so 0014CA6 is start_kernel+some hex number I can't add in my head.
-grep -i 00108 System.map
-this produces
-00010800 T _stext
+::
+
+ grep -i 00108 System.map
+
+this produces::
+
+ 00010800 T _stext
+
so 8001085A is _stext+0x5a
Congrats you've done your first backchain.
@@ -1337,47 +1567,49 @@ system might be choking with around 64.
Here is some of the common IO terminology:
Subchannel:
-This is the logical number most IO commands use to talk to an IO device. There
-can be up to 0x10000 (65536) of these in a configuration, typically there are a
-few hundred. Under VM for simplicity they are allocated contiguously, however
-on the native hardware they are not. They typically stay consistent between
-boots provided no new hardware is inserted or removed.
-Under Linux for s390 we use these as IRQ's and also when issuing an IO command
-(CLEAR SUBCHANNEL, HALT SUBCHANNEL, MODIFY SUBCHANNEL, RESUME SUBCHANNEL,
-START SUBCHANNEL, STORE SUBCHANNEL and TEST SUBCHANNEL). We use this as the ID
-of the device we wish to talk to. The most important of these instructions are
-START SUBCHANNEL (to start IO), TEST SUBCHANNEL (to check whether the IO
-completed successfully) and HALT SUBCHANNEL (to kill IO). A subchannel can have
-up to 8 channel paths to a device, this offers redundancy if one is not
-available.
+ This is the logical number most IO commands use to talk to an IO device. There
+ can be up to 0x10000 (65536) of these in a configuration, typically there are a
+ few hundred. Under VM for simplicity they are allocated contiguously, however
+ on the native hardware they are not. They typically stay consistent between
+ boots provided no new hardware is inserted or removed.
+
+ Under Linux for s390 we use these as IRQ's and also when issuing an IO command
+ (CLEAR SUBCHANNEL, HALT SUBCHANNEL, MODIFY SUBCHANNEL, RESUME SUBCHANNEL,
+ START SUBCHANNEL, STORE SUBCHANNEL and TEST SUBCHANNEL). We use this as the ID
+ of the device we wish to talk to. The most important of these instructions are
+ START SUBCHANNEL (to start IO), TEST SUBCHANNEL (to check whether the IO
+ completed successfully) and HALT SUBCHANNEL (to kill IO). A subchannel can have
+ up to 8 channel paths to a device, this offers redundancy if one is not
+ available.
Device Number:
-This number remains static and is closely tied to the hardware. There are 65536
-of these, made up of a CHPID (Channel Path ID, the most significant 8 bits) and
-another lsb 8 bits. These remain static even if more devices are inserted or
-removed from the hardware. There is a 1 to 1 mapping between subchannels and
-device numbers, provided devices aren't inserted or removed.
+ This number remains static and is closely tied to the hardware. There are 65536
+ of these, made up of a CHPID (Channel Path ID, the most significant 8 bits) and
+ another lsb 8 bits. These remain static even if more devices are inserted or
+ removed from the hardware. There is a 1 to 1 mapping between subchannels and
+ device numbers, provided devices aren't inserted or removed.
Channel Control Words:
-CCWs are linked lists of instructions initially pointed to by an operation
-request block (ORB), which is initially given to Start Subchannel (SSCH)
-command along with the subchannel number for the IO subsystem to process
-while the CPU continues executing normal code.
-CCWs come in two flavours, Format 0 (24 bit for backward compatibility) and
-Format 1 (31 bit). These are typically used to issue read and write (and many
-other) instructions. They consist of a length field and an absolute address
-field.
-Each IO typically gets 1 or 2 interrupts, one for channel end (primary status)
-when the channel is idle, and the second for device end (secondary status).
-Sometimes you get both concurrently. You check how the IO went on by issuing a
-TEST SUBCHANNEL at each interrupt, from which you receive an Interruption
-response block (IRB). If you get channel and device end status in the IRB
-without channel checks etc. your IO probably went okay. If you didn't you
-probably need to examine the IRB, extended status word etc.
-If an error occurs, more sophisticated control units have a facility known as
-concurrent sense. This means that if an error occurs Extended sense information
-will be presented in the Extended status word in the IRB. If not you have to
-issue a subsequent SENSE CCW command after the test subchannel.
+ CCWs are linked lists of instructions initially pointed to by an operation
+ request block (ORB), which is initially given to Start Subchannel (SSCH)
+ command along with the subchannel number for the IO subsystem to process
+ while the CPU continues executing normal code.
+ CCWs come in two flavours, Format 0 (24 bit for backward compatibility) and
+ Format 1 (31 bit). These are typically used to issue read and write (and many
+ other) instructions. They consist of a length field and an absolute address
+ field.
+
+ Each IO typically gets 1 or 2 interrupts, one for channel end (primary status)
+ when the channel is idle, and the second for device end (secondary status).
+ Sometimes you get both concurrently. You check how the IO went on by issuing a
+ TEST SUBCHANNEL at each interrupt, from which you receive an Interruption
+ response block (IRB). If you get channel and device end status in the IRB
+ without channel checks etc. your IO probably went okay. If you didn't you
+ probably need to examine the IRB, extended status word etc.
+ If an error occurs, more sophisticated control units have a facility known as
+ concurrent sense. This means that if an error occurs Extended sense information
+ will be presented in the Extended status word in the IRB. If not you have to
+ issue a subsequent SENSE CCW command after the test subchannel.
TPI (Test pending interrupt) can also be used for polled IO, but in
@@ -1388,58 +1620,62 @@ Store Subchannel and Modify Subchannel can be used to examine and modify
operating characteristics of a subchannel (e.g. channel paths).
Other IO related Terms:
-Sysplex: S390's Clustering Technology
-QDIO: S390's new high speed IO architecture to support devices such as gigabit
-ethernet, this architecture is also designed to be forward compatible with
-upcoming 64 bit machines.
+Sysplex:
+ S390's Clustering Technology
+QDIO:
+ S390's new high speed IO architecture to support devices such as gigabit
+ ethernet, this architecture is also designed to be forward compatible with
+ upcoming 64 bit machines.
-General Concepts
+
+General Concepts
+----------------
Input Output Processors (IOP's) are responsible for communicating between
the mainframe CPU's & the channel & relieve the mainframe CPU's from the
-burden of communicating with IO devices directly, this allows the CPU's to
-concentrate on data processing.
+burden of communicating with IO devices directly, this allows the CPU's to
+concentrate on data processing.
-IOP's can use one or more links ( known as channel paths ) to talk to each
+IOP's can use one or more links ( known as channel paths ) to talk to each
IO device. It first checks for path availability & chooses an available one,
then starts ( & sometimes terminates IO ).
There are two types of channel path: ESCON & the Parallel IO interface.
IO devices are attached to control units, control units provide the
-logic to interface the channel paths & channel path IO protocols to
+logic to interface the channel paths & channel path IO protocols to
the IO devices, they can be integrated with the devices or housed separately
-& often talk to several similar devices ( typical examples would be raid
-controllers or a control unit which connects to 1000 3270 terminals ).
+& often talk to several similar devices ( typical examples would be raid
+controllers or a control unit which connects to 1000 3270 terminals )::
- +---------------------------------------------------------------+
- | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ |
- | | CPU | | CPU | | CPU | | CPU | | Main | | Expanded | |
- | | | | | | | | | | Memory | | Storage | |
- | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ |
- |---------------------------------------------------------------+
- | IOP | IOP | IOP |
- |---------------------------------------------------------------
- | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C |
- ----------------------------------------------------------------
- || ||
- || Bus & Tag Channel Path || ESCON
- || ====================== || Channel
- || || || || Path
- +----------+ +----------+ +----------+
- | | | | | |
- | CU | | CU | | CU |
- | | | | | |
- +----------+ +----------+ +----------+
- | | | | |
-+----------+ +----------+ +----------+ +----------+ +----------+
-|I/O Device| |I/O Device| |I/O Device| |I/O Device| |I/O Device|
-+----------+ +----------+ +----------+ +----------+ +----------+
- CPU = Central Processing Unit
- C = Channel
- IOP = IP Processor
- CU = Control Unit
+ +---------------------------------------------------------------+
+ | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ |
+ | | CPU | | CPU | | CPU | | CPU | | Main | | Expanded | |
+ | | | | | | | | | | Memory | | Storage | |
+ | +-----+ +-----+ +-----+ +-----+ +----------+ +----------+ |
+ |---------------------------------------------------------------+
+ | IOP | IOP | IOP |
+ |---------------------------------------------------------------
+ | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C | C |
+ ----------------------------------------------------------------
+ || ||
+ || Bus & Tag Channel Path || ESCON
+ || ====================== || Channel
+ || || || || Path
+ +----------+ +----------+ +----------+
+ | | | | | |
+ | CU | | CU | | CU |
+ | | | | | |
+ +----------+ +----------+ +----------+
+ | | | | |
+ +----------+ +----------+ +----------+ +----------+ +----------+
+ |I/O Device| |I/O Device| |I/O Device| |I/O Device| |I/O Device|
+ +----------+ +----------+ +----------+ +----------+ +----------+
+ CPU = Central Processing Unit
+ C = Channel
+ IOP = IP Processor
+ CU = Control Unit
The 390 IO systems come in 2 flavours the current 390 machines support both
@@ -1447,7 +1683,7 @@ The Older 360 & 370 Interface,sometimes called the Parallel I/O interface,
sometimes called Bus-and Tag & sometimes Original Equipment Manufacturers
Interface (OEMI).
-This byte wide Parallel channel path/bus has parity & data on the "Bus" cable
+This byte wide Parallel channel path/bus has parity & data on the "Bus" cable
and control lines on the "Tag" cable. These can operate in byte multiplex mode
for sharing between several slow devices or burst mode and monopolize the
channel for the whole burst. Up to 256 devices can be addressed on one of these
@@ -1459,13 +1695,13 @@ support only transfer rates of 3.0, 2.0 & 1.0 MB/sec.
One of these paths can be daisy chained to up to 8 control units.
-ESCON if fibre optic it is also called FICON
+ESCON if fibre optic it is also called FICON
Was introduced by IBM in 1990. Has 2 fibre optic cables and uses either leds or
lasers for communication at a signaling rate of up to 200 megabits/sec. As
10bits are transferred for every 8 bits info this drops to 160 megabits/sec
and to 18.6 Megabytes/sec once control info and CRC are added. ESCON only
operates in burst mode.
-
+
ESCONs typical max cable length is 3km for the led version and 20km for the
laser version known as XDF (extended distance facility). This can be further
extended by using an ESCON director which triples the above mentioned ranges.
@@ -1489,31 +1725,29 @@ Debugging IO on s/390 & z/Architecture under VM
Now we are ready to go on with IO tracing commands under VM
-A few self explanatory queries:
-Q OSA
-Q CTC
-Q DISK ( This command is CMS specific )
-Q DASD
+A few self explanatory queries::
+ Q OSA
+ Q CTC
+ Q DISK ( This command is CMS specific )
+ Q DASD
+Q OSA on my machine returns::
-
-
-
-Q OSA on my machine returns
-OSA 7C08 ON OSA 7C08 SUBCHANNEL = 0000
-OSA 7C09 ON OSA 7C09 SUBCHANNEL = 0001
-OSA 7C14 ON OSA 7C14 SUBCHANNEL = 0002
-OSA 7C15 ON OSA 7C15 SUBCHANNEL = 0003
+ OSA 7C08 ON OSA 7C08 SUBCHANNEL = 0000
+ OSA 7C09 ON OSA 7C09 SUBCHANNEL = 0001
+ OSA 7C14 ON OSA 7C14 SUBCHANNEL = 0002
+ OSA 7C15 ON OSA 7C15 SUBCHANNEL = 0003
If you have a guest with certain privileges you may be able to see devices
which don't belong to you. To avoid this, add the option V.
-e.g.
-Q V OSA
+e.g.::
+
+ Q V OSA
Now using the device numbers returned by this command we will
Trace the io starting up on the first device 7c08 & 7c09
-In our simplest case we can trace the
+In our simplest case we can trace the
start subchannels
like TR SSCH 7C08-7C09
or the halt subchannels
@@ -1524,34 +1758,47 @@ A good trick is tracing all the IO's and CCWS and spooling them into the reader
of another VM guest so he can ftp the logfile back to his own machine. I'll do
a small bit of this and give you a look at the output.
-1) Spool stdout to VM reader
-SP PRT TO (another vm guest ) or * for the local vm guest
-2) Fill the reader with the trace
-TR IO 7c08-7c09 INST INT CCW PRT RUN
-3) Start up linux
-i 00c
-4) Finish the trace
-TR END
-5) close the reader
-C PRT
-6) list reader contents
-RDRLIST
-7) copy it to linux4's minidisk
-RECEIVE / LOG TXT A1 ( replace
+1) Spool stdout to VM reader::
+
+ SP PRT TO (another vm guest ) or * for the local vm guest
+
+2) Fill the reader with the trace::
+
+ TR IO 7c08-7c09 INST INT CCW PRT RUN
+
+3) Start up linux::
+
+ i 00c
+4) Finish the trace::
+
+ TR END
+
+5) close the reader::
+
+ C PRT
+
+6) list reader contents::
+
+ RDRLIST
+
+7) copy it to linux4's minidisk::
+
+ RECEIVE / LOG TXT A1 ( replace
+
8)
filel & press F11 to look at it
-You should see something like:
+You should see something like::
-00020942' SSCH B2334000 0048813C CC 0 SCH 0000 DEV 7C08
- CPA 000FFDF0 PARM 00E2C9C4 KEY 0 FPI C0 LPM 80
- CCW 000FFDF0 E4200100 00487FE8 0000 E4240100 ........
- IDAL 43D8AFE8
- IDAL 0FB76000
-00020B0A' I/O DEV 7C08 -> 000197BC' SCH 0000 PARM 00E2C9C4
-00021628' TSCH B2354000 >> 00488164 CC 0 SCH 0000 DEV 7C08
- CCWA 000FFDF8 DEV STS 0C SCH STS 00 CNT 00EC
- KEY 0 FPI C0 CC 0 CTLS 4007
-00022238' STSCH B2344000 >> 00488108 CC 0 SCH 0000 DEV 7C08
+ 00020942' SSCH B2334000 0048813C CC 0 SCH 0000 DEV 7C08
+ CPA 000FFDF0 PARM 00E2C9C4 KEY 0 FPI C0 LPM 80
+ CCW 000FFDF0 E4200100 00487FE8 0000 E4240100 ........
+ IDAL 43D8AFE8
+ IDAL 0FB76000
+ 00020B0A' I/O DEV 7C08 -> 000197BC' SCH 0000 PARM 00E2C9C4
+ 00021628' TSCH B2354000 >> 00488164 CC 0 SCH 0000 DEV 7C08
+ CCWA 000FFDF8 DEV STS 0C SCH STS 00 CNT 00EC
+ KEY 0 FPI C0 CC 0 CTLS 4007
+ 00022238' STSCH B2344000 >> 00488108 CC 0 SCH 0000 DEV 7C08
If you don't like messing up your readed ( because you possibly booted from it )
you can alternatively spool it to another readers guest.
@@ -1563,43 +1810,58 @@ These commands are listed only because they have
been of use to me in the past & may be of use to
you too. For more complete info on each of the commands
use type HELP <command> from CMS.
-detaching devices
-DET <devno range>
-ATT <devno range> <guest>
+
+detaching devices::
+
+ DET <devno range>
+ ATT <devno range> <guest>
+
attach a device to guest * for your own guest
-READY <devno> cause VM to issue a fake interrupt.
-The VARY command is normally only available to VM administrators.
-VARY ON PATH <path> TO <devno range>
-VARY OFF PATH <PATH> FROM <devno range>
+READY <devno>
+ cause VM to issue a fake interrupt.
+
+The VARY command is normally only available to VM administrators::
+
+ VARY ON PATH <path> TO <devno range>
+ VARY OFF PATH <PATH> FROM <devno range>
+
This is used to switch on or off channel paths to devices.
Q CHPID <channel path ID>
-This displays state of devices using this channel path
+ This displays state of devices using this channel path
+
D SCHIB <subchannel>
-This displays the subchannel information SCHIB block for the device.
-this I believe is also only available to administrators.
+ This displays the subchannel information SCHIB block for the device.
+ this I believe is also only available to administrators.
+
DEFINE CTC <devno>
-defines a virtual CTC channel to channel connection
-2 need to be defined on each guest for the CTC driver to use.
+ defines a virtual CTC channel to channel connection
+ 2 need to be defined on each guest for the CTC driver to use.
+
COUPLE devno userid remote devno
-Joins a local virtual device to a remote virtual device
-( commonly used for the CTC driver ).
+ Joins a local virtual device to a remote virtual device
+ ( commonly used for the CTC driver ).
+
+Building a VM ramdisk under CMS which linux can use::
+
+ def vfb-<blocksize> <subchannel> <number blocks>
-Building a VM ramdisk under CMS which linux can use
-def vfb-<blocksize> <subchannel> <number blocks>
blocksize is commonly 4096 for linux.
-Formatting it
-format <subchannel> <driver letter e.g. x> (blksize <blocksize>
-Sharing a disk between multiple guests
-LINK userid devno1 devno2 mode password
+Formatting it::
+
+ format <subchannel> <driver letter e.g. x> (blksize <blocksize>
+
+Sharing a disk between multiple guests::
+
+ LINK userid devno1 devno2 mode password
GDB on S390
===========
-N.B. if compiling for debugging gdb works better without optimisation
+N.B. if compiling for debugging gdb works better without optimisation
( see Compiling programs for debugging )
invocation
@@ -1609,113 +1871,169 @@ gdb <victim program> <optional corefile>
Online help
-----------
help: gives help on commands
-e.g.
-help
-help display
+
+e.g.::
+
+ help
+ help display
+
Note gdb's online help is very good use it.
Assembly
--------
-info registers: displays registers other than floating point.
-info all-registers: displays floating points as well.
-disassemble: disassembles
-e.g.
-disassemble without parameters will disassemble the current function
-disassemble $pc $pc+10
+info registers:
+ displays registers other than floating point.
+
+info all-registers:
+ displays floating points as well.
+
+disassemble:
+ disassembles
+
+e.g.::
+
+ disassemble without parameters will disassemble the current function
+ disassemble $pc $pc+10
Viewing & modifying variables
-----------------------------
-print or p: displays variable or register
+print or p:
+ displays variable or register
+
e.g. p/x $sp will display the stack pointer
-display: prints variable or register each time program stops
-e.g.
-display/x $pc will display the program counter
-display argc
+display:
+ prints variable or register each time program stops
-undisplay : undo's display's
+e.g.::
-info breakpoints: shows all current breakpoints
+ display/x $pc will display the program counter
+ display argc
-info stack: shows stack back trace (if this doesn't work too well, I'll show
-you the stacktrace by hand below).
+undisplay:
+ undo's display's
-info locals: displays local variables.
+info breakpoints:
+ shows all current breakpoints
-info args: display current procedure arguments.
+info stack:
+ shows stack back trace (if this doesn't work too well, I'll show
+ you the stacktrace by hand below).
-set args: will set argc & argv each time the victim program is invoked.
+info locals:
+ displays local variables.
-set <variable>=value
-set argc=100
-set $pc=0
+info args:
+ display current procedure arguments.
+
+set args:
+ will set argc & argv each time the victim program is invoked
+
+e.g.::
+
+ set <variable>=value
+ set argc=100
+ set $pc=0
Modifying execution
-------------------
-step: steps n lines of sourcecode
-step steps 1 line.
-step 100 steps 100 lines of code.
+step:
+ steps n lines of sourcecode
-next: like step except this will not step into subroutines
+step
+ steps 1 line.
-stepi: steps a single machine code instruction.
-e.g. stepi 100
+step 100
+ steps 100 lines of code.
-nexti: steps a single machine code instruction but will not step into
-subroutines.
+next:
+ like step except this will not step into subroutines
-finish: will run until exit of the current routine
+stepi:
+ steps a single machine code instruction.
-run: (re)starts a program
+e.g.::
-cont: continues a program
+ stepi 100
-quit: exits gdb.
+nexti:
+ steps a single machine code instruction but will not step into
+ subroutines.
+
+finish:
+ will run until exit of the current routine
+
+run:
+ (re)starts a program
+
+cont:
+ continues a program
+
+quit:
+ exits gdb.
breakpoints
------------
break
-sets a breakpoint
-e.g.
+ sets a breakpoint
-break main
+e.g.::
-break *$pc
-
-break *0x400618
+ break main
+ break *$pc
+ break *0x400618
Here's a really useful one for large programs
+
rbr
-Set a breakpoint for all functions matching REGEXP
-e.g.
-rbr 390
+ Set a breakpoint for all functions matching REGEXP
+
+e.g.::
+
+ rbr 390
+
will set a breakpoint with all functions with 390 in their name.
info breakpoints
-lists all breakpoints
+ lists all breakpoints
+
+delete:
+ delete breakpoint by number or delete them all
-delete: delete breakpoint by number or delete them all
e.g.
-delete 1 will delete the first breakpoint
-delete will delete them all
-watch: This will set a watchpoint ( usually hardware assisted ),
+delete 1
+ will delete the first breakpoint
+
+
+delete
+ will delete them all
+
+watch:
+ This will set a watchpoint ( usually hardware assisted ),
+
This will watch a variable till it changes
+
e.g.
-watch cnt, will watch the variable cnt till it changes.
+
+watch cnt
+ will watch the variable cnt till it changes.
+
As an aside unfortunately gdb's, architecture independent watchpoint code
is inconsistent & not very good, watchpoints usually work but not always.
-info watchpoints: Display currently active watchpoints
+info watchpoints:
+ Display currently active watchpoints
condition: ( another useful one )
-Specify breakpoint number N to break only if COND is true.
-Usage is `condition N COND', where N is an integer and COND is an
+ Specify breakpoint number N to break only if COND is true.
+
+Usage is `condition N COND`, where N is an integer and COND is an
expression to be evaluated whenever breakpoint N is reached.
@@ -1723,41 +2041,51 @@ expression to be evaluated whenever breakpoint N is reached.
User defined functions/macros
-----------------------------
define: ( Note this is very very useful,simple & powerful )
+
usage define <name> <list of commands> end
-examples which you should consider putting into .gdbinit in your home directory
-define d
-stepi
-disassemble $pc $pc+10
-end
+examples which you should consider putting into .gdbinit in your home
+directory::
-define e
-nexti
-disassemble $pc $pc+10
-end
+ define d
+ stepi
+ disassemble $pc $pc+10
+ end
+ define e
+ nexti
+ disassemble $pc $pc+10
+ end
Other hard to classify stuff
----------------------------
signal n:
-sends the victim program a signal.
-e.g. signal 3 will send a SIGQUIT.
+ sends the victim program a signal.
+
+e.g. `signal 3` will send a SIGQUIT.
info signals:
-what gdb does when the victim receives certain signals.
+ what gdb does when the victim receives certain signals.
list:
-e.g.
-list lists current function source
-list 1,10 list first 10 lines of current file.
+
+e.g.:
+
+list
+ lists current function source
+list 1,10
+ list first 10 lines of current file.
+
list test.c:1,10
directory:
-Adds directories to be searched for source if gdb cannot find the source.
-(note it is a bit sensitive about slashes)
-e.g. To add the root of the filesystem to the searchpath do
-directory //
+ Adds directories to be searched for source if gdb cannot find the source.
+ (note it is a bit sensitive about slashes)
+
+e.g. To add the root of the filesystem to the searchpath do::
+
+ directory //
call <function>
@@ -1765,153 +2093,205 @@ This calls a function in the victim program, this is pretty powerful
e.g.
(gdb) call printf("hello world")
outputs:
-$1 = 11
+$1 = 11
You might now be thinking that the line above didn't work, something extra had
to be done.
(gdb) call fflush(stdout)
hello world$2 = 0
-As an aside the debugger also calls malloc & free under the hood
+As an aside the debugger also calls malloc & free under the hood
to make space for the "hello world" string.
hints
-----
-1) command completion works just like bash
-( if you are a bad typist like me this really helps )
+1) command completion works just like bash
+ ( if you are a bad typist like me this really helps )
+
e.g. hit br <TAB> & cursor up & down :-).
2) if you have a debugging problem that takes a few steps to recreate
put the steps into a file called .gdbinit in your current working directory
-if you have defined a few extra useful user defined commands put these in
+if you have defined a few extra useful user defined commands put these in
your home directory & they will be read each time gdb is launched.
-A typical .gdbinit file might be.
-break main
-run
-break runtime_exception
-cont
+A typical .gdbinit file might be.::
+
+ break main
+ run
+ break runtime_exception
+ cont
stack chaining in gdb by hand
-----------------------------
-This is done using a the same trick described for VM
-p/x (*($sp+56))&0x7fffffff get the first backchain.
+This is done using a the same trick described for VM::
+
+ p/x (*($sp+56))&0x7fffffff
+
+get the first backchain.
For z/Architecture
Replace 56 with 112 & ignore the &0x7fffffff
in the macros below & do nasty casts to longs like the following
as gdb unfortunately deals with printed arguments as ints which
messes up everything.
-i.e. here is a 3rd backchain dereference
-p/x *(long *)(***(long ***)$sp+112)
+i.e. here is a 3rd backchain dereference::
+
+ p/x *(long *)(***(long ***)$sp+112)
+
+
+this outputs::
+
+ $5 = 0x528f18
-this outputs
-$5 = 0x528f18
on my machine.
-Now you can use
-info symbol (*($sp+56))&0x7fffffff
-you might see something like.
-rl_getc + 36 in section .text telling you what is located at address 0x528f18
-Now do.
-p/x (*(*$sp+56))&0x7fffffff
-This outputs
-$6 = 0x528ed0
-Now do.
-info symbol (*(*$sp+56))&0x7fffffff
-rl_read_key + 180 in section .text
-now do
-p/x (*(**$sp+56))&0x7fffffff
+
+Now you can use::
+
+ info symbol (*($sp+56))&0x7fffffff
+
+you might see something like::
+
+ rl_getc + 36 in section .text
+
+telling you what is located at address 0x528f18
+Now do::
+
+ p/x (*(*$sp+56))&0x7fffffff
+
+This outputs::
+
+ $6 = 0x528ed0
+
+Now do::
+
+ info symbol (*(*$sp+56))&0x7fffffff
+ rl_read_key + 180 in section .text
+
+now do::
+
+ p/x (*(**$sp+56))&0x7fffffff
+
& so on.
Disassembling instructions without debug info
---------------------------------------------
gdb typically complains if there is a lack of debugging
-symbols in the disassemble command with
+symbols in the disassemble command with
"No function contains specified address." To get around
-this do
-x/<number lines to disassemble>xi <address>
-e.g.
-x/20xi 0x400730
+this do::
+ x/<number lines to disassemble>xi <address>
+e.g.::
-Note: Remember gdb has history just like bash you don't need to retype the
-whole line just use the up & down arrows.
+ x/20xi 0x400730
+
+
+
+Note:
+ Remember gdb has history just like bash you don't need to retype the
+ whole line just use the up & down arrows.
For more info
-------------
-From your linuxbox do
-man gdb or info gdb.
+From your linuxbox do::
+
+ man gdb
+
+or::
+
+ info gdb.
core dumps
----------
-What a core dump ?,
+
+What a core dump ?
+^^^^^^^^^^^^^^^^^^
+
A core dump is a file generated by the kernel (if allowed) which contains the
registers and all active pages of the program which has crashed.
+
From this file gdb will allow you to look at the registers, stack trace and
memory of the program as if it just crashed on your system. It is usually
called core and created in the current working directory.
+
This is very useful in that a customer can mail a core dump to a technical
support department and the technical support department can reconstruct what
happened. Provided they have an identical copy of this program with debugging
symbols compiled in and the source base of this build is available.
+
In short it is far more useful than something like a crash log could ever hope
to be.
-Why have I never seen one ?.
-Probably because you haven't used the command
-ulimit -c unlimited in bash
-to allow core dumps, now do
-ulimit -a
+Why have I never seen one ?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Probably because you haven't used the command::
+
+ ulimit -c unlimited in bash
+
+to allow core dumps, now do::
+
+ ulimit -a
+
to verify that the limit was accepted.
A sample core dump
-To create this I'm going to do
-ulimit -c unlimited
-gdb
-to launch gdb (my victim app. ) now be bad & do the following from another
-telnet/xterm session to the same machine
-ps -aux | grep gdb
-kill -SIGSEGV <gdb's pid>
-or alternatively use killall -SIGSEGV gdb if you have the killall command.
-Now look at the core dump.
-./gdb core
-Displays the following
-GNU gdb 4.18
-Copyright 1998 Free Software Foundation, Inc.
-GDB is free software, covered by the GNU General Public License, and you are
-welcome to change it and/or distribute copies of it under certain conditions.
-Type "show copying" to see the conditions.
-There is absolutely no warranty for GDB. Type "show warranty" for details.
-This GDB was configured as "s390-ibm-linux"...
-Core was generated by `./gdb'.
-Program terminated with signal 11, Segmentation fault.
-Reading symbols from /usr/lib/libncurses.so.4...done.
-Reading symbols from /lib/libm.so.6...done.
-Reading symbols from /lib/libc.so.6...done.
-Reading symbols from /lib/ld-linux.so.2...done.
-#0 0x40126d1a in read () from /lib/libc.so.6
-Setting up the environment for debugging gdb.
-Breakpoint 1 at 0x4dc6f8: file utils.c, line 471.
-Breakpoint 2 at 0x4d87a4: file top.c, line 2609.
-(top-gdb) info stack
-#0 0x40126d1a in read () from /lib/libc.so.6
-#1 0x528f26 in rl_getc (stream=0x7ffffde8) at input.c:402
-#2 0x528ed0 in rl_read_key () at input.c:381
-#3 0x5167e6 in readline_internal_char () at readline.c:454
-#4 0x5168ee in readline_internal_charloop () at readline.c:507
-#5 0x51692c in readline_internal () at readline.c:521
-#6 0x5164fe in readline (prompt=0x7ffff810)
- at readline.c:349
-#7 0x4d7a8a in command_line_input (prompt=0x564420 "(gdb) ", repeat=1,
- annotation_suffix=0x4d6b44 "prompt") at top.c:2091
-#8 0x4d6cf0 in command_loop () at top.c:1345
-#9 0x4e25bc in main (argc=1, argv=0x7ffffdf4) at main.c:635
+ To create this I'm going to do::
+
+ ulimit -c unlimited
+ gdb
+
+to launch gdb (my victim app. ) now be bad & do the following from another
+telnet/xterm session to the same machine::
+
+ ps -aux | grep gdb
+ kill -SIGSEGV <gdb's pid>
+
+or alternatively use `killall -SIGSEGV gdb` if you have the killall command.
+
+Now look at the core dump::
+
+ ./gdb core
+
+Displays the following::
+
+ GNU gdb 4.18
+ Copyright 1998 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License, and you are
+ welcome to change it and/or distribute copies of it under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB. Type "show warranty" for details.
+ This GDB was configured as "s390-ibm-linux"...
+ Core was generated by `./gdb'.
+ Program terminated with signal 11, Segmentation fault.
+ Reading symbols from /usr/lib/libncurses.so.4...done.
+ Reading symbols from /lib/libm.so.6...done.
+ Reading symbols from /lib/libc.so.6...done.
+ Reading symbols from /lib/ld-linux.so.2...done.
+ #0 0x40126d1a in read () from /lib/libc.so.6
+ Setting up the environment for debugging gdb.
+ Breakpoint 1 at 0x4dc6f8: file utils.c, line 471.
+ Breakpoint 2 at 0x4d87a4: file top.c, line 2609.
+ (top-gdb) info stack
+ #0 0x40126d1a in read () from /lib/libc.so.6
+ #1 0x528f26 in rl_getc (stream=0x7ffffde8) at input.c:402
+ #2 0x528ed0 in rl_read_key () at input.c:381
+ #3 0x5167e6 in readline_internal_char () at readline.c:454
+ #4 0x5168ee in readline_internal_charloop () at readline.c:507
+ #5 0x51692c in readline_internal () at readline.c:521
+ #6 0x5164fe in readline (prompt=0x7ffff810)
+ at readline.c:349
+ #7 0x4d7a8a in command_line_input (prompt=0x564420 "(gdb) ", repeat=1,
+ annotation_suffix=0x4d6b44 "prompt") at top.c:2091
+ #8 0x4d6cf0 in command_loop () at top.c:1345
+ #9 0x4e25bc in main (argc=1, argv=0x7ffffdf4) at main.c:635
LDD
@@ -1919,27 +2299,32 @@ LDD
This is a program which lists the shared libraries which a library needs,
Note you also get the relocations of the shared library text segments which
help when using objdump --source.
-e.g.
- ldd ./gdb
-outputs
-libncurses.so.4 => /usr/lib/libncurses.so.4 (0x40018000)
-libm.so.6 => /lib/libm.so.6 (0x4005e000)
-libc.so.6 => /lib/libc.so.6 (0x40084000)
-/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+
+e.g.::
+
+ ldd ./gdb
+
+outputs::
+
+ libncurses.so.4 => /usr/lib/libncurses.so.4 (0x40018000)
+ libm.so.6 => /lib/libm.so.6 (0x4005e000)
+ libc.so.6 => /lib/libc.so.6 (0x40084000)
+ /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
Debugging shared libraries
==========================
Most programs use shared libraries, however it can be very painful
-when you single step instruction into a function like printf for the
+when you single step instruction into a function like printf for the
first time & you end up in functions like _dl_runtime_resolve this is
-the ld.so doing lazy binding, lazy binding is a concept in ELF where
-shared library functions are not loaded into memory unless they are
+the ld.so doing lazy binding, lazy binding is a concept in ELF where
+shared library functions are not loaded into memory unless they are
actually used, great for saving memory but a pain to debug.
-To get around this either relink the program -static or exit gdb type
-export LD_BIND_NOW=true this will stop lazy binding & restart the gdb'ing
+
+To get around this either relink the program -static or exit gdb type
+export LD_BIND_NOW=true this will stop lazy binding & restart the gdb'ing
the program in question.
-
+
Debugging modules
@@ -1955,106 +2340,127 @@ It is a filesystem created by the kernel with files which are created on demand
by the kernel if read, or can be used to modify kernel parameters,
it is a powerful concept.
-e.g.
-
-cat /proc/sys/net/ipv4/ip_forward
-On my machine outputs
-0
-telling me ip_forwarding is not on to switch it on I can do
-echo 1 > /proc/sys/net/ipv4/ip_forward
-cat it again
-cat /proc/sys/net/ipv4/ip_forward
-On my machine now outputs
-1
+e.g.::
+
+ cat /proc/sys/net/ipv4/ip_forward
+
+On my machine outputs::
+
+ 0
+
+telling me ip_forwarding is not on to switch it on I can do::
+
+ echo 1 > /proc/sys/net/ipv4/ip_forward
+
+cat it again::
+
+ cat /proc/sys/net/ipv4/ip_forward
+
+On my machine now outputs::
+
+ 1
+
IP forwarding is on.
+
There is a lot of useful info in here best found by going in and having a look
around, so I'll take you through some entries I consider important.
All the processes running on the machine have their own entry defined by
/proc/<pid>
-So lets have a look at the init process
-cd /proc/1
-cat cmdline
-emits
-init [2]
+So lets have a look at the init process::
+
+ cd /proc/1
+ cat cmdline
+
+emits::
+
+ init [2]
+
+::
+
+ cd /proc/1/fd
-cd /proc/1/fd
This contains numerical entries of all the open files,
-some of these you can cat e.g. stdout (2)
+some of these you can cat e.g. stdout (2)::
-cat /proc/29/maps
-on my machine emits
+ cat /proc/29/maps
-00400000-00478000 r-xp 00000000 5f:00 4103 /bin/bash
-00478000-0047e000 rw-p 00077000 5f:00 4103 /bin/bash
-0047e000-00492000 rwxp 00000000 00:00 0
-40000000-40015000 r-xp 00000000 5f:00 14382 /lib/ld-2.1.2.so
-40015000-40016000 rw-p 00014000 5f:00 14382 /lib/ld-2.1.2.so
-40016000-40017000 rwxp 00000000 00:00 0
-40017000-40018000 rw-p 00000000 00:00 0
-40018000-4001b000 r-xp 00000000 5f:00 14435 /lib/libtermcap.so.2.0.8
-4001b000-4001c000 rw-p 00002000 5f:00 14435 /lib/libtermcap.so.2.0.8
-4001c000-4010d000 r-xp 00000000 5f:00 14387 /lib/libc-2.1.2.so
-4010d000-40111000 rw-p 000f0000 5f:00 14387 /lib/libc-2.1.2.so
-40111000-40114000 rw-p 00000000 00:00 0
-40114000-4011e000 r-xp 00000000 5f:00 14408 /lib/libnss_files-2.1.2.so
-4011e000-4011f000 rw-p 00009000 5f:00 14408 /lib/libnss_files-2.1.2.so
-7fffd000-80000000 rwxp ffffe000 00:00 0
+on my machine emits::
+
+ 00400000-00478000 r-xp 00000000 5f:00 4103 /bin/bash
+ 00478000-0047e000 rw-p 00077000 5f:00 4103 /bin/bash
+ 0047e000-00492000 rwxp 00000000 00:00 0
+ 40000000-40015000 r-xp 00000000 5f:00 14382 /lib/ld-2.1.2.so
+ 40015000-40016000 rw-p 00014000 5f:00 14382 /lib/ld-2.1.2.so
+ 40016000-40017000 rwxp 00000000 00:00 0
+ 40017000-40018000 rw-p 00000000 00:00 0
+ 40018000-4001b000 r-xp 00000000 5f:00 14435 /lib/libtermcap.so.2.0.8
+ 4001b000-4001c000 rw-p 00002000 5f:00 14435 /lib/libtermcap.so.2.0.8
+ 4001c000-4010d000 r-xp 00000000 5f:00 14387 /lib/libc-2.1.2.so
+ 4010d000-40111000 rw-p 000f0000 5f:00 14387 /lib/libc-2.1.2.so
+ 40111000-40114000 rw-p 00000000 00:00 0
+ 40114000-4011e000 r-xp 00000000 5f:00 14408 /lib/libnss_files-2.1.2.so
+ 4011e000-4011f000 rw-p 00009000 5f:00 14408 /lib/libnss_files-2.1.2.so
+ 7fffd000-80000000 rwxp ffffe000 00:00 0
Showing us the shared libraries init uses where they are in memory
& memory access permissions for each virtual memory area.
/proc/1/cwd is a softlink to the current working directory.
-/proc/1/root is the root of the filesystem for this process.
+
+/proc/1/root is the root of the filesystem for this process.
/proc/1/mem is the current running processes memory which you
can read & write to like a file.
+
strace uses this sometimes as it is a bit faster than the
rather inefficient ptrace interface for peeking at DATA.
+::
-cat status
+ cat status
-Name: init
-State: S (sleeping)
-Pid: 1
-PPid: 0
-Uid: 0 0 0 0
-Gid: 0 0 0 0
-Groups:
-VmSize: 408 kB
-VmLck: 0 kB
-VmRSS: 208 kB
-VmData: 24 kB
-VmStk: 8 kB
-VmExe: 368 kB
-VmLib: 0 kB
-SigPnd: 0000000000000000
-SigBlk: 0000000000000000
-SigIgn: 7fffffffd7f0d8fc
-SigCgt: 00000000280b2603
-CapInh: 00000000fffffeff
-CapPrm: 00000000ffffffff
-CapEff: 00000000fffffeff
+ Name: init
+ State: S (sleeping)
+ Pid: 1
+ PPid: 0
+ Uid: 0 0 0 0
+ Gid: 0 0 0 0
+ Groups:
+ VmSize: 408 kB
+ VmLck: 0 kB
+ VmRSS: 208 kB
+ VmData: 24 kB
+ VmStk: 8 kB
+ VmExe: 368 kB
+ VmLib: 0 kB
+ SigPnd: 0000000000000000
+ SigBlk: 0000000000000000
+ SigIgn: 7fffffffd7f0d8fc
+ SigCgt: 00000000280b2603
+ CapInh: 00000000fffffeff
+ CapPrm: 00000000ffffffff
+ CapEff: 00000000fffffeff
+
+ User PSW: 070de000 80414146
+ task: 004b6000 tss: 004b62d8 ksp: 004b7ca8 pt_regs: 004b7f68
+ User GPRS:
+ 00000400 00000000 0000000b 7ffffa90
+ 00000000 00000000 00000000 0045d9f4
+ 0045cafc 7ffffa90 7fffff18 0045cb08
+ 00010400 804039e8 80403af8 7ffff8b0
+ User ACRS:
+ 00000000 00000000 00000000 00000000
+ 00000001 00000000 00000000 00000000
+ 00000000 00000000 00000000 00000000
+ 00000000 00000000 00000000 00000000
+ Kernel BackChain CallChain BackChain CallChain
+ 004b7ca8 8002bd0c 004b7d18 8002b92c
+ 004b7db8 8005cd50 004b7e38 8005d12a
+ 004b7f08 80019114
-User PSW: 070de000 80414146
-task: 004b6000 tss: 004b62d8 ksp: 004b7ca8 pt_regs: 004b7f68
-User GPRS:
-00000400 00000000 0000000b 7ffffa90
-00000000 00000000 00000000 0045d9f4
-0045cafc 7ffffa90 7fffff18 0045cb08
-00010400 804039e8 80403af8 7ffff8b0
-User ACRS:
-00000000 00000000 00000000 00000000
-00000001 00000000 00000000 00000000
-00000000 00000000 00000000 00000000
-00000000 00000000 00000000 00000000
-Kernel BackChain CallChain BackChain CallChain
- 004b7ca8 8002bd0c 004b7d18 8002b92c
- 004b7db8 8005cd50 004b7e38 8005d12a
- 004b7f08 80019114
Showing among other things memory usage & status of some signals &
the processes'es registers from the kernel task_structure
as well as a backchain which may be useful if a process crashes
@@ -2067,11 +2473,16 @@ debug feature
Some of our drivers now support a "debug feature" in
/proc/s390dbf see s390dbf.txt in the linux/Documentation directory
for more info.
-e.g.
-to switch on the lcs "debug feature"
-echo 5 > /proc/s390dbf/lcs/level
-& then after the error occurred.
-cat /proc/s390dbf/lcs/sprintf >/logfile
+
+e.g.
+to switch on the lcs "debug feature"::
+
+ echo 5 > /proc/s390dbf/lcs/level
+
+& then after the error occurred::
+
+ cat /proc/s390dbf/lcs/sprintf >/logfile
+
the logfile now contains some information which may help
tech support resolve a problem in the field.
@@ -2083,35 +2494,50 @@ ifconfig is a quite useful command
it gives the current state of network drivers.
If you suspect your network device driver is dead
-one way to check is type
-ifconfig <network device>
+one way to check is type::
+
+ ifconfig <network device>
+
e.g. tr0
-You should see something like
-tr0 Link encap:16/4 Mbps Token Ring (New) HWaddr 00:04:AC:20:8E:48
- inet addr:9.164.185.132 Bcast:9.164.191.255 Mask:255.255.224.0
- UP BROADCAST RUNNING MULTICAST MTU:2000 Metric:1
- RX packets:246134 errors:0 dropped:0 overruns:0 frame:0
- TX packets:5 errors:0 dropped:0 overruns:0 carrier:0
- collisions:0 txqueuelen:100
+
+You should see something like::
+
+ ifconfig tr0
+ tr0 Link encap:16/4 Mbps Token Ring (New) HWaddr 00:04:AC:20:8E:48
+ inet addr:9.164.185.132 Bcast:9.164.191.255 Mask:255.255.224.0
+ UP BROADCAST RUNNING MULTICAST MTU:2000 Metric:1
+ RX packets:246134 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:5 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:100
if the device doesn't say up
-try
-/etc/rc.d/init.d/network start
+try::
+
+ /etc/rc.d/init.d/network start
+
( this starts the network stack & hopefully calls ifconfig tr0 up ).
ifconfig looks at the output of /proc/net/dev and presents it in a more
presentable form.
+
Now ping the device from a machine in the same subnet.
+
if the RX packets count & TX packets counts don't increment you probably
have problems.
-next
-cat /proc/net/arp
+
+next::
+
+ cat /proc/net/arp
+
Do you see any hardware addresses in the cache if not you may have problems.
-Next try
-ping -c 5 <broadcast_addr> i.e. the Bcast field above in the output of
+Next try::
+
+ ping -c 5 <broadcast_addr>
+
+i.e. the Bcast field above in the output of
ifconfig. Do you see any replies from machines other than the local machine
if not you may have problems. also if the TX packets count in ifconfig
-hasn't incremented either you have serious problems in your driver
-(e.g. the txbusy field of the network device being stuck on )
+hasn't incremented either you have serious problems in your driver
+(e.g. the txbusy field of the network device being stuck on )
or you may have multiple network devices connected.
@@ -2119,28 +2545,43 @@ chandev
-------
There is a new device layer for channel devices, some
drivers e.g. lcs are registered with this layer.
+
If the device uses the channel device layer you'll be
-able to find what interrupts it uses & the current state
+able to find what interrupts it uses & the current state
of the device.
+
See the manpage chandev.8 &type cat /proc/chandev for more info.
SysRq
=====
This is now supported by linux for s/390 & z/Architecture.
-To enable it do compile the kernel with
-Kernel Hacking -> Magic SysRq Key Enabled
-echo "1" > /proc/sys/kernel/sysrq
-also type
-echo "8" >/proc/sys/kernel/printk
+
+To enable it do compile the kernel with::
+
+ Kernel Hacking -> Magic SysRq Key Enabled
+
+Then::
+
+ echo "1" > /proc/sys/kernel/sysrq
+
+also type::
+
+ echo "8" >/proc/sys/kernel/printk
+
To make printk output go to console.
-On 390 all commands are prefixed with
-^-
-e.g.
-^-t will show tasks.
-^-? or some unknown command will display help.
+
+On 390 all commands are prefixed with::
+
+ ^-
+
+e.g.::
+
+ ^-t will show tasks.
+ ^-? or some unknown command will display help.
+
The sysrq key reading is very picky ( I have to type the keys in an
- xterm session & paste them into the x3270 console )
+xterm session & paste them into the x3270 console )
& it may be wise to predefine the keys as described in the VM hints above
This is particularly useful for syncing disks unmounting & rebooting
@@ -2150,19 +2591,19 @@ Read Documentation/admin-guide/sysrq.rst for more info
References:
===========
-Enterprise Systems Architecture Reference Summary
-Enterprise Systems Architecture Principles of Operation
-Hartmut Penners s390 stack frame sheet.
-IBM Mainframe Channel Attachment a technology brief from a CISCO webpage
-Various bits of man & info pages of Linux.
-Linux & GDB source.
-Various info & man pages.
-CMS Help on tracing commands.
-Linux for s/390 Elf Application Binary Interface
-Linux for z/Series Elf Application Binary Interface ( Both Highly Recommended )
-z/Architecture Principles of Operation SA22-7832-00
-Enterprise Systems Architecture/390 Reference Summary SA22-7209-01 & the
-Enterprise Systems Architecture/390 Principles of Operation SA22-7201-05
+- Enterprise Systems Architecture Reference Summary
+- Enterprise Systems Architecture Principles of Operation
+- Hartmut Penners s390 stack frame sheet.
+- IBM Mainframe Channel Attachment a technology brief from a CISCO webpage
+- Various bits of man & info pages of Linux.
+- Linux & GDB source.
+- Various info & man pages.
+- CMS Help on tracing commands.
+- Linux for s/390 Elf Application Binary Interface
+- Linux for z/Series Elf Application Binary Interface ( Both Highly Recommended )
+- z/Architecture Principles of Operation SA22-7832-00
+- Enterprise Systems Architecture/390 Reference Summary SA22-7209-01 & the
+- Enterprise Systems Architecture/390 Principles of Operation SA22-7201-05
Special Thanks
==============
diff --git a/Documentation/s390/driver-model.txt b/Documentation/s390/driver-model.rst
similarity index 73%
rename from Documentation/s390/driver-model.txt
rename to Documentation/s390/driver-model.rst
index ed265cf54cde..ad4bc2dbea43 100644
--- a/Documentation/s390/driver-model.txt
+++ b/Documentation/s390/driver-model.rst
@@ -1,5 +1,6 @@
+=============================
S/390 driver model interfaces
------------------------------
+=============================
1. CCW devices
--------------
@@ -7,13 +8,13 @@ S/390 driver model interfaces
All devices which can be addressed by means of ccws are called 'CCW devices' -
even if they aren't actually driven by ccws.
-All ccw devices are accessed via a subchannel, this is reflected in the
-structures under devices/:
+All ccw devices are accessed via a subchannel, this is reflected in the
+structures under devices/::
-devices/
+ devices/
- system/
- css0/
- - 0.0.0000/0.0.0815/
+ - 0.0.0000/0.0.0815/
- 0.0.0001/0.0.4711/
- 0.0.0002/
- 0.1.0000/0.1.1234/
@@ -35,14 +36,18 @@ be found under bus/ccw/devices/.
All ccw devices export some data via sysfs.
-cutype: The control unit type / model.
+cutype:
+ The control unit type / model.
-devtype: The device type / model, if applicable.
+devtype:
+ The device type / model, if applicable.
-availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for
+availability:
+ Can be 'good' or 'boxed'; 'no path' or 'no device' for
disconnected devices.
-online: An interface to set the device online and offline.
+online:
+ An interface to set the device online and offline.
In the special case of the device being disconnected (see the
notify function under 1.2), piping 0 to online will forcibly delete
the device.
@@ -52,9 +57,11 @@ The device drivers can add entries to export per-device data and interfaces.
There is also some data exported on a per-subchannel basis (see under
bus/css/devices/):
-chpids: Via which chpids the device is connected.
+chpids:
+ Via which chpids the device is connected.
-pimpampom: The path installed, path available and path operational masks.
+pimpampom:
+ The path installed, path available and path operational masks.
There also might be additional data, for example for block devices.
@@ -74,77 +81,93 @@ b. After a. has been performed, if necessary, the device is finally brought up
------------------------------------
The basic struct ccw_device and struct ccw_driver data structures can be found
-under include/asm/ccwdev.h.
+under include/asm/ccwdev.h::
-struct ccw_device {
- spinlock_t *ccwlock;
- struct ccw_device_private *private;
- struct ccw_device_id id;
+ struct ccw_device {
+ spinlock_t *ccwlock;
+ struct ccw_device_private *private;
+ struct ccw_device_id id;
- struct ccw_driver *drv;
- struct device dev;
+ struct ccw_driver *drv;
+ struct device dev;
int online;
void (*handler) (struct ccw_device *dev, unsigned long intparm,
- struct irb *irb);
-};
+ struct irb *irb);
+ };
-struct ccw_driver {
- struct module *owner;
- struct ccw_device_id *ids;
- int (*probe) (struct ccw_device *);
+ struct ccw_driver {
+ struct module *owner;
+ struct ccw_device_id *ids;
+ int (*probe) (struct ccw_device *);
int (*remove) (struct ccw_device *);
int (*set_online) (struct ccw_device *);
int (*set_offline) (struct ccw_device *);
int (*notify) (struct ccw_device *, int);
struct device_driver driver;
char *name;
-};
+ };
The 'private' field contains data needed for internal i/o operation only, and
is not available to the device driver.
Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
and/or device types/models it is interested. This information can later be found
-in the struct ccw_device_id fields:
+in the struct ccw_device_id fields::
-struct ccw_device_id {
- __u16 match_flags;
+ struct ccw_device_id {
+ __u16 match_flags;
- __u16 cu_type;
- __u16 dev_type;
- __u8 cu_model;
- __u8 dev_model;
+ __u16 cu_type;
+ __u16 dev_type;
+ __u8 cu_model;
+ __u8 dev_model;
unsigned long driver_info;
-};
+ };
The functions in ccw_driver should be used in the following way:
-probe: This function is called by the device layer for each device the driver
+
+probe:
+ This function is called by the device layer for each device the driver
is interested in. The driver should only allocate private structures
to put in dev->driver_data and create attributes (if needed). Also,
the interrupt handler (see below) should be set here.
-int (*probe) (struct ccw_device *cdev);
+::
-Parameters: cdev - the device to be probed.
+ int (*probe) (struct ccw_device *cdev);
+Parameters:
+ cdev
+ - the device to be probed.
-remove: This function is called by the device layer upon removal of the driver,
+
+remove:
+ This function is called by the device layer upon removal of the driver,
the device or the module. The driver should perform cleanups here.
-int (*remove) (struct ccw_device *cdev);
+::
-Parameters: cdev - the device to be removed.
+ int (*remove) (struct ccw_device *cdev);
+Parameters:
+ cdev
+ - the device to be removed.
-set_online: This function is called by the common I/O layer when the device is
+
+set_online:
+ This function is called by the common I/O layer when the device is
activated via the 'online' attribute. The driver should finally
setup and activate the device here.
-int (*set_online) (struct ccw_device *);
+::
-Parameters: cdev - the device to be activated. The common layer has
+ int (*set_online) (struct ccw_device *);
+
+Parameters:
+ cdev
+ - the device to be activated. The common layer has
verified that the device is not already online.
@@ -152,15 +175,22 @@ set_offline: This function is called by the common I/O layer when the device is
de-activated via the 'online' attribute. The driver should shut
down the device, but not de-allocate its private data.
-int (*set_offline) (struct ccw_device *);
+::
-Parameters: cdev - the device to be deactivated. The common layer has
+ int (*set_offline) (struct ccw_device *);
+
+Parameters:
+ cdev
+ - the device to be deactivated. The common layer has
verified that the device is online.
-notify: This function is called by the common I/O layer for some state changes
+notify:
+ This function is called by the common I/O layer for some state changes
of the device.
+
Signalled to the driver are:
+
* In online state, device detached (CIO_GONE) or last path gone
(CIO_NO_PATH). The driver must return !0 to keep the device; for
return code 0, the device will be deleted as usual (also when no
@@ -173,32 +203,40 @@ notify: This function is called by the common I/O layer for some state changes
return code of the notify function the device driver signals if it
wants the device back: !0 for keeping, 0 to make the device being
removed and re-registered.
-
-int (*notify) (struct ccw_device *, int);
-Parameters: cdev - the device whose state changed.
- event - the event that happened. This can be one of CIO_GONE,
- CIO_NO_PATH or CIO_OPER.
+::
+
+ int (*notify) (struct ccw_device *, int);
+
+Parameters:
+ cdev
+ - the device whose state changed.
+
+ event
+ - the event that happened. This can be one of CIO_GONE,
+ CIO_NO_PATH or CIO_OPER.
The handler field of the struct ccw_device is meant to be set to the interrupt
-handler for the device. In order to accommodate drivers which use several
+handler for the device. In order to accommodate drivers which use several
distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
instead of ccw_driver.
The handler is registered with the common layer during set_online() processing
before the driver is called, and is deregistered during set_offline() after the
-driver has been called. Also, after registering / before deregistering, path
+driver has been called. Also, after registering / before deregistering, path
grouping resp. disbanding of the path group (if applicable) are performed.
-void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
+::
-Parameters: dev - the device the handler is called for
+ void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
+
+Parameters: dev - the device the handler is called for
intparm - the intparm which allows the device driver to identify
- the i/o the interrupt is associated with, or to recognize
- the interrupt as unsolicited.
- irb - interruption response block which contains the accumulated
- status.
+ the i/o the interrupt is associated with, or to recognize
+ the interrupt as unsolicited.
+ irb - interruption response block which contains the accumulated
+ status.
-The device driver is called from the common ccw_device layer and can retrieve
+The device driver is called from the common ccw_device layer and can retrieve
information about the interrupt from the irb parameter.
@@ -237,23 +275,27 @@ only the logical state and not the physical state, since we cannot track the
latter consistently due to lacking machine support (we don't need to be aware
of it anyway).
-status - Can be 'online' or 'offline'.
+status
+ - Can be 'online' or 'offline'.
Piping 'on' or 'off' sets the chpid logically online/offline.
Piping 'on' to an online chpid triggers path reprobing for all devices
the chpid connects to. This can be used to force the kernel to re-use
a channel path the user knows to be online, but the machine hasn't
created a machine check for.
-type - The physical type of the channel path.
+type
+ - The physical type of the channel path.
-shared - Whether the channel path is shared.
+shared
+ - Whether the channel path is shared.
-cmg - The channel measurement group.
+cmg
+ - The channel measurement group.
3. System devices
-----------------
-3.1 xpram
+3.1 xpram
---------
xpram shows up under devices/system/ as 'xpram'.
@@ -279,9 +321,8 @@ Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interfa
number is assigned sequentially to the connections defined via the 'connection'
attribute.
-user - shows the connection partner.
-
-buffer - maximum buffer size.
- Pipe to it to change buffer size.
-
+user
+ - shows the connection partner.
+buffer
+ - maximum buffer size. Pipe to it to change buffer size.
diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst
new file mode 100644
index 000000000000..1a914da2a07b
--- /dev/null
+++ b/Documentation/s390/index.rst
@@ -0,0 +1,30 @@
+:orphan:
+
+=================
+s390 Architecture
+=================
+
+.. toctree::
+ :maxdepth: 1
+
+ cds
+ 3270
+ debugging390
+ driver-model
+ monreader
+ qeth
+ s390dbf
+ vfio-ap
+ vfio-ccw
+ zfcpdump
+ dasd
+ common_io
+
+ text_files
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/s390/monreader.txt b/Documentation/s390/monreader.rst
similarity index 81%
rename from Documentation/s390/monreader.txt
rename to Documentation/s390/monreader.rst
index d3729585fdb0..1e857575c113 100644
--- a/Documentation/s390/monreader.txt
+++ b/Documentation/s390/monreader.rst
@@ -1,24 +1,26 @@
+=================================================
+Linux API for read access to z/VM Monitor Records
+=================================================
Date : 2004-Nov-26
+
Author: Gerald Schaefer ([email protected])
- Linux API for read access to z/VM Monitor Records
- =================================================
Description
===========
This item delivers a new Linux API in the form of a misc char device that is
usable from user space and allows read access to the z/VM Monitor Records
-collected by the *MONITOR System Service of z/VM.
+collected by the `*MONITOR` System Service of z/VM.
User Requirements
=================
The z/VM guest on which you want to access this API needs to be configured in
-order to allow IUCV connections to the *MONITOR service, i.e. it needs the
-IUCV *MONITOR statement in its user entry. If the monitor DCSS to be used is
+order to allow IUCV connections to the `*MONITOR` service, i.e. it needs the
+IUCV `*MONITOR` statement in its user entry. If the monitor DCSS to be used is
restricted (likely), you also need the NAMESAVE <DCSS NAME> statement.
This item will use the IUCV device driver to access the z/VM services, so you
need a kernel with IUCV support. You also need z/VM version 4.4 or 5.1.
@@ -50,7 +52,9 @@ Your guest virtual storage has to end below the starting address of the DCSS
and you have to specify the "mem=" kernel parameter in your parmfile with a
value greater than the ending address of the DCSS.
-Example: DEF STOR 140M
+Example::
+
+ DEF STOR 140M
This defines 140MB storage size for your guest, the parameter "mem=160M" is
added to the parmfile.
@@ -66,24 +70,27 @@ kernel, the kernel parameter "monreader.mondcss=<DCSS NAME>" can be specified
in the parmfile.
The default name for the DCSS is "MONDCSS" if none is specified. In case that
-there are other users already connected to the *MONITOR service (e.g.
+there are other users already connected to the `*MONITOR` service (e.g.
Performance Toolkit), the monitor DCSS is already defined and you have to use
the same DCSS. The CP command Q MONITOR (Class E privileged) shows the name
of the monitor DCSS, if already defined, and the users connected to the
-*MONITOR service.
+`*MONITOR` service.
Refer to the "z/VM Performance" book (SC24-6109-00) on how to create a monitor
DCSS if your z/VM doesn't have one already, you need Class E privileges to
define and save a DCSS.
Example:
--------
-modprobe monreader mondcss=MYDCSS
+
+::
+
+ modprobe monreader mondcss=MYDCSS
This loads the module and sets the DCSS name to "MYDCSS".
NOTE:
-----
-This API provides no interface to control the *MONITOR service, e.g. specify
+This API provides no interface to control the `*MONITOR` service, e.g. specify
which data should be collected. This can be done by the CP command MONITOR
(Class E privileged), see "CP Command and Utility Reference".
@@ -98,6 +105,7 @@ If your distribution does not support udev, a device node will not be created
automatically and you have to create it manually after loading the module.
Therefore you need to know the major and minor numbers of the device. These
numbers can be found in /sys/class/misc/monreader/dev.
+
Typing cat /sys/class/misc/monreader/dev will give an output of the form
<major>:<minor>. The device node can be created via the mknod command, enter
mknod <name> c <major> <minor>, where <name> is the name of the device node
@@ -105,10 +113,13 @@ to be created.
Example:
--------
-# modprobe monreader
-# cat /sys/class/misc/monreader/dev
-10:63
-# mknod /dev/monreader c 10 63
+
+::
+
+ # modprobe monreader
+ # cat /sys/class/misc/monreader/dev
+ 10:63
+ # mknod /dev/monreader c 10 63
This loads the module with the default monitor DCSS (MONDCSS) and creates a
device node.
@@ -133,20 +144,21 @@ last byte of data. The start address is needed to handle "end-of-frame" records
correctly (domain 1, record 13), i.e. it can be used to determine the record
start offset relative to a 4K page (frame) boundary.
-See "Appendix A: *MONITOR" in the "z/VM Performance" document for a description
+See "Appendix A: `*MONITOR`" in the "z/VM Performance" document for a description
of the monitor control element layout. The layout of the monitor records can
be found here (z/VM 5.1): http://www.vm.ibm.com/pubs/mon510/index.html
-The layout of the data stream provided by the monreader device is as follows:
-...
-<0 byte read>
-<first MCE> \
-<first set of records> |
-... |- data set
-<last MCE> |
-<last set of records> /
-<0 byte read>
-...
+The layout of the data stream provided by the monreader device is as follows::
+
+ ...
+ <0 byte read>
+ <first MCE> \
+ <first set of records> |
+ ... |- data set
+ <last MCE> |
+ <last set of records> /
+ <0 byte read>
+ ...
There may be more than one combination of MCE and corresponding record set
within one data set and the end of each data set is indicated by a successful
@@ -165,15 +177,19 @@ As with most char devices, error conditions are indicated by returning a
negative value for the number of bytes read. In this case, the errno variable
indicates the error condition:
-EIO: reply failed, read data is invalid and the application
+EIO:
+ reply failed, read data is invalid and the application
should discard the data read since the last successful read with 0 size.
-EFAULT: copy_to_user failed, read data is invalid and the application should
- discard the data read since the last successful read with 0 size.
-EAGAIN: occurs on a non-blocking read if there is no data available at the
- moment. There is no data missing or corrupted, just try again or rather
- use polling for non-blocking reads.
-EOVERFLOW: message limit reached, the data read since the last successful
- read with 0 size is valid but subsequent records may be missing.
+EFAULT:
+ copy_to_user failed, read data is invalid and the application should
+ discard the data read since the last successful read with 0 size.
+EAGAIN:
+ occurs on a non-blocking read if there is no data available at the
+ moment. There is no data missing or corrupted, just try again or rather
+ use polling for non-blocking reads.
+EOVERFLOW:
+ message limit reached, the data read since the last successful
+ read with 0 size is valid but subsequent records may be missing.
In the last case (EOVERFLOW) there may be missing data, in the first two cases
(EIO, EFAULT) there will be missing data. It's up to the application if it will
@@ -183,7 +199,7 @@ Open:
-----
Only one user is allowed to open the char device. If it is already in use, the
open function will fail (return a negative value) and set errno to EBUSY.
-The open function may also fail if an IUCV connection to the *MONITOR service
+The open function may also fail if an IUCV connection to the `*MONITOR` service
cannot be established. In this case errno will be set to EIO and an error
message with an IPUSER SEVER code will be printed into syslog. The IPUSER SEVER
codes are described in the "z/VM Performance" book, Appendix A.
@@ -194,4 +210,3 @@ As soon as the device is opened, incoming messages will be accepted and they
will account for the message limit, i.e. opening the device without reading
from it will provoke the "message limit reached" error (EOVERFLOW error code)
eventually.
-
diff --git a/Documentation/s390/qeth.txt b/Documentation/s390/qeth.rst
similarity index 62%
rename from Documentation/s390/qeth.txt
rename to Documentation/s390/qeth.rst
index aa06fcf5f8c2..f02fdaa68de0 100644
--- a/Documentation/s390/qeth.txt
+++ b/Documentation/s390/qeth.rst
@@ -1,8 +1,12 @@
+=============================
IBM s390 QDIO Ethernet Driver
+=============================
OSA and HiperSockets Bridge Port Support
+========================================
Uevents
+-------
To generate the events the device must be assigned a role of either
a primary or a secondary Bridge Port. For more information, see
@@ -13,12 +17,15 @@ of some configured Bridge Port device on the channel changes, a udev
event with ACTION=CHANGE is emitted on behalf of the corresponding
ccwgroup device. The event has the following attributes:
-BRIDGEPORT=statechange - indicates that the Bridge Port device changed
+BRIDGEPORT=statechange
+ indicates that the Bridge Port device changed
its state.
-ROLE={primary|secondary|none} - the role assigned to the port.
+ROLE={primary|secondary|none}
+ the role assigned to the port.
-STATE={active|standby|inactive} - the newly assumed state of the port.
+STATE={active|standby|inactive}
+ the newly assumed state of the port.
When run on HiperSockets Bridge Capable Port hardware with host address
notifications enabled, a udev event with ACTION=CHANGE is emitted.
@@ -26,25 +33,32 @@ It is emitted on behalf of the corresponding ccwgroup device when a host
or a VLAN is registered or unregistered on the network served by the device.
The event has the following attributes:
-BRIDGEDHOST={reset|register|deregister|abort} - host address
+BRIDGEDHOST={reset|register|deregister|abort}
+ host address
notifications are started afresh, a new host or VLAN is registered or
deregistered on the Bridge Port HiperSockets channel, or address
notifications are aborted.
-VLAN=numeric-vlan-id - VLAN ID on which the event occurred. Not included
+VLAN=numeric-vlan-id
+ VLAN ID on which the event occurred. Not included
if no VLAN is involved in the event.
-MAC=xx:xx:xx:xx:xx:xx - MAC address of the host that is being registered
+MAC=xx:xx:xx:xx:xx:xx
+ MAC address of the host that is being registered
or deregistered from the HiperSockets channel. Not reported if the
event reports the creation or destruction of a VLAN.
-NTOK_BUSID=x.y.zzzz - device bus ID (CSSID, SSID and device number).
+NTOK_BUSID=x.y.zzzz
+ device bus ID (CSSID, SSID and device number).
-NTOK_IID=xx - device IID.
+NTOK_IID=xx
+ device IID.
-NTOK_CHPID=xx - device CHPID.
+NTOK_CHPID=xx
+ device CHPID.
-NTOK_CHID=xxxx - device channel ID.
+NTOK_CHID=xxxx
+ device channel ID.
-Note that the NTOK_* attributes refer to devices other than the one
+Note that the `NTOK_*` attributes refer to devices other than the one
connected to the system on which the OS is running.
diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.rst
similarity index 43%
rename from Documentation/s390/s390dbf.txt
rename to Documentation/s390/s390dbf.rst
index 61329fd62e89..ec2a1faa414b 100644
--- a/Documentation/s390/s390dbf.txt
+++ b/Documentation/s390/s390dbf.rst
@@ -1,34 +1,38 @@
+==================
S390 Debug Feature
==================
-files: arch/s390/kernel/debug.c
- arch/s390/include/asm/debug.h
+files:
+ - arch/s390/kernel/debug.c
+ - arch/s390/include/asm/debug.h
Description:
------------
-The goal of this feature is to provide a kernel debug logging API
-where log records can be stored efficiently in memory, where each component
+The goal of this feature is to provide a kernel debug logging API
+where log records can be stored efficiently in memory, where each component
(e.g. device drivers) can have one separate debug log.
One purpose of this is to inspect the debug logs after a production system crash
in order to analyze the reason for the crash.
+
If the system still runs but only a subcomponent which uses dbf fails,
it is possible to look at the debug logs on a live system via the Linux
debugfs filesystem.
+
The debug feature may also very useful for kernel and driver development.
Design:
-------
-Kernel components (e.g. device drivers) can register themselves at the debug
-feature with the function call debug_register(). This function initializes a
-debug log for the caller. For each debug log exists a number of debug areas
+Kernel components (e.g. device drivers) can register themselves at the debug
+feature with the function call debug_register(). This function initializes a
+debug log for the caller. For each debug log exists a number of debug areas
where exactly one is active at one time. Each debug area consists of contiguous
pages in memory. In the debug areas there are stored debug entries (log records)
-which are written by event- and exception-calls.
+which are written by event- and exception-calls.
An event-call writes the specified debug entry to the active debug
-area and updates the log pointer for the active area. If the end
-of the active debug area is reached, a wrap around is done (ring buffer)
-and the next debug entry will be written at the beginning of the active
+area and updates the log pointer for the active area. If the end
+of the active debug area is reached, a wrap around is done (ring buffer)
+and the next debug entry will be written at the beginning of the active
debug area.
An exception-call writes the specified debug entry to the log and
@@ -37,7 +41,7 @@ that the records which describe the origin of the exception are not
overwritten when a wrap around for the current area occurs.
The debug areas themselves are also ordered in form of a ring buffer.
-When an exception is thrown in the last debug area, the following debug
+When an exception is thrown in the last debug area, the following debug
entries are then written again in the very first area.
There are three versions for the event- and exception-calls: One for
@@ -76,244 +80,359 @@ through writing a number string "x" to the 'level' debugfs file which is
provided for every debug log. Debugging can be switched off completely
by using "-" on the 'level' debugfs file.
-Example:
+Example::
-> echo "-" > /sys/kernel/debug/s390dbf/dasd/level
+ > echo "-" > /sys/kernel/debug/s390dbf/dasd/level
It is also possible to deactivate the debug feature globally for every
debug log. You can change the behavior using 2 sysctl parameters in
/proc/sys/s390dbf:
+
There are currently 2 possible triggers, which stop the debug feature
globally. The first possibility is to use the "debug_active" sysctl. If
set to 1 the debug feature is running. If "debug_active" is set to 0 the
debug feature is turned off.
+
The second trigger which stops the debug feature is a kernel oops.
That prevents the debug feature from overwriting debug information that
happened before the oops. After an oops you can reactivate the debug feature
by piping 1 to /proc/sys/s390dbf/debug_active. Nevertheless, its not
suggested to use an oopsed kernel in a production environment.
+
If you want to disallow the deactivation of the debug feature, you can use
the "debug_stoppable" sysctl. If you set "debug_stoppable" to 0 the debug
feature cannot be stopped. If the debug feature is already stopped, it
will stay deactivated.
+----------------------------------------------------------------------------
+
Kernel Interfaces:
------------------
-----------------------------------------------------------------------------
-debug_info_t *debug_register(char *name, int pages, int nr_areas,
- int buf_size);
+::
-Parameter: name: Name of debug log (e.g. used for debugfs entry)
- pages: number of pages, which will be allocated per area
- nr_areas: number of debug areas
- buf_size: size of data area in each debug entry
+ debug_info_t *debug_register(char *name, int pages, int nr_areas,
+ int buf_size);
-Return Value: Handle for generated debug area
- NULL if register failed
+Parameter:
+ name:
+ Name of debug log (e.g. used for debugfs entry)
+ pages:
+ Number of pages, which will be allocated per area
+ nr_areas:
+ Number of debug areas
+ buf_size:
+ Size of data area in each debug entry
-Description: Allocates memory for a debug log
- Must not be called within an interrupt handler
+Return Value:
+ Handle for generated debug area
-----------------------------------------------------------------------------
-debug_info_t *debug_register_mode(char *name, int pages, int nr_areas,
- int buf_size, mode_t mode, uid_t uid,
- gid_t gid);
-
-Parameter: name: Name of debug log (e.g. used for debugfs entry)
- pages: Number of pages, which will be allocated per area
- nr_areas: Number of debug areas
- buf_size: Size of data area in each debug entry
- mode: File mode for debugfs files. E.g. S_IRWXUGO
- uid: User ID for debugfs files. Currently only 0 is
- supported.
- gid: Group ID for debugfs files. Currently only 0 is
- supported.
-
-Return Value: Handle for generated debug area
- NULL if register failed
+ NULL if register failed
Description: Allocates memory for a debug log
Must not be called within an interrupt handler
+----------------------------------------------------------------------------
+
+::
+
+ debug_info_t *debug_register_mode(char *name, int pages, int nr_areas,
+ int buf_size, mode_t mode, uid_t uid,
+ gid_t gid);
+
+Parameter:
+ name:
+ Name of debug log (e.g. used for debugfs entry)
+ pages:
+ Number of pages, which will be allocated per area
+ nr_areas:
+ Number of debug areas
+ buf_size:
+ Size of data area in each debug entry
+ mode:
+ File mode for debugfs files. E.g. S_IRWXUGO
+ uid:
+ User ID for debugfs files. Currently only 0 is
+ supported.
+ gid:
+ Group ID for debugfs files. Currently only 0 is
+ supported.
+
+Return Value:
+ Handle for generated debug area
+
+ NULL if register failed
+
+Description:
+ Allocates memory for a debug log
+ Must not be called within an interrupt handler
+
---------------------------------------------------------------------------
-void debug_unregister (debug_info_t * id);
-Parameter: id: handle for debug log
+::
-Return Value: none
+ void debug_unregister (debug_info_t * id);
-Description: frees memory for a debug log and removes all registered debug
+Parameter:
+ id:
+ handle for debug log
+
+Return Value:
+ none
+
+Description:
+ frees memory for a debug log and removes all registered debug
views.
- Must not be called within an interrupt handler
+
+ Must not be called within an interrupt handler
---------------------------------------------------------------------------
-void debug_set_level (debug_info_t * id, int new_level);
-Parameter: id: handle for debug log
- new_level: new debug level
+::
+
+ void debug_set_level (debug_info_t * id, int new_level);
+
+Parameter: id: handle for debug log
+ new_level: new debug level
-Return Value: none
+Return Value:
+ none
-Description: Sets new actual debug level if new_level is valid.
+Description:
+ Sets new actual debug level if new_level is valid.
---------------------------------------------------------------------------
-bool debug_level_enabled (debug_info_t * id, int level);
-Parameter: id: handle for debug log
- level: debug level
+::
+
+ bool debug_level_enabled (debug_info_t * id, int level);
+
+Parameter:
+ id:
+ handle for debug log
+ level:
+ debug level
-Return Value: True if level is less or equal to the current debug level.
+Return Value:
+ True if level is less or equal to the current debug level.
-Description: Returns true if debug events for the specified level would be
+Description:
+ Returns true if debug events for the specified level would be
logged. Otherwise returns false.
+
---------------------------------------------------------------------------
-void debug_stop_all(void);
-Parameter: none
+::
+
+ void debug_stop_all(void);
+
+Parameter:
+ none
-Return Value: none
+Return Value:
+ none
-Description: stops the debug feature if stopping is allowed. Currently
- used in case of a kernel oops.
+Description:
+ stops the debug feature if stopping is allowed. Currently
+ used in case of a kernel oops.
---------------------------------------------------------------------------
-debug_entry_t* debug_event (debug_info_t* id, int level, void* data,
- int length);
-Parameter: id: handle for debug log
- level: debug level
- data: pointer to data for debug entry
- length: length of data in bytes
+::
-Return Value: Address of written debug entry
+ debug_entry_t* debug_event (debug_info_t* id, int level, void* data,
+ int length);
-Description: writes debug entry to active debug area (if level <= actual
- debug level)
+Parameter:
+ id:
+ handle for debug log
+ level:
+ debug level
+ data:
+ pointer to data for debug entry
+ length:
+ length of data in bytes
+
+Return Value:
+ Address of written debug entry
+
+Description:
+ writes debug entry to active debug area (if level <= actual
+ debug level)
---------------------------------------------------------------------------
-debug_entry_t* debug_int_event (debug_info_t * id, int level,
- unsigned int data);
-debug_entry_t* debug_long_event(debug_info_t * id, int level,
- unsigned long data);
-Parameter: id: handle for debug log
- level: debug level
- data: integer value for debug entry
+::
+
+ debug_entry_t* debug_int_event (debug_info_t * id, int level,
+ unsigned int data);
+ debug_entry_t* debug_long_event(debug_info_t * id, int level,
+ unsigned long data);
-Return Value: Address of written debug entry
+Parameter:
+ id:
+ handle for debug log
+ level:
+ debug level
+ data:
+ integer value for debug entry
-Description: writes debug entry to active debug area (if level <= actual
- debug level)
+Return Value:
+ Address of written debug entry
+
+Description:
+ writes debug entry to active debug area (if level <= actual
+ debug level)
---------------------------------------------------------------------------
-debug_entry_t* debug_text_event (debug_info_t * id, int level,
- const char* data);
-Parameter: id: handle for debug log
- level: debug level
- data: string for debug entry
+::
+
+ debug_entry_t* debug_text_event (debug_info_t * id, int level,
+ const char* data);
+
+Parameter:
+ id:
+ handle for debug log
+ level:
+ debug level
+ data:
+ string for debug entry
-Return Value: Address of written debug entry
+Return Value:
+ Address of written debug entry
-Description: writes debug entry in ascii format to active debug area
- (if level <= actual debug level)
+Description:
+ writes debug entry in ascii format to active debug area
+ (if level <= actual debug level)
---------------------------------------------------------------------------
-debug_entry_t* debug_sprintf_event (debug_info_t * id, int level,
- char* string,...);
-Parameter: id: handle for debug log
- level: debug level
- string: format string for debug entry
- ...: varargs used as in sprintf()
+::
+
+ debug_entry_t* debug_sprintf_event (debug_info_t * id, int level,
+ char* string,...);
+
+Parameter:
+ id:
+ handle for debug log
+ level:
+ debug level
+ string:
+ format string for debug entry
+ ...:
+ varargs used as in sprintf()
Return Value: Address of written debug entry
-Description: writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level).
- floats and long long datatypes cannot be used as varargs.
+Description:
+ writes debug entry with format string and varargs (longs) to
+ active debug area (if level $<=$ actual debug level).
+ floats and long long datatypes cannot be used as varargs.
---------------------------------------------------------------------------
-debug_entry_t* debug_exception (debug_info_t* id, int level, void* data,
- int length);
+::
-Parameter: id: handle for debug log
- level: debug level
- data: pointer to data for debug entry
- length: length of data in bytes
+ debug_entry_t* debug_exception (debug_info_t* id, int level, void* data,
+ int length);
-Return Value: Address of written debug entry
+Parameter:
+ id:
+ handle for debug log
+ level:
+ debug level
+ data:
+ pointer to data for debug entry
+ length:
+ length of data in bytes
-Description: writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
+Return Value:
+ Address of written debug entry
+
+Description:
+ writes debug entry to active debug area (if level <= actual
+ debug level) and switches to next debug area
---------------------------------------------------------------------------
-debug_entry_t* debug_int_exception (debug_info_t * id, int level,
- unsigned int data);
-debug_entry_t* debug_long_exception(debug_info_t * id, int level,
- unsigned long data);
-Parameter: id: handle for debug log
- level: debug level
- data: integer value for debug entry
+::
+
+ debug_entry_t* debug_int_exception (debug_info_t * id, int level,
+ unsigned int data);
+ debug_entry_t* debug_long_exception(debug_info_t * id, int level,
+ unsigned long data);
+
+Parameter: id: handle for debug log
+ level: debug level
+ data: integer value for debug entry
-Return Value: Address of written debug entry
+Return Value: Address of written debug entry
-Description: writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
+Description: writes debug entry to active debug area (if level <= actual
+ debug level) and switches to next debug area
---------------------------------------------------------------------------
-debug_entry_t* debug_text_exception (debug_info_t * id, int level,
- const char* data);
-Parameter: id: handle for debug log
- level: debug level
- data: string for debug entry
+::
+
+ debug_entry_t* debug_text_exception (debug_info_t * id, int level,
+ const char* data);
-Return Value: Address of written debug entry
+Parameter: id: handle for debug log
+ level: debug level
+ data: string for debug entry
-Description: writes debug entry in ascii format to active debug area
- (if level <= actual debug level) and switches to next debug
- area
+Return Value: Address of written debug entry
+
+Description: writes debug entry in ascii format to active debug area
+ (if level <= actual debug level) and switches to next debug
+ area
---------------------------------------------------------------------------
-debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level,
- char* string,...);
-Parameter: id: handle for debug log
- level: debug level
- string: format string for debug entry
- ...: varargs used as in sprintf()
+::
+
+ debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level,
+ char* string,...);
-Return Value: Address of written debug entry
+Parameter: id: handle for debug log
+ level: debug level
+ string: format string for debug entry
+ ...: varargs used as in sprintf()
-Description: writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level) and
- switches to next debug area.
- floats and long long datatypes cannot be used as varargs.
+Return Value: Address of written debug entry
+
+Description: writes debug entry with format string and varargs (longs) to
+ active debug area (if level $<=$ actual debug level) and
+ switches to next debug area.
+ floats and long long datatypes cannot be used as varargs.
---------------------------------------------------------------------------
-int debug_register_view (debug_info_t * id, struct debug_view *view);
+::
+
+ int debug_register_view (debug_info_t * id, struct debug_view *view);
-Parameter: id: handle for debug log
- view: pointer to debug view struct
+Parameter: id: handle for debug log
+ view: pointer to debug view struct
-Return Value: 0 : ok
- < 0: Error
+Return Value: 0 : ok
+ < 0: Error
Description: registers new debug view and creates debugfs dir entry
---------------------------------------------------------------------------
-int debug_unregister_view (debug_info_t * id, struct debug_view *view);
-Parameter: id: handle for debug log
- view: pointer to debug view struct
+::
-Return Value: 0 : ok
- < 0: Error
+ int debug_unregister_view (debug_info_t * id, struct debug_view *view);
+
+Parameter: id: handle for debug log
+ view: pointer to debug view struct
+
+Return Value: 0 : ok
+ < 0: Error
Description: unregisters debug view and removes debugfs dir entry
@@ -323,113 +442,117 @@ Predefined views:
-----------------
extern struct debug_view debug_hex_ascii_view;
+
extern struct debug_view debug_raw_view;
+
extern struct debug_view debug_sprintf_view;
Examples
--------
-/*
- * hex_ascii- + raw-view Example
- */
+::
-#include <linux/init.h>
-#include <asm/debug.h>
+ /*
+ * hex_ascii- + raw-view Example
+ */
-static debug_info_t* debug_info;
+ #include <linux/init.h>
+ #include <asm/debug.h>
-static int init(void)
-{
- /* register 4 debug areas with one page each and 4 byte data field */
+ static debug_info_t* debug_info;
- debug_info = debug_register ("test", 1, 4, 4 );
- debug_register_view(debug_info,&debug_hex_ascii_view);
- debug_register_view(debug_info,&debug_raw_view);
+ static int init(void)
+ {
+ /* register 4 debug areas with one page each and 4 byte data field */
- debug_text_event(debug_info, 4 , "one ");
- debug_int_exception(debug_info, 4, 4711);
- debug_event(debug_info, 3, &debug_info, 4);
+ debug_info = debug_register ("test", 1, 4, 4 );
+ debug_register_view(debug_info,&debug_hex_ascii_view);
+ debug_register_view(debug_info,&debug_raw_view);
- return 0;
-}
+ debug_text_event(debug_info, 4 , "one ");
+ debug_int_exception(debug_info, 4, 4711);
+ debug_event(debug_info, 3, &debug_info, 4);
-static void cleanup(void)
-{
- debug_unregister (debug_info);
-}
+ return 0;
+ }
-module_init(init);
-module_exit(cleanup);
+ static void cleanup(void)
+ {
+ debug_unregister (debug_info);
+ }
+
+ module_init(init);
+ module_exit(cleanup);
---------------------------------------------------------------------------
-/*
- * sprintf-view Example
- */
+::
-#include <linux/init.h>
-#include <asm/debug.h>
+ /*
+ * sprintf-view Example
+ */
-static debug_info_t* debug_info;
+ #include <linux/init.h>
+ #include <asm/debug.h>
-static int init(void)
-{
- /* register 4 debug areas with one page each and data field for */
- /* format string pointer + 2 varargs (= 3 * sizeof(long)) */
+ static debug_info_t* debug_info;
- debug_info = debug_register ("test", 1, 4, sizeof(long) * 3);
- debug_register_view(debug_info,&debug_sprintf_view);
+ static int init(void)
+ {
+ /* register 4 debug areas with one page each and data field for */
+ /* format string pointer + 2 varargs (= 3 * sizeof(long)) */
- debug_sprintf_event(debug_info, 2 , "first event in %s:%i\n",__FILE__,__LINE__);
- debug_sprintf_exception(debug_info, 1, "pointer to debug info: %p\n",&debug_info);
+ debug_info = debug_register ("test", 1, 4, sizeof(long) * 3);
+ debug_register_view(debug_info,&debug_sprintf_view);
- return 0;
-}
+ debug_sprintf_event(debug_info, 2 , "first event in %s:%i\n",__FILE__,__LINE__);
+ debug_sprintf_exception(debug_info, 1, "pointer to debug info: %p\n",&debug_info);
-static void cleanup(void)
-{
- debug_unregister (debug_info);
-}
-
-module_init(init);
-module_exit(cleanup);
+ return 0;
+ }
+ static void cleanup(void)
+ {
+ debug_unregister (debug_info);
+ }
+ module_init(init);
+ module_exit(cleanup);
Debugfs Interface
-----------------
-Views to the debug logs can be investigated through reading the corresponding
+-----------------
+Views to the debug logs can be investigated through reading the corresponding
debugfs-files:
-Example:
+Example::
-> ls /sys/kernel/debug/s390dbf/dasd
-flush hex_ascii level pages raw
-> cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s
-00 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | ....
-00 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE
-00 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | ....
-00 00974733272:682281 1 * 02 0006ab08 41 4c 4c 43 | EXCP
-01 00974733272:682284 2 - 02 0006ab16 45 43 4b 44 | ECKD
-01 00974733272:682287 2 - 02 0006ab28 00 00 00 04 | ....
-01 00974733272:682289 2 - 02 0006ab3e 00 00 00 20 | ...
-01 00974733272:682297 2 - 02 0006ad7e 07 ea 4a 90 | ....
-01 00974733272:684384 2 - 00 0006ade6 46 52 45 45 | FREE
-01 00974733272:684388 2 - 00 0006adf6 07 ea 4a 90 | ....
+ > ls /sys/kernel/debug/s390dbf/dasd
+ flush hex_ascii level pages raw
+ > cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s
+ 00 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | ....
+ 00 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE
+ 00 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | ....
+ 00 00974733272:682281 1 * 02 0006ab08 41 4c 4c 43 | EXCP
+ 01 00974733272:682284 2 - 02 0006ab16 45 43 4b 44 | ECKD
+ 01 00974733272:682287 2 - 02 0006ab28 00 00 00 04 | ....
+ 01 00974733272:682289 2 - 02 0006ab3e 00 00 00 20 | ...
+ 01 00974733272:682297 2 - 02 0006ad7e 07 ea 4a 90 | ....
+ 01 00974733272:684384 2 - 00 0006ade6 46 52 45 45 | FREE
+ 01 00974733272:684388 2 - 00 0006adf6 07 ea 4a 90 | ....
See section about predefined views for explanation of the above output!
Changing the debug level
------------------------
-Example:
+Example::
-> cat /sys/kernel/debug/s390dbf/dasd/level
-3
-> echo "5" > /sys/kernel/debug/s390dbf/dasd/level
-> cat /sys/kernel/debug/s390dbf/dasd/level
-5
+ > cat /sys/kernel/debug/s390dbf/dasd/level
+ 3
+ > echo "5" > /sys/kernel/debug/s390dbf/dasd/level
+ > cat /sys/kernel/debug/s390dbf/dasd/level
+ 5
Flushing debug areas
--------------------
@@ -439,11 +562,13 @@ are flushed.
Examples:
-1. Flush debug area 0:
-> echo "0" > /sys/kernel/debug/s390dbf/dasd/flush
+1. Flush debug area 0::
-2. Flush all debug areas:
-> echo "-" > /sys/kernel/debug/s390dbf/dasd/flush
+ > echo "0" > /sys/kernel/debug/s390dbf/dasd/flush
+
+2. Flush all debug areas::
+
+ > echo "-" > /sys/kernel/debug/s390dbf/dasd/flush
Changing the size of debug areas
------------------------------------
@@ -453,23 +578,27 @@ also flush the debug areas.
Example:
-Define 4 pages for the debug areas of debug feature "dasd":
-> echo "4" > /sys/kernel/debug/s390dbf/dasd/pages
+Define 4 pages for the debug areas of debug feature "dasd"::
+
+ > echo "4" > /sys/kernel/debug/s390dbf/dasd/pages
Stooping the debug feature
--------------------------
Example:
-1. Check if stopping is allowed
-> cat /proc/sys/s390dbf/debug_stoppable
-2. Stop debug feature
-> echo 0 > /proc/sys/s390dbf/debug_active
+1. Check if stopping is allowed::
+
+ > cat /proc/sys/s390dbf/debug_stoppable
+
+2. Stop debug feature::
+
+ > echo 0 > /proc/sys/s390dbf/debug_active
lcrash Interface
----------------
It is planned that the dump analysis tool lcrash gets an additional command
-'s390dbf' to display all the debug logs. With this tool it will be possible
-to investigate the debug logs on a live system and with a memory dump after
+'s390dbf' to display all the debug logs. With this tool it will be possible
+to investigate the debug logs on a live system and with a memory dump after
a system crash.
Investigating raw memory
@@ -494,32 +623,35 @@ order to see the debug entries well formatted.
Predefined Views
----------------
-There are three predefined views: hex_ascii, raw and sprintf.
-The hex_ascii view shows the data field in hex and ascii representation
-(e.g. '45 43 4b 44 | ECKD').
+There are three predefined views: hex_ascii, raw and sprintf.
+The hex_ascii view shows the data field in hex and ascii representation
+(e.g. '45 43 4b 44 | ECKD').
The raw view returns a bytestream as the debug areas are stored in memory.
The sprintf view formats the debug entries in the same way as the sprintf
function would do. The sprintf event/exception functions write to the
-debug entry a pointer to the format string (size = sizeof(long))
-and for each vararg a long value. So e.g. for a debug entry with a format
-string plus two varargs one would need to allocate a (3 * sizeof(long))
+debug entry a pointer to the format string (size = sizeof(long))
+and for each vararg a long value. So e.g. for a debug entry with a format
+string plus two varargs one would need to allocate a (3 * sizeof(long))
byte data area in the debug_register() function.
-IMPORTANT: Using "%s" in sprintf event functions is dangerous. You can only
-use "%s" in the sprintf event functions, if the memory for the passed string is
-available as long as the debug feature exists. The reason behind this is that
-due to performance considerations only a pointer to the string is stored in
-the debug feature. If you log a string that is freed afterwards, you will get
-an OOPS when inspecting the debug feature, because then the debug feature will
-access the already freed memory.
+IMPORTANT:
+ Using "%s" in sprintf event functions is dangerous. You can only
+ use "%s" in the sprintf event functions, if the memory for the passed string
+ is available as long as the debug feature exists. The reason behind this is
+ that due to performance considerations only a pointer to the string is stored
+ in the debug feature. If you log a string that is freed afterwards, you will
+ get an OOPS when inspecting the debug feature, because then the debug feature
+ will access the already freed memory.
-NOTE: If using the sprintf view do NOT use other event/exception functions
-than the sprintf-event and -exception functions.
+NOTE:
+ If using the sprintf view do NOT use other event/exception functions
+ than the sprintf-event and -exception functions.
The format of the hex_ascii and sprintf view is as follows:
+
- Number of area
-- Timestamp (formatted as seconds and microseconds since 00:00:00 Coordinated
+- Timestamp (formatted as seconds and microseconds since 00:00:00 Coordinated
Universal Time (UTC), January 1, 1970)
- level of debug entry
- Exception flag (* = Exception)
@@ -528,140 +660,144 @@ The format of the hex_ascii and sprintf view is as follows:
- data field
The format of the raw view is:
+
- Header as described in debug.h
-- datafield
+- datafield
-A typical line of the hex_ascii view will look like the following (first line
+A typical line of the hex_ascii view will look like the following (first line
is only for explanation and will not be displayed when 'cating' the view):
area time level exception cpu caller data (hex + ascii)
--------------------------------------------------------------------------
-00 00964419409:440690 1 - 00 88023fe
+00 00964419409:440690 1 - 00 88023fe
Defining views
--------------
Views are specified with the 'debug_view' structure. There are defined
-callback functions which are used for reading and writing the debugfs files:
+callback functions which are used for reading and writing the debugfs files::
-struct debug_view {
- char name[DEBUG_MAX_PROCF_LEN];
- debug_prolog_proc_t* prolog_proc;
- debug_header_proc_t* header_proc;
- debug_format_proc_t* format_proc;
- debug_input_proc_t* input_proc;
+ struct debug_view {
+ char name[DEBUG_MAX_PROCF_LEN];
+ debug_prolog_proc_t* prolog_proc;
+ debug_header_proc_t* header_proc;
+ debug_format_proc_t* format_proc;
+ debug_input_proc_t* input_proc;
void* private_data;
-};
+ };
-where
+where::
-typedef int (debug_header_proc_t) (debug_info_t* id,
- struct debug_view* view,
- int area,
- debug_entry_t* entry,
- char* out_buf);
+ typedef int (debug_header_proc_t) (debug_info_t* id,
+ struct debug_view* view,
+ int area,
+ debug_entry_t* entry,
+ char* out_buf);
-typedef int (debug_format_proc_t) (debug_info_t* id,
- struct debug_view* view, char* out_buf,
- const char* in_buf);
-typedef int (debug_prolog_proc_t) (debug_info_t* id,
- struct debug_view* view,
- char* out_buf);
-typedef int (debug_input_proc_t) (debug_info_t* id,
- struct debug_view* view,
- struct file* file, const char* user_buf,
- size_t in_buf_size, loff_t* offset);
+ typedef int (debug_format_proc_t) (debug_info_t* id,
+ struct debug_view* view, char* out_buf,
+ const char* in_buf);
+ typedef int (debug_prolog_proc_t) (debug_info_t* id,
+ struct debug_view* view,
+ char* out_buf);
+ typedef int (debug_input_proc_t) (debug_info_t* id,
+ struct debug_view* view,
+ struct file* file, const char* user_buf,
+ size_t in_buf_size, loff_t* offset);
The "private_data" member can be used as pointer to view specific data.
It is not used by the debug feature itself.
-The output when reading a debugfs file is structured like this:
+The output when reading a debugfs file is structured like this::
-"prolog_proc output"
+ "prolog_proc output"
-"header_proc output 1" "format_proc output 1"
-"header_proc output 2" "format_proc output 2"
-"header_proc output 3" "format_proc output 3"
-...
+ "header_proc output 1" "format_proc output 1"
+ "header_proc output 2" "format_proc output 2"
+ "header_proc output 3" "format_proc output 3"
+ ...
When a view is read from the debugfs, the Debug Feature calls the
'prolog_proc' once for writing the prolog.
-Then 'header_proc' and 'format_proc' are called for each
+Then 'header_proc' and 'format_proc' are called for each
existing debug entry.
-The input_proc can be used to implement functionality when it is written to
+The input_proc can be used to implement functionality when it is written to
the view (e.g. like with 'echo "0" > /sys/kernel/debug/s390dbf/dasd/level).
For header_proc there can be used the default function
debug_dflt_header_fn() which is defined in debug.h.
and which produces the same header output as the predefined views.
-E.g:
-00 00964419409:440761 2 - 00 88023ec
+E.g::
+
+ 00 00964419409:440761 2 - 00 88023ec
In order to see how to use the callback functions check the implementation
of the default views!
-Example
+Example::
-#include <asm/debug.h>
+ #include <asm/debug.h>
-#define UNKNOWNSTR "data: %08x"
+ #define UNKNOWNSTR "data: %08x"
-const char* messages[] =
-{"This error...........\n",
- "That error...........\n",
- "Problem..............\n",
- "Something went wrong.\n",
- "Everything ok........\n",
- NULL
-};
+ const char* messages[] =
+ {"This error...........\n",
+ "That error...........\n",
+ "Problem..............\n",
+ "Something went wrong.\n",
+ "Everything ok........\n",
+ NULL
+ };
-static int debug_test_format_fn(
- debug_info_t * id, struct debug_view *view,
- char *out_buf, const char *in_buf
-)
-{
- int i, rc = 0;
+ static int debug_test_format_fn(
+ debug_info_t * id, struct debug_view *view,
+ char *out_buf, const char *in_buf
+ )
+ {
+ int i, rc = 0;
- if(id->buf_size >= 4) {
- int msg_nr = *((int*)in_buf);
- if(msg_nr < sizeof(messages)/sizeof(char*) - 1)
- rc += sprintf(out_buf, "%s", messages[msg_nr]);
- else
- rc += sprintf(out_buf, UNKNOWNSTR, msg_nr);
+ if(id->buf_size >= 4) {
+ int msg_nr = *((int*)in_buf);
+ if(msg_nr < sizeof(messages)/sizeof(char*) - 1)
+ rc += sprintf(out_buf, "%s", messages[msg_nr]);
+ else
+ rc += sprintf(out_buf, UNKNOWNSTR, msg_nr);
+ }
+ out:
+ return rc;
}
- out:
- return rc;
-}
-struct debug_view debug_test_view = {
- "myview", /* name of view */
- NULL, /* no prolog */
- &debug_dflt_header_fn, /* default header for each entry */
- &debug_test_format_fn, /* our own format function */
- NULL, /* no input function */
- NULL /* no private data */
-};
+ struct debug_view debug_test_view = {
+ "myview", /* name of view */
+ NULL, /* no prolog */
+ &debug_dflt_header_fn, /* default header for each entry */
+ &debug_test_format_fn, /* our own format function */
+ NULL, /* no input function */
+ NULL /* no private data */
+ };
-=====
test:
=====
-debug_info_t *debug_info;
-...
-debug_info = debug_register ("test", 0, 4, 4 ));
-debug_register_view(debug_info, &debug_test_view);
-for(i = 0; i < 10; i ++) debug_int_event(debug_info, 1, i);
-> cat /sys/kernel/debug/s390dbf/test/myview
-00 00964419734:611402 1 - 00 88042ca This error...........
-00 00964419734:611405 1 - 00 88042ca That error...........
-00 00964419734:611408 1 - 00 88042ca Problem..............
-00 00964419734:611411 1 - 00 88042ca Something went wrong.
-00 00964419734:611414 1 - 00 88042ca Everything ok........
-00 00964419734:611417 1 - 00 88042ca data: 00000005
-00 00964419734:611419 1 - 00 88042ca data: 00000006
-00 00964419734:611422 1 - 00 88042ca data: 00000007
-00 00964419734:611425 1 - 00 88042ca data: 00000008
-00 00964419734:611428 1 - 00 88042ca data: 00000009
+::
+
+ debug_info_t *debug_info;
+ ...
+ debug_info = debug_register ("test", 0, 4, 4 ));
+ debug_register_view(debug_info, &debug_test_view);
+ for(i = 0; i < 10; i ++) debug_int_event(debug_info, 1, i);
+
+ > cat /sys/kernel/debug/s390dbf/test/myview
+ 00 00964419734:611402 1 - 00 88042ca This error...........
+ 00 00964419734:611405 1 - 00 88042ca That error...........
+ 00 00964419734:611408 1 - 00 88042ca Problem..............
+ 00 00964419734:611411 1 - 00 88042ca Something went wrong.
+ 00 00964419734:611414 1 - 00 88042ca Everything ok........
+ 00 00964419734:611417 1 - 00 88042ca data: 00000005
+ 00 00964419734:611419 1 - 00 88042ca data: 00000006
+ 00 00964419734:611422 1 - 00 88042ca data: 00000007
+ 00 00964419734:611425 1 - 00 88042ca data: 00000008
+ 00 00964419734:611428 1 - 00 88042ca data: 00000009
diff --git a/Documentation/s390/text_files.rst b/Documentation/s390/text_files.rst
new file mode 100644
index 000000000000..c94d05d4fa17
--- /dev/null
+++ b/Documentation/s390/text_files.rst
@@ -0,0 +1,11 @@
+ibm 3270 changelog
+------------------
+
+.. include:: 3270.ChangeLog
+ :literal:
+
+ibm 3270 config3270.sh
+----------------------
+
+.. literalinclude:: config3270.sh
+ :language: shell
diff --git a/Documentation/s390/vfio-ap.txt b/Documentation/s390/vfio-ap.rst
similarity index 72%
rename from Documentation/s390/vfio-ap.txt
rename to Documentation/s390/vfio-ap.rst
index 65167cfe4485..b5c51f7c748d 100644
--- a/Documentation/s390/vfio-ap.txt
+++ b/Documentation/s390/vfio-ap.rst
@@ -1,4 +1,9 @@
-Introduction:
+===============================
+Adjunct Processor (AP) facility
+===============================
+
+
+Introduction
============
The Adjunct Processor (AP) facility is an IBM Z cryptographic facility comprised
of three AP instructions and from 1 up to 256 PCIe cryptographic adapter cards.
@@ -11,7 +16,7 @@ framework. This implementation relies considerably on the s390 virtualization
facilities which do most of the hard work of providing direct access to AP
devices.
-AP Architectural Overview:
+AP Architectural Overview
=========================
To facilitate the comprehension of the design, let's start with some
definitions:
@@ -31,13 +36,13 @@ definitions:
in the LPAR, the AP bus detects the AP adapter cards assigned to the LPAR and
creates a sysfs device for each assigned adapter. For example, if AP adapters
4 and 10 (0x0a) are assigned to the LPAR, the AP bus will create the following
- sysfs device entries:
+ sysfs device entries::
/sys/devices/ap/card04
/sys/devices/ap/card0a
Symbolic links to these devices will also be created in the AP bus devices
- sub-directory:
+ sub-directory::
/sys/bus/ap/devices/[card04]
/sys/bus/ap/devices/[card04]
@@ -84,7 +89,7 @@ definitions:
the cross product of the AP adapter and usage domain numbers detected when the
AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and usage
domains 6 and 71 (0x47) are assigned to the LPAR, the AP bus will create the
- following sysfs entries:
+ following sysfs entries::
/sys/devices/ap/card04/04.0006
/sys/devices/ap/card04/04.0047
@@ -92,7 +97,7 @@ definitions:
/sys/devices/ap/card0a/0a.0047
The following symbolic links to these devices will be created in the AP bus
- devices subdirectory:
+ devices subdirectory::
/sys/bus/ap/devices/[04.0006]
/sys/bus/ap/devices/[04.0047]
@@ -112,7 +117,7 @@ definitions:
domain that is not one of the usage domains, but the modified domain
must be one of the control domains.
-AP and SIE:
+AP and SIE
==========
Let's now take a look at how AP instructions executed on a guest are interpreted
by the hardware.
@@ -153,7 +158,7 @@ and 2 and usage domains 5 and 6 are assigned to a guest, the APQNs (1,5), (1,6),
The APQNs can provide secure key functionality - i.e., a private key is stored
on the adapter card for each of its domains - so each APQN must be assigned to
-at most one guest or to the linux host.
+at most one guest or to the linux host::
Example 1: Valid configuration:
------------------------------
@@ -181,8 +186,8 @@ at most one guest or to the linux host.
This is an invalid configuration because both guests have access to
APQN (1,6).
-The Design:
-===========
+The Design
+==========
The design introduces three new objects:
1. AP matrix device
@@ -205,43 +210,43 @@ The VFIO AP (vfio_ap) device driver serves the following purposes:
Reserve APQNs for exclusive use of KVM guests
---------------------------------------------
The following block diagram illustrates the mechanism by which APQNs are
-reserved:
+reserved::
- +------------------+
- 7 remove | |
- +--------------------> cex4queue driver |
- | | |
- | +------------------+
- |
- |
- | +------------------+ +-----------------+
- | 5 register driver | | 3 create | |
- | +----------------> Device core +----------> matrix device |
- | | | | | |
- | | +--------^---------+ +-----------------+
- | | |
- | | +-------------------+
- | | +-----------------------------------+ |
- | | | 4 register AP driver | | 2 register device
- | | | | |
-+--------+---+-v---+ +--------+-------+-+
-| | | |
-| ap_bus +--------------------- > vfio_ap driver |
-| | 8 probe | |
-+--------^---------+ +--^--^------------+
-6 edit | | |
- apmask | +-----------------------------+ | 9 mdev create
- aqmask | | 1 modprobe |
-+--------+-----+---+ +----------------+-+ +------------------+
-| | | |8 create | mediated |
-| admin | | VFIO device core |---------> matrix |
-| + | | | device |
-+------+-+---------+ +--------^---------+ +--------^---------+
- | | | |
- | | 9 create vfio_ap-passthrough | |
- | +------------------------------+ |
- +-------------------------------------------------------------+
- 10 assign adapter/domain/control domain
+ +------------------+
+ 7 remove | |
+ +--------------------> cex4queue driver |
+ | | |
+ | +------------------+
+ |
+ |
+ | +------------------+ +----------------+
+ | 5 register driver | | 3 create | |
+ | +----------------> Device core +----------> matrix device |
+ | | | | | |
+ | | +--------^---------+ +----------------+
+ | | |
+ | | +-------------------+
+ | | +-----------------------------------+ |
+ | | | 4 register AP driver | | 2 register device
+ | | | | |
+ +--------+---+-v---+ +--------+-------+-+
+ | | | |
+ | ap_bus +--------------------- > vfio_ap driver |
+ | | 8 probe | |
+ +--------^---------+ +--^--^------------+
+ 6 edit | | |
+ apmask | +-----------------------------+ | 9 mdev create
+ aqmask | | 1 modprobe |
+ +--------+-----+---+ +----------------+-+ +----------------+
+ | | | |8 create | mediated |
+ | admin | | VFIO device core |---------> matrix |
+ | + | | | device |
+ +------+-+---------+ +--------^---------+ +--------^-------+
+ | | | |
+ | | 9 create vfio_ap-passthrough | |
+ | +------------------------------+ |
+ +-------------------------------------------------------------+
+ 10 assign adapter/domain/control domain
The process for reserving an AP queue for use by a KVM guest is:
@@ -250,7 +255,7 @@ The process for reserving an AP queue for use by a KVM guest is:
device with the device core. This will serve as the parent device for
all mediated matrix devices used to configure an AP matrix for a guest.
3. The /sys/devices/vfio_ap/matrix device is created by the device core
-4 The vfio_ap device driver will register with the AP bus for AP queue devices
+4. The vfio_ap device driver will register with the AP bus for AP queue devices
of type 10 and higher (CEX4 and newer). The driver will provide the vfio_ap
driver's probe and remove callback interfaces. Devices older than CEX4 queues
are not supported to simplify the implementation by not needlessly
@@ -266,13 +271,14 @@ The process for reserving an AP queue for use by a KVM guest is:
it.
9. The administrator creates a passthrough type mediated matrix device to be
used by a guest
-10 The administrator assigns the adapters, usage domains and control domains
- to be exclusively used by a guest.
+10. The administrator assigns the adapters, usage domains and control domains
+ to be exclusively used by a guest.
Set up the VFIO mediated device interfaces
------------------------------------------
The VFIO AP device driver utilizes the common interface of the VFIO mediated
device core driver to:
+
* Register an AP mediated bus driver to add a mediated matrix device to and
remove it from a VFIO group.
* Create and destroy a mediated matrix device
@@ -280,25 +286,25 @@ device core driver to:
* Add a mediated matrix device to and remove it from an IOMMU group
The following high-level block diagram shows the main components and interfaces
-of the VFIO AP mediated matrix device driver:
+of the VFIO AP mediated matrix device driver::
- +-------------+
- | |
- | +---------+ | mdev_register_driver() +--------------+
- | | Mdev | +<-----------------------+ |
- | | bus | | | vfio_mdev.ko |
- | | driver | +----------------------->+ |<-> VFIO user
- | +---------+ | probe()/remove() +--------------+ APIs
- | |
- | MDEV CORE |
- | MODULE |
- | mdev.ko |
- | +---------+ | mdev_register_device() +--------------+
- | |Physical | +<-----------------------+ |
- | | device | | | vfio_ap.ko |<-> matrix
- | |interface| +----------------------->+ | device
- | +---------+ | callback +--------------+
- +-------------+
+ +-------------+
+ | |
+ | +---------+ | mdev_register_driver() +--------------+
+ | | Mdev | +<-----------------------+ |
+ | | bus | | | vfio_mdev.ko |
+ | | driver | +----------------------->+ |<-> VFIO user
+ | +---------+ | probe()/remove() +--------------+ APIs
+ | |
+ | MDEV CORE |
+ | MODULE |
+ | mdev.ko |
+ | +---------+ | mdev_register_device() +--------------+
+ | |Physical | +<-----------------------+ |
+ | | device | | | vfio_ap.ko |<-> matrix
+ | |interface| +----------------------->+ | device
+ | +---------+ | callback +--------------+
+ +-------------+
During initialization of the vfio_ap module, the matrix device is registered
with an 'mdev_parent_ops' structure that provides the sysfs attribute
@@ -306,7 +312,8 @@ structures, mdev functions and callback interfaces for managing the mediated
matrix device.
* sysfs attribute structures:
- * supported_type_groups
+
+ supported_type_groups
The VFIO mediated device framework supports creation of user-defined
mediated device types. These mediated device types are specified
via the 'supported_type_groups' structure when a device is registered
@@ -318,61 +325,72 @@ matrix device.
The VFIO AP device driver will register one mediated device type for
passthrough devices:
+
/sys/devices/vfio_ap/matrix/mdev_supported_types/vfio_ap-passthrough
+
Only the read-only attributes required by the VFIO mdev framework will
- be provided:
- ... name
- ... device_api
- ... available_instances
- ... device_api
- Where:
- * name: specifies the name of the mediated device type
- * device_api: the mediated device type's API
- * available_instances: the number of mediated matrix passthrough devices
- that can be created
- * device_api: specifies the VFIO API
- * mdev_attr_groups
+ be provided::
+
+ ... name
+ ... device_api
+ ... available_instances
+ ... device_api
+
+ Where:
+
+ * name:
+ specifies the name of the mediated device type
+ * device_api:
+ the mediated device type's API
+ * available_instances:
+ the number of mediated matrix passthrough devices
+ that can be created
+ * device_api:
+ specifies the VFIO API
+ mdev_attr_groups
This attribute group identifies the user-defined sysfs attributes of the
mediated device. When a device is registered with the VFIO mediated device
framework, the sysfs attribute files identified in the 'mdev_attr_groups'
structure will be created in the mediated matrix device's directory. The
sysfs attributes for a mediated matrix device are:
- * assign_adapter:
- * unassign_adapter:
+
+ assign_adapter / unassign_adapter:
Write-only attributes for assigning/unassigning an AP adapter to/from the
mediated matrix device. To assign/unassign an adapter, the APID of the
adapter is echoed to the respective attribute file.
- * assign_domain:
- * unassign_domain:
+ assign_domain / unassign_domain:
Write-only attributes for assigning/unassigning an AP usage domain to/from
the mediated matrix device. To assign/unassign a domain, the domain
number of the the usage domain is echoed to the respective attribute
file.
- * matrix:
+ matrix:
A read-only file for displaying the APQNs derived from the cross product
of the adapter and domain numbers assigned to the mediated matrix device.
- * assign_control_domain:
- * unassign_control_domain:
+ assign_control_domain / unassign_control_domain:
Write-only attributes for assigning/unassigning an AP control domain
to/from the mediated matrix device. To assign/unassign a control domain,
the ID of the domain to be assigned/unassigned is echoed to the respective
attribute file.
- * control_domains:
+ control_domains:
A read-only file for displaying the control domain numbers assigned to the
mediated matrix device.
* functions:
- * create:
+
+ create:
allocates the ap_matrix_mdev structure used by the vfio_ap driver to:
+
* Store the reference to the KVM structure for the guest using the mdev
* Store the AP matrix configuration for the adapters, domains, and control
domains assigned via the corresponding sysfs attributes files
- * remove:
+
+ remove:
deallocates the mediated matrix device's ap_matrix_mdev structure. This will
be allowed only if a running guest is not using the mdev.
* callback interfaces
- * open:
+
+ open:
The vfio_ap driver uses this callback to register a
VFIO_GROUP_NOTIFY_SET_KVM notifier callback function for the mdev matrix
device. The open is invoked when QEMU connects the VFIO iommu group
@@ -380,16 +398,17 @@ matrix device.
to configure the KVM guest is provided via this callback. The KVM structure,
is used to configure the guest's access to the AP matrix defined via the
mediated matrix device's sysfs attribute files.
- * release:
+ release:
unregisters the VFIO_GROUP_NOTIFY_SET_KVM notifier callback function for the
mdev matrix device and deconfigures the guest's AP matrix.
-Configure the APM, AQM and ADM in the CRYCB:
+Configure the APM, AQM and ADM in the CRYCB
-------------------------------------------
Configuring the AP matrix for a KVM guest will be performed when the
VFIO_GROUP_NOTIFY_SET_KVM notifier callback is invoked. The notifier
function is called when QEMU connects to KVM. The guest's AP matrix is
configured via it's CRYCB by:
+
* Setting the bits in the APM corresponding to the APIDs assigned to the
mediated matrix device via its 'assign_adapter' interface.
* Setting the bits in the AQM corresponding to the domains assigned to the
@@ -418,12 +437,12 @@ available to a KVM guest via the following CPU model features:
Note: If the user chooses to specify a CPU model different than the 'host'
model to QEMU, the CPU model features and facilities need to be turned on
-explicitly; for example:
+explicitly; for example::
/usr/bin/qemu-system-s390x ... -cpu z13,ap=on,apqci=on,apft=on
A guest can be precluded from using AP features/facilities by turning them off
-explicitly; for example:
+explicitly; for example::
/usr/bin/qemu-system-s390x ... -cpu host,ap=off,apqci=off,apft=off
@@ -435,7 +454,7 @@ the APFT facility is not installed on the guest, then the probe of device
drivers will fail since only type 10 and newer devices can be configured for
guest use.
-Example:
+Example
=======
Let's now provide an example to illustrate how KVM guests may be given
access to AP facilities. For this example, we will show how to configure
@@ -444,30 +463,36 @@ look like this:
Guest1
------
+=========== ===== ============
CARD.DOMAIN TYPE MODE
-------------------------------
+=========== ===== ============
05 CEX5C CCA-Coproc
05.0004 CEX5C CCA-Coproc
05.00ab CEX5C CCA-Coproc
06 CEX5A Accelerator
06.0004 CEX5A Accelerator
06.00ab CEX5C CCA-Coproc
+=========== ===== ============
Guest2
------
+=========== ===== ============
CARD.DOMAIN TYPE MODE
-------------------------------
+=========== ===== ============
05 CEX5A Accelerator
05.0047 CEX5A Accelerator
05.00ff CEX5A Accelerator
+=========== ===== ============
Guest2
------
+=========== ===== ============
CARD.DOMAIN TYPE MODE
-------------------------------
+=========== ===== ============
06 CEX5A Accelerator
06.0047 CEX5A Accelerator
06.00ff CEX5A Accelerator
+=========== ===== ============
These are the steps:
@@ -492,25 +517,26 @@ These are the steps:
* VFIO_MDEV_DEVICE
* KVM
- If using make menuconfig select the following to build the vfio_ap module:
- -> Device Drivers
- -> IOMMU Hardware Support
- select S390 AP IOMMU Support
- -> VFIO Non-Privileged userspace driver framework
- -> Mediated device driver frramework
- -> VFIO driver for Mediated devices
- -> I/O subsystem
- -> VFIO support for AP devices
+ If using make menuconfig select the following to build the vfio_ap module::
+
+ -> Device Drivers
+ -> IOMMU Hardware Support
+ select S390 AP IOMMU Support
+ -> VFIO Non-Privileged userspace driver framework
+ -> Mediated device driver frramework
+ -> VFIO driver for Mediated devices
+ -> I/O subsystem
+ -> VFIO support for AP devices
2. Secure the AP queues to be used by the three guests so that the host can not
access them. To secure them, there are two sysfs files that specify
bitmasks marking a subset of the APQN range as 'usable by the default AP
queue device drivers' or 'not usable by the default device drivers' and thus
available for use by the vfio_ap device driver'. The location of the sysfs
- files containing the masks are:
+ files containing the masks are::
- /sys/bus/ap/apmask
- /sys/bus/ap/aqmask
+ /sys/bus/ap/apmask
+ /sys/bus/ap/aqmask
The 'apmask' is a 256-bit mask that identifies a set of AP adapter IDs
(APID). Each bit in the mask, from left to right (i.e., from most significant
@@ -526,7 +552,7 @@ These are the steps:
queue device drivers; otherwise, the APQI is usable by the vfio_ap device
driver.
- Take, for example, the following mask:
+ Take, for example, the following mask::
0x7dffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
@@ -548,68 +574,70 @@ These are the steps:
respective sysfs mask file in one of two formats:
* An absolute hex string starting with 0x - like "0x12345678" - sets
- the mask. If the given string is shorter than the mask, it is padded
- with 0s on the right; for example, specifying a mask value of 0x41 is
- the same as specifying:
+ the mask. If the given string is shorter than the mask, it is padded
+ with 0s on the right; for example, specifying a mask value of 0x41 is
+ the same as specifying::
- 0x4100000000000000000000000000000000000000000000000000000000000000
+ 0x4100000000000000000000000000000000000000000000000000000000000000
- Keep in mind that the mask reads from left to right (i.e., most
- significant to least significant bit in big endian order), so the mask
- above identifies device numbers 1 and 7 (01000001).
+ Keep in mind that the mask reads from left to right (i.e., most
+ significant to least significant bit in big endian order), so the mask
+ above identifies device numbers 1 and 7 (01000001).
- If the string is longer than the mask, the operation is terminated with
- an error (EINVAL).
+ If the string is longer than the mask, the operation is terminated with
+ an error (EINVAL).
* Individual bits in the mask can be switched on and off by specifying
- each bit number to be switched in a comma separated list. Each bit
- number string must be prepended with a ('+') or minus ('-') to indicate
- the corresponding bit is to be switched on ('+') or off ('-'). Some
- valid values are:
+ each bit number to be switched in a comma separated list. Each bit
+ number string must be prepended with a ('+') or minus ('-') to indicate
+ the corresponding bit is to be switched on ('+') or off ('-'). Some
+ valid values are:
- "+0" switches bit 0 on
- "-13" switches bit 13 off
- "+0x41" switches bit 65 on
- "-0xff" switches bit 255 off
+ - "+0" switches bit 0 on
+ - "-13" switches bit 13 off
+ - "+0x41" switches bit 65 on
+ - "-0xff" switches bit 255 off
- The following example:
- +0,-6,+0x47,-0xf0
+ The following example:
- Switches bits 0 and 71 (0x47) on
- Switches bits 6 and 240 (0xf0) off
+ +0,-6,+0x47,-0xf0
- Note that the bits not specified in the list remain as they were before
- the operation.
+ Switches bits 0 and 71 (0x47) on
+
+ Switches bits 6 and 240 (0xf0) off
+
+ Note that the bits not specified in the list remain as they were before
+ the operation.
2. The masks can also be changed at boot time via parameters on the kernel
command line like this:
- ap.apmask=0xffff ap.aqmask=0x40
+ ap.apmask=0xffff ap.aqmask=0x40
- This would create the following masks:
+ This would create the following masks::
- apmask:
- 0xffff000000000000000000000000000000000000000000000000000000000000
+ apmask:
+ 0xffff000000000000000000000000000000000000000000000000000000000000
- aqmask:
- 0x4000000000000000000000000000000000000000000000000000000000000000
+ aqmask:
+ 0x4000000000000000000000000000000000000000000000000000000000000000
- Resulting in these two pools:
+ Resulting in these two pools::
- default drivers pool: adapter 0-15, domain 1
- alternate drivers pool: adapter 16-255, domains 0, 2-255
+ default drivers pool: adapter 0-15, domain 1
+ alternate drivers pool: adapter 16-255, domains 0, 2-255
- Securing the APQNs for our example:
- ----------------------------------
+Securing the APQNs for our example
+----------------------------------
To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004, 06.0047,
06.00ab, and 06.00ff for use by the vfio_ap device driver, the corresponding
- APQNs can either be removed from the default masks:
+ APQNs can either be removed from the default masks::
echo -5,-6 > /sys/bus/ap/apmask
echo -4,-0x47,-0xab,-0xff > /sys/bus/ap/aqmask
- Or the masks can be set as follows:
+ Or the masks can be set as follows::
echo 0xf9ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff \
> apmask
@@ -620,19 +648,19 @@ These are the steps:
This will result in AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004,
06.0047, 06.00ab, and 06.00ff getting bound to the vfio_ap device driver. The
sysfs directory for the vfio_ap device driver will now contain symbolic links
- to the AP queue devices bound to it:
+ to the AP queue devices bound to it::
- /sys/bus/ap
- ... [drivers]
- ...... [vfio_ap]
- ......... [05.0004]
- ......... [05.0047]
- ......... [05.00ab]
- ......... [05.00ff]
- ......... [06.0004]
- ......... [06.0047]
- ......... [06.00ab]
- ......... [06.00ff]
+ /sys/bus/ap
+ ... [drivers]
+ ...... [vfio_ap]
+ ......... [05.0004]
+ ......... [05.0047]
+ ......... [05.00ab]
+ ......... [05.00ff]
+ ......... [06.0004]
+ ......... [06.0047]
+ ......... [06.00ab]
+ ......... [06.00ff]
Keep in mind that only type 10 and newer adapters (i.e., CEX4 and later)
can be bound to the vfio_ap device driver. The reason for this is to
@@ -645,96 +673,96 @@ These are the steps:
queue device can be read from the parent card's sysfs directory. For example,
to see the hardware type of the queue 05.0004:
- cat /sys/bus/ap/devices/card05/hwtype
+ cat /sys/bus/ap/devices/card05/hwtype
The hwtype must be 10 or higher (CEX4 or newer) in order to be bound to the
vfio_ap device driver.
3. Create the mediated devices needed to configure the AP matrixes for the
three guests and to provide an interface to the vfio_ap driver for
- use by the guests:
+ use by the guests::
- /sys/devices/vfio_ap/matrix/
- --- [mdev_supported_types]
- ------ [vfio_ap-passthrough] (passthrough mediated matrix device type)
- --------- create
- --------- [devices]
+ /sys/devices/vfio_ap/matrix/
+ --- [mdev_supported_types]
+ ------ [vfio_ap-passthrough] (passthrough mediated matrix device type)
+ --------- create
+ --------- [devices]
- To create the mediated devices for the three guests:
+ To create the mediated devices for the three guests::
uuidgen > create
uuidgen > create
uuidgen > create
- or
+ or
- echo $uuid1 > create
- echo $uuid2 > create
- echo $uuid3 > create
+ echo $uuid1 > create
+ echo $uuid2 > create
+ echo $uuid3 > create
This will create three mediated devices in the [devices] subdirectory named
after the UUID written to the create attribute file. We call them $uuid1,
- $uuid2 and $uuid3 and this is the sysfs directory structure after creation:
+ $uuid2 and $uuid3 and this is the sysfs directory structure after creation::
- /sys/devices/vfio_ap/matrix/
- --- [mdev_supported_types]
- ------ [vfio_ap-passthrough]
- --------- [devices]
- ------------ [$uuid1]
- --------------- assign_adapter
- --------------- assign_control_domain
- --------------- assign_domain
- --------------- matrix
- --------------- unassign_adapter
- --------------- unassign_control_domain
- --------------- unassign_domain
+ /sys/devices/vfio_ap/matrix/
+ --- [mdev_supported_types]
+ ------ [vfio_ap-passthrough]
+ --------- [devices]
+ ------------ [$uuid1]
+ --------------- assign_adapter
+ --------------- assign_control_domain
+ --------------- assign_domain
+ --------------- matrix
+ --------------- unassign_adapter
+ --------------- unassign_control_domain
+ --------------- unassign_domain
- ------------ [$uuid2]
- --------------- assign_adapter
- --------------- assign_control_domain
- --------------- assign_domain
- --------------- matrix
- --------------- unassign_adapter
- ----------------unassign_control_domain
- ----------------unassign_domain
+ ------------ [$uuid2]
+ --------------- assign_adapter
+ --------------- assign_control_domain
+ --------------- assign_domain
+ --------------- matrix
+ --------------- unassign_adapter
+ ----------------unassign_control_domain
+ ----------------unassign_domain
- ------------ [$uuid3]
- --------------- assign_adapter
- --------------- assign_control_domain
- --------------- assign_domain
- --------------- matrix
- --------------- unassign_adapter
- ----------------unassign_control_domain
- ----------------unassign_domain
+ ------------ [$uuid3]
+ --------------- assign_adapter
+ --------------- assign_control_domain
+ --------------- assign_domain
+ --------------- matrix
+ --------------- unassign_adapter
+ ----------------unassign_control_domain
+ ----------------unassign_domain
4. The administrator now needs to configure the matrixes for the mediated
devices $uuid1 (for Guest1), $uuid2 (for Guest2) and $uuid3 (for Guest3).
- This is how the matrix is configured for Guest1:
+ This is how the matrix is configured for Guest1::
echo 5 > assign_adapter
echo 6 > assign_adapter
echo 4 > assign_domain
echo 0xab > assign_domain
- Control domains can similarly be assigned using the assign_control_domain
- sysfs file.
+ Control domains can similarly be assigned using the assign_control_domain
+ sysfs file.
- If a mistake is made configuring an adapter, domain or control domain,
- you can use the unassign_xxx files to unassign the adapter, domain or
- control domain.
+ If a mistake is made configuring an adapter, domain or control domain,
+ you can use the unassign_xxx files to unassign the adapter, domain or
+ control domain.
- To display the matrix configuration for Guest1:
+ To display the matrix configuration for Guest1::
- cat matrix
+ cat matrix
- This is how the matrix is configured for Guest2:
+ This is how the matrix is configured for Guest2::
echo 5 > assign_adapter
echo 0x47 > assign_domain
echo 0xff > assign_domain
- This is how the matrix is configured for Guest3:
+ This is how the matrix is configured for Guest3::
echo 6 > assign_adapter
echo 0x47 > assign_domain
@@ -783,24 +811,24 @@ These are the steps:
configured for the system. If a control domain number higher than the maximum
is specified, the operation will terminate with an error (ENODEV).
-5. Start Guest1:
+5. Start Guest1::
- /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
- -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
+ /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
+ -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
-7. Start Guest2:
+7. Start Guest2::
- /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
- -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
+ /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
+ -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
-7. Start Guest3:
+7. Start Guest3::
- /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
- -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
+ /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
+ -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
When the guest is shut down, the mediated matrix devices may be removed.
-Using our example again, to remove the mediated matrix device $uuid1:
+Using our example again, to remove the mediated matrix device $uuid1::
/sys/devices/vfio_ap/matrix/
--- [mdev_supported_types]
@@ -809,18 +837,19 @@ Using our example again, to remove the mediated matrix device $uuid1:
------------ [$uuid1]
--------------- remove
+::
echo 1 > remove
- This will remove all of the mdev matrix device's sysfs structures including
- the mdev device itself. To recreate and reconfigure the mdev matrix device,
- all of the steps starting with step 3 will have to be performed again. Note
- that the remove will fail if a guest using the mdev is still running.
+This will remove all of the mdev matrix device's sysfs structures including
+the mdev device itself. To recreate and reconfigure the mdev matrix device,
+all of the steps starting with step 3 will have to be performed again. Note
+that the remove will fail if a guest using the mdev is still running.
- It is not necessary to remove an mdev matrix device, but one may want to
- remove it if no guest will use it during the remaining lifetime of the linux
- host. If the mdev matrix device is removed, one may want to also reconfigure
- the pool of adapters and queues reserved for use by the default drivers.
+It is not necessary to remove an mdev matrix device, but one may want to
+remove it if no guest will use it during the remaining lifetime of the linux
+host. If the mdev matrix device is removed, one may want to also reconfigure
+the pool of adapters and queues reserved for use by the default drivers.
Limitations
===========
diff --git a/Documentation/s390/vfio-ccw.txt b/Documentation/s390/vfio-ccw.rst
similarity index 89%
rename from Documentation/s390/vfio-ccw.txt
rename to Documentation/s390/vfio-ccw.rst
index 2be11ad864ff..1f6d0b56d53e 100644
--- a/Documentation/s390/vfio-ccw.txt
+++ b/Documentation/s390/vfio-ccw.rst
@@ -1,3 +1,4 @@
+==================================
vfio-ccw: the basic infrastructure
==================================
@@ -11,9 +12,11 @@ virtual machine, while vfio is the means.
Different than other hardware architectures, s390 has defined a unified
I/O access method, which is so called Channel I/O. It has its own access
patterns:
+
- Channel programs run asynchronously on a separate (co)processor.
- The channel subsystem will access any memory designated by the caller
in the channel program directly, i.e. there is no iommu involved.
+
Thus when we introduce vfio support for these devices, we realize it
with a mediated device (mdev) implementation. The vfio mdev will be
added to an iommu group, so as to make itself able to be managed by the
@@ -24,6 +27,7 @@ to perform I/O instructions.
This document does not intend to explain the s390 I/O architecture in
every detail. More information/reference could be found here:
+
- A good start to know Channel I/O in general:
https://en.wikipedia.org/wiki/Channel_I/O
- s390 architecture:
@@ -80,6 +84,7 @@ until interrupted. The I/O completion result is received by the
interrupt handler in the form of interrupt response block (IRB).
Back to vfio-ccw, in short:
+
- ORBs and channel programs are built in guest kernel (with guest
physical addresses).
- ORBs and channel programs are passed to the host kernel.
@@ -106,6 +111,7 @@ it gets sent to hardware.
Within this implementation, we have two drivers for two types of
devices:
+
- The vfio_ccw driver for the physical subchannel device.
This is an I/O subchannel driver for the real subchannel device. It
realizes a group of callbacks and registers to the mdev framework as a
@@ -137,7 +143,7 @@ devices:
vfio_pin_pages and a vfio_unpin_pages interfaces from the vfio iommu
backend for the physical devices to pin and unpin pages by demand.
-Below is a high Level block diagram.
+Below is a high Level block diagram::
+-------------+
| |
@@ -158,6 +164,7 @@ Below is a high Level block diagram.
+-------------+
The process of how these work together.
+
1. vfio_ccw.ko drives the physical I/O subchannel, and registers the
physical device (with callbacks) to mdev framework.
When vfio_ccw probing the subchannel device, it registers device
@@ -178,17 +185,17 @@ vfio-ccw I/O region
An I/O region is used to accept channel program request from user
space and store I/O interrupt result for user space to retrieve. The
-definition of the region is:
+definition of the region is::
-struct ccw_io_region {
-#define ORB_AREA_SIZE 12
- __u8 orb_area[ORB_AREA_SIZE];
-#define SCSW_AREA_SIZE 12
- __u8 scsw_area[SCSW_AREA_SIZE];
-#define IRB_AREA_SIZE 96
- __u8 irb_area[IRB_AREA_SIZE];
- __u32 ret_code;
-} __packed;
+ struct ccw_io_region {
+ #define ORB_AREA_SIZE 12
+ __u8 orb_area[ORB_AREA_SIZE];
+ #define SCSW_AREA_SIZE 12
+ __u8 scsw_area[SCSW_AREA_SIZE];
+ #define IRB_AREA_SIZE 96
+ __u8 irb_area[IRB_AREA_SIZE];
+ __u32 ret_code;
+ } __packed;
While starting an I/O request, orb_area should be filled with the
guest ORB, and scsw_area should be filled with the SCSW of the Virtual
@@ -205,7 +212,7 @@ vfio-ccw follows what vfio-pci did on the s390 platform and uses
vfio-iommu-type1 as the vfio iommu backend.
* CCW translation APIs
- A group of APIs (start with 'cp_') to do CCW translation. The CCWs
+ A group of APIs (start with `cp_`) to do CCW translation. The CCWs
passed in by a user space program are organized with their guest
physical memory addresses. These APIs will copy the CCWs into kernel
space, and assemble a runnable kernel channel program by updating the
@@ -217,12 +224,14 @@ vfio-iommu-type1 as the vfio iommu backend.
This driver utilizes the CCW translation APIs and introduces
vfio_ccw, which is the driver for the I/O subchannel devices you want
to pass through.
- vfio_ccw implements the following vfio ioctls:
+ vfio_ccw implements the following vfio ioctls::
+
VFIO_DEVICE_GET_INFO
VFIO_DEVICE_GET_IRQ_INFO
VFIO_DEVICE_GET_REGION_INFO
VFIO_DEVICE_RESET
VFIO_DEVICE_SET_IRQS
+
This provides an I/O region, so that the user space program can pass a
channel program to the kernel, to do further CCW translation before
issuing them to a real device.
@@ -236,32 +245,49 @@ bit more detail how an I/O request triggered by the QEMU guest will be
handled (without error handling).
Explanation:
-Q1-Q7: QEMU side process.
-K1-K5: Kernel side process.
-Q1. Get I/O region info during initialization.
-Q2. Setup event notifier and handler to handle I/O completion.
+- Q1-Q7: QEMU side process.
+- K1-K5: Kernel side process.
+
+Q1.
+ Get I/O region info during initialization.
+
+Q2.
+ Setup event notifier and handler to handle I/O completion.
... ...
-Q3. Intercept a ssch instruction.
-Q4. Write the guest channel program and ORB to the I/O region.
- K1. Copy from guest to kernel.
- K2. Translate the guest channel program to a host kernel space
- channel program, which becomes runnable for a real device.
- K3. With the necessary information contained in the orb passed in
- by QEMU, issue the ccwchain to the device.
- K4. Return the ssch CC code.
-Q5. Return the CC code to the guest.
+Q3.
+ Intercept a ssch instruction.
+Q4.
+ Write the guest channel program and ORB to the I/O region.
+
+ K1.
+ Copy from guest to kernel.
+ K2.
+ Translate the guest channel program to a host kernel space
+ channel program, which becomes runnable for a real device.
+ K3.
+ With the necessary information contained in the orb passed in
+ by QEMU, issue the ccwchain to the device.
+ K4.
+ Return the ssch CC code.
+Q5.
+ Return the CC code to the guest.
... ...
- K5. Interrupt handler gets the I/O result and write the result to
- the I/O region.
- K6. Signal QEMU to retrieve the result.
-Q6. Get the signal and event handler reads out the result from the I/O
+ K5.
+ Interrupt handler gets the I/O result and write the result to
+ the I/O region.
+ K6.
+ Signal QEMU to retrieve the result.
+
+Q6.
+ Get the signal and event handler reads out the result from the I/O
region.
-Q7. Update the irb for the guest.
+Q7.
+ Update the irb for the guest.
Limitations
-----------
@@ -295,6 +321,6 @@ Reference
1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832)
2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204)
3. https://en.wikipedia.org/wiki/Channel_I/O
-4. Documentation/s390/cds.txt
+4. Documentation/s390/cds.rst
5. Documentation/vfio.txt
6. Documentation/vfio-mediated-device.txt
diff --git a/Documentation/s390/zfcpdump.txt b/Documentation/s390/zfcpdump.rst
similarity index 97%
rename from Documentation/s390/zfcpdump.txt
rename to Documentation/s390/zfcpdump.rst
index b064aa59714d..54e8e7caf7e7 100644
--- a/Documentation/s390/zfcpdump.txt
+++ b/Documentation/s390/zfcpdump.rst
@@ -1,4 +1,6 @@
+==================================
The s390 SCSI dump tool (zfcpdump)
+==================================
System z machines (z900 or higher) provide hardware support for creating system
dumps on SCSI disks. The dump process is initiated by booting a dump tool, which
diff --git a/MAINTAINERS b/MAINTAINERS
index 72d1e5da0779..dce53f6414b6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13738,7 +13738,7 @@ L: [email protected]
L: [email protected]
S: Supported
F: drivers/s390/cio/vfio_ccw*
-F: Documentation/s390/vfio-ccw.txt
+F: Documentation/s390/vfio-ccw.rst
F: include/uapi/linux/vfio_ccw.h
S390 ZCRYPT DRIVER
@@ -13758,7 +13758,7 @@ S: Supported
F: drivers/s390/crypto/vfio_ap_drv.c
F: drivers/s390/crypto/vfio_ap_private.h
F: drivers/s390/crypto/vfio_ap_ops.c
-F: Documentation/s390/vfio-ap.txt
+F: Documentation/s390/vfio-ap.rst
S390 ZFCP DRIVER
M: Steffen Maier <[email protected]>
diff --git a/arch/s390/Kconfig b/arch/s390/Kconfig
index 067713f7a377..bb528dcdf4a5 100644
--- a/arch/s390/Kconfig
+++ b/arch/s390/Kconfig
@@ -833,9 +833,9 @@ config CRASH_DUMP
Crash dump kernels are loaded in the main kernel with kexec-tools
into a specially reserved region and then later executed after
a crash by kdump/kexec.
- Refer to <file:Documentation/s390/zfcpdump.txt> for more details on this.
+ Refer to <file:Documentation/s390/zfcpdump.rst> for more details on this.
This option also enables s390 zfcpdump.
- See also <file:Documentation/s390/zfcpdump.txt>
+ See also <file:Documentation/s390/zfcpdump.rst>
endmenu
diff --git a/arch/s390/include/asm/debug.h b/arch/s390/include/asm/debug.h
index c305d39f5016..b94783f71322 100644
--- a/arch/s390/include/asm/debug.h
+++ b/arch/s390/include/asm/debug.h
@@ -152,7 +152,7 @@ static inline debug_entry_t *debug_text_event(debug_info_t *id, int level,
/*
* IMPORTANT: Use "%s" in sprintf format strings with care! Only pointers are
- * stored in the s390dbf. See Documentation/s390/s390dbf.txt for more details!
+ * stored in the s390dbf. See Documentation/s390/s390dbf.rst for more details!
*/
extern debug_entry_t *
__debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
@@ -210,7 +210,7 @@ static inline debug_entry_t *debug_text_exception(debug_info_t *id, int level,
/*
* IMPORTANT: Use "%s" in sprintf format strings with care! Only pointers are
- * stored in the s390dbf. See Documentation/s390/s390dbf.txt for more details!
+ * stored in the s390dbf. See Documentation/s390/s390dbf.rst for more details!
*/
extern debug_entry_t *
__debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
diff --git a/drivers/s390/char/zcore.c b/drivers/s390/char/zcore.c
index 405a60538630..08f812475f5e 100644
--- a/drivers/s390/char/zcore.c
+++ b/drivers/s390/char/zcore.c
@@ -4,7 +4,7 @@
* dumps on SCSI disks (zfcpdump). The "zcore/mem" debugfs file shows the same
* dump format as s390 standalone dumps.
*
- * For more information please refer to Documentation/s390/zfcpdump.txt
+ * For more information please refer to Documentation/s390/zfcpdump.rst
*
* Copyright IBM Corp. 2003, 2008
* Author(s): Michael Holzheu
--
2.21.0
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 <[email protected]>
---
.../{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, [email protected]
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, [email protected]
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, [email protected]
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
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 <[email protected]>
---
.../admin-guide/kernel-parameters.txt | 2 +-
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} | 79 +--
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 +-
.../fb/{matroxfb.txt => matroxfb.rst} | 528 +++++++++---------
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/{pvr2fb.txt => pvr2fb.rst} | 55 +-
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 ++-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
.../fb/{sh7760fb.txt => sh7760fb.rst} | 153 +++--
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/{sstfb.txt => sstfb.rst} | 231 ++++----
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.txt => viafb.rst} | 393 +++++++------
.../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +-
MAINTAINERS | 10 +-
drivers/tty/Kconfig | 2 +-
drivers/video/fbdev/Kconfig | 24 +-
drivers/video/fbdev/matrox/matroxfb_base.c | 2 +-
drivers/video/fbdev/pxafb.c | 2 +-
drivers/video/fbdev/sh7760fb.c | 2 +-
42 files changed, 1535 insertions(+), 1247 deletions(-)
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%)
rename Documentation/fb/{matroxfb.txt => matroxfb.rst} (32%)
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
rename Documentation/fb/{pvr2fb.txt => pvr2fb.rst} (36%)
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
rename Documentation/fb/{sh7760fb.txt => sh7760fb.rst} (39%)
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
rename Documentation/fb/{sstfb.txt => sstfb.rst} (28%)
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%)
rename Documentation/fb/{viafb.txt => viafb.rst} (18%)
rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index a2c36cbad438..d5f01f7eb5ca 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -5046,7 +5046,7 @@
vector=percpu: enable percpu vector domain
video= [FB] Frame buffer configuration
- See Documentation/fb/modedb.txt.
+ See Documentation/fb/modedb.rst.
video.brightness_switch_enabled= [0,1]
If set to 1, on receiving an ACPI notify event
diff --git a/Documentation/fb/api.txt b/Documentation/fb/api.rst
similarity index 97%
rename from Documentation/fb/api.txt
rename to Documentation/fb/api.rst
index d52cf1e3b975..79ec33dded74 100644
--- a/Documentation/fb/api.txt
+++ b/Documentation/fb/api.rst
@@ -1,5 +1,6 @@
- The Frame Buffer Device API
- ---------------------------
+===========================
+The Frame Buffer Device API
+===========================
Last revised: June 21, 2011
@@ -21,13 +22,13 @@ deal with different behaviours.
---------------
Device and driver capabilities are reported in the fixed screen information
-capabilities field.
+capabilities field::
-struct fb_fix_screeninfo {
+ struct fb_fix_screeninfo {
...
__u16 capabilities; /* see FB_CAP_* */
...
-};
+ };
Application should use those capabilities to find out what features they can
expect from the device and driver.
@@ -151,9 +152,9 @@ fb_fix_screeninfo and fb_var_screeninfo structure respectively.
struct fb_fix_screeninfo stores device independent unchangeable information
about the frame buffer device and the current format. Those information can't
be directly modified by applications, but can be changed by the driver when an
-application modifies the format.
+application modifies the format::
-struct fb_fix_screeninfo {
+ struct fb_fix_screeninfo {
char id[16]; /* identification string eg "TT Builtin" */
unsigned long smem_start; /* Start of frame buffer mem */
/* (physical address) */
@@ -172,13 +173,13 @@ struct fb_fix_screeninfo {
/* specific chip/card we have */
__u16 capabilities; /* see FB_CAP_* */
__u16 reserved[2]; /* Reserved for future compatibility */
-};
+ };
struct fb_var_screeninfo stores device independent changeable information
about a frame buffer device, its current format and video mode, as well as
-other miscellaneous parameters.
+other miscellaneous parameters::
-struct fb_var_screeninfo {
+ struct fb_var_screeninfo {
__u32 xres; /* visible resolution */
__u32 yres;
__u32 xres_virtual; /* virtual resolution */
@@ -216,7 +217,7 @@ struct fb_var_screeninfo {
__u32 rotate; /* angle we rotate counter clockwise */
__u32 colorspace; /* colorspace for FOURCC-based modes */
__u32 reserved[4]; /* Reserved for future compatibility */
-};
+ };
To modify variable information, applications call the FBIOPUT_VSCREENINFO
ioctl with a pointer to a fb_var_screeninfo structure. If the call is
@@ -255,14 +256,14 @@ monochrome, grayscale or pseudocolor visuals, although this is not required.
- For truecolor and directcolor formats, applications set the grayscale field
to zero, and the red, blue, green and transp fields to describe the layout of
- color components in memory.
+ color components in memory::
-struct fb_bitfield {
+ struct fb_bitfield {
__u32 offset; /* beginning of bitfield */
__u32 length; /* length of bitfield */
__u32 msb_right; /* != 0 : Most significant bit is */
/* right */
-};
+ };
Pixel values are bits_per_pixel wide and are split in non-overlapping red,
green, blue and alpha (transparency) components. Location and size of each
diff --git a/Documentation/fb/arkfb.txt b/Documentation/fb/arkfb.rst
similarity index 92%
rename from Documentation/fb/arkfb.txt
rename to Documentation/fb/arkfb.rst
index e8487a9d6a05..aeca8773dd7e 100644
--- a/Documentation/fb/arkfb.txt
+++ b/Documentation/fb/arkfb.rst
@@ -1,6 +1,6 @@
-
- arkfb - fbdev driver for ARK Logic chips
- ========================================
+========================================
+arkfb - fbdev driver for ARK Logic chips
+========================================
Supported Hardware
@@ -47,7 +47,7 @@ Missing Features
(alias TODO list)
* secondary (not initialized by BIOS) device support
- * big endian support
+ * big endian support
* DPMS support
* MMIO support
* interlaced mode variant
diff --git a/Documentation/fb/aty128fb.txt b/Documentation/fb/aty128fb.rst
similarity index 61%
rename from Documentation/fb/aty128fb.txt
rename to Documentation/fb/aty128fb.rst
index b605204fcfe1..3f107718f933 100644
--- a/Documentation/fb/aty128fb.txt
+++ b/Documentation/fb/aty128fb.rst
@@ -1,8 +1,9 @@
-[This file is cloned from VesaFB/matroxfb]
-
+=================
What is aty128fb?
=================
+.. [This file is cloned from VesaFB/matroxfb]
+
This is a driver for a graphic framebuffer for ATI Rage128 based devices
on Intel and PPC boxes.
@@ -24,15 +25,15 @@ How to use it?
==============
Switching modes is done using the video=aty128fb:<resolution>... modedb
-boot parameter or using `fbset' program.
+boot parameter or using `fbset` program.
-See Documentation/fb/modedb.txt for more information on modedb
+See Documentation/fb/modedb.rst for more information on modedb
resolutions.
You should compile in both vgacon (to boot if you remove your Rage128 from
box) and aty128fb (for graphics mode). You should not compile-in vesafb
-unless you have primary display on non-Rage128 VBE2.0 device (see
-Documentation/fb/vesafb.txt for details).
+unless you have primary display on non-Rage128 VBE2.0 device (see
+Documentation/fb/vesafb.rst for details).
X11
@@ -48,16 +49,18 @@ Configuration
=============
You can pass kernel command line options to vesafb with
-`video=aty128fb:option1,option2:value2,option3' (multiple options should
-be separated by comma, values are separated from options by `:').
+`video=aty128fb:option1,option2:value2,option3` (multiple options should
+be separated by comma, values are separated from options by `:`).
Accepted options:
-noaccel - do not use acceleration engine. It is default.
-accel - use acceleration engine. Not finished.
-vmode:x - chooses PowerMacintosh video mode <x>. Deprecated.
-cmode:x - chooses PowerMacintosh colour mode <x>. Deprecated.
-<XxX@X> - selects startup videomode. See modedb.txt for detailed
- explanation. Default is 640x480x8bpp.
+========= =======================================================
+noaccel do not use acceleration engine. It is default.
+accel use acceleration engine. Not finished.
+vmode:x chooses PowerMacintosh video mode <x>. Deprecated.
+cmode:x chooses PowerMacintosh colour mode <x>. Deprecated.
+<XxX@X> selects startup videomode. See modedb.txt for detailed
+ explanation. Default is 640x480x8bpp.
+========= =======================================================
Limitations
@@ -65,8 +68,8 @@ Limitations
There are known and unknown bugs, features and misfeatures.
Currently there are following known bugs:
- + This driver is still experimental and is not finished. Too many
+
+ - This driver is still experimental and is not finished. Too many
bugs/errata to list here.
---
Brad Douglas <[email protected]>
diff --git a/Documentation/fb/cirrusfb.txt b/Documentation/fb/cirrusfb.rst
similarity index 75%
rename from Documentation/fb/cirrusfb.txt
rename to Documentation/fb/cirrusfb.rst
index f75950d330a4..8c3e6c6cb114 100644
--- a/Documentation/fb/cirrusfb.txt
+++ b/Documentation/fb/cirrusfb.rst
@@ -1,32 +1,32 @@
+============================================
+Framebuffer driver for Cirrus Logic chipsets
+============================================
- Framebuffer driver for Cirrus Logic chipsets
- Copyright 1999 Jeff Garzik <[email protected]>
+Copyright 1999 Jeff Garzik <[email protected]>
-
-{ just a little something to get people going; contributors welcome! }
-
+.. just a little something to get people going; contributors welcome!
Chip families supported:
- SD64
- Piccolo
- Picasso
- Spectrum
- Alpine (GD-543x/4x)
- Picasso4 (GD-5446)
- GD-5480
- Laguna (GD-546x)
+ - SD64
+ - Piccolo
+ - Picasso
+ - Spectrum
+ - Alpine (GD-543x/4x)
+ - Picasso4 (GD-5446)
+ - GD-5480
+ - Laguna (GD-546x)
Bus's supported:
- PCI
- Zorro
+ - PCI
+ - Zorro
Architectures supported:
- i386
- Alpha
- PPC (Motorola Powerstack)
- m68k (Amiga)
+ - i386
+ - Alpha
+ - PPC (Motorola Powerstack)
+ - m68k (Amiga)
@@ -34,10 +34,9 @@ Default video modes
-------------------
At the moment, there are two kernel command line arguments supported:
-mode:640x480
-mode:800x600
- or
-mode:1024x768
+- mode:640x480
+- mode:800x600
+- mode:1024x768
Full support for startup video modes (modedb) will be integrated soon.
@@ -93,5 +92,3 @@ Version 1.9.4
Version 1.9.3
-------------
* Bundled with kernel 2.3.14-pre1 or later.
-
-
diff --git a/Documentation/fb/cmap_xfbdev.txt b/Documentation/fb/cmap_xfbdev.rst
similarity index 50%
rename from Documentation/fb/cmap_xfbdev.txt
rename to Documentation/fb/cmap_xfbdev.rst
index 55e1f0a3d2b4..5db5e9787361 100644
--- a/Documentation/fb/cmap_xfbdev.txt
+++ b/Documentation/fb/cmap_xfbdev.rst
@@ -1,26 +1,29 @@
+==========================
Understanding fbdev's cmap
---------------------------
+==========================
These notes explain how X's dix layer uses fbdev's cmap structures.
-*. example of relevant structures in fbdev as used for a 3-bit grayscale cmap
-struct fb_var_screeninfo {
- .bits_per_pixel = 8,
- .grayscale = 1,
- .red = { 4, 3, 0 },
- .green = { 0, 0, 0 },
- .blue = { 0, 0, 0 },
-}
-struct fb_fix_screeninfo {
- .visual = FB_VISUAL_STATIC_PSEUDOCOLOR,
-}
-for (i = 0; i < 8; i++)
+- example of relevant structures in fbdev as used for a 3-bit grayscale cmap::
+
+ struct fb_var_screeninfo {
+ .bits_per_pixel = 8,
+ .grayscale = 1,
+ .red = { 4, 3, 0 },
+ .green = { 0, 0, 0 },
+ .blue = { 0, 0, 0 },
+ }
+ struct fb_fix_screeninfo {
+ .visual = FB_VISUAL_STATIC_PSEUDOCOLOR,
+ }
+ for (i = 0; i < 8; i++)
info->cmap.red[i] = (((2*i)+1)*(0xFFFF))/16;
-memcpy(info->cmap.green, info->cmap.red, sizeof(u16)*8);
-memcpy(info->cmap.blue, info->cmap.red, sizeof(u16)*8);
+ memcpy(info->cmap.green, info->cmap.red, sizeof(u16)*8);
+ memcpy(info->cmap.blue, info->cmap.red, sizeof(u16)*8);
-*. X11 apps do something like the following when trying to use grayscale.
-for (i=0; i < 8; i++) {
+- X11 apps do something like the following when trying to use grayscale::
+
+ for (i=0; i < 8; i++) {
char colorspec[64];
memset(colorspec,0,64);
sprintf(colorspec, "rgb:%x/%x/%x", i*36,i*36,i*36);
@@ -28,26 +31,26 @@ for (i=0; i < 8; i++) {
printf("Can't get color %s\n",colorspec);
XAllocColor(outputDisplay, testColormap, &wantedColor);
grays[i] = wantedColor;
-}
+ }
+
There's also named equivalents like gray1..x provided you have an rgb.txt.
Somewhere in X's callchain, this results in a call to X code that handles the
colormap. For example, Xfbdev hits the following:
-xc-011010/programs/Xserver/dix/colormap.c:
+xc-011010/programs/Xserver/dix/colormap.c::
-FindBestPixel(pentFirst, size, prgb, channel)
+ FindBestPixel(pentFirst, size, prgb, channel)
-dr = (long) pent->co.local.red - prgb->red;
-dg = (long) pent->co.local.green - prgb->green;
-db = (long) pent->co.local.blue - prgb->blue;
-sq = dr * dr;
-UnsignedToBigNum (sq, &sum);
-BigNumAdd (&sum, &temp, &sum);
+ dr = (long) pent->co.local.red - prgb->red;
+ dg = (long) pent->co.local.green - prgb->green;
+ db = (long) pent->co.local.blue - prgb->blue;
+ sq = dr * dr;
+ UnsignedToBigNum (sq, &sum);
+ BigNumAdd (&sum, &temp, &sum);
co.local.red are entries that were brought in through FBIOGETCMAP which come
directly from the info->cmap.red that was listed above. The prgb is the rgb
that the app wants to match to. The above code is doing what looks like a least
squares matching function. That's why the cmap entries can't be set to the left
hand side boundaries of a color range.
-
diff --git a/Documentation/fb/deferred_io.txt b/Documentation/fb/deferred_io.rst
similarity index 86%
rename from Documentation/fb/deferred_io.txt
rename to Documentation/fb/deferred_io.rst
index 748328370250..7300cff255a3 100644
--- a/Documentation/fb/deferred_io.txt
+++ b/Documentation/fb/deferred_io.rst
@@ -1,5 +1,6 @@
+===========
Deferred IO
------------
+===========
Deferred IO is a way to delay and repurpose IO. It uses host memory as a
buffer and the MMU pagefault as a pretrigger for when to perform the device
@@ -16,7 +17,7 @@ works:
- app continues writing to that page with no additional cost. this is
the key benefit.
- the workqueue task comes in and mkcleans the pages on the list, then
- completes the work associated with updating the framebuffer. this is
+ completes the work associated with updating the framebuffer. this is
the real work talking to the device.
- app tries to write to the address (that has now been mkcleaned)
- get pagefault and the above sequence occurs again
@@ -47,29 +48,32 @@ How to use it: (for fbdev drivers)
----------------------------------
The following example may be helpful.
-1. Setup your structure. Eg:
+1. Setup your structure. Eg::
-static struct fb_deferred_io hecubafb_defio = {
- .delay = HZ,
- .deferred_io = hecubafb_dpy_deferred_io,
-};
+ static struct fb_deferred_io hecubafb_defio = {
+ .delay = HZ,
+ .deferred_io = hecubafb_dpy_deferred_io,
+ };
The delay is the minimum delay between when the page_mkwrite trigger occurs
and when the deferred_io callback is called. The deferred_io callback is
explained below.
-2. Setup your deferred IO callback. Eg:
-static void hecubafb_dpy_deferred_io(struct fb_info *info,
- struct list_head *pagelist)
+2. Setup your deferred IO callback. Eg::
+
+ static void hecubafb_dpy_deferred_io(struct fb_info *info,
+ struct list_head *pagelist)
The deferred_io callback is where you would perform all your IO to the display
device. You receive the pagelist which is the list of pages that were written
to during the delay. You must not modify this list. This callback is called
from a workqueue.
-3. Call init
+3. Call init::
+
info->fbdefio = &hecubafb_defio;
fb_deferred_io_init(info);
-4. Call cleanup
+4. Call cleanup::
+
fb_deferred_io_cleanup(info);
diff --git a/Documentation/fb/efifb.txt b/Documentation/fb/efifb.rst
similarity index 75%
rename from Documentation/fb/efifb.txt
rename to Documentation/fb/efifb.rst
index 1a85c1bdaf38..04840331a00e 100644
--- a/Documentation/fb/efifb.txt
+++ b/Documentation/fb/efifb.rst
@@ -1,6 +1,6 @@
-
+==============
What is efifb?
-===============
+==============
This is a generic EFI platform driver for Intel based Apple computers.
efifb is only for EFI booted Intel Macs.
@@ -8,16 +8,17 @@ efifb is only for EFI booted Intel Macs.
Supported Hardware
==================
-iMac 17"/20"
-Macbook
-Macbook Pro 15"/17"
-MacMini
+- iMac 17"/20"
+- Macbook
+- Macbook Pro 15"/17"
+- MacMini
How to use it?
==============
efifb does not have any kind of autodetection of your machine.
-You have to add the following kernel parameters in your elilo.conf:
+You have to add the following kernel parameters in your elilo.conf::
+
Macbook :
video=efifb:macbook
MacMini :
@@ -29,9 +30,10 @@ You have to add the following kernel parameters in your elilo.conf:
Accepted options:
+======= ===========================================================
nowc Don't map the framebuffer write combined. This can be used
to workaround side-effects and slowdowns on other CPU cores
when large amounts of console data are written.
+======= ===========================================================
---
Edgar Hucek <[email protected]>
diff --git a/Documentation/fb/ep93xx-fb.txt b/Documentation/fb/ep93xx-fb.rst
similarity index 85%
rename from Documentation/fb/ep93xx-fb.txt
rename to Documentation/fb/ep93xx-fb.rst
index 5af1bd9effae..6f7767926d1a 100644
--- a/Documentation/fb/ep93xx-fb.txt
+++ b/Documentation/fb/ep93xx-fb.rst
@@ -4,7 +4,7 @@ Driver for EP93xx LCD controller
The EP93xx LCD controller can drive both standard desktop monitors and
embedded LCD displays. If you have a standard desktop monitor then you
-can use the standard Linux video mode database. In your board file:
+can use the standard Linux video mode database. In your board file::
static struct ep93xxfb_mach_info some_board_fb_info = {
.num_modes = EP93XXFB_USE_MODEDB,
@@ -12,7 +12,7 @@ can use the standard Linux video mode database. In your board file:
};
If you have an embedded LCD display then you need to define a video
-mode for it as follows:
+mode for it as follows::
static struct fb_videomode some_board_video_modes[] = {
{
@@ -23,11 +23,11 @@ mode for it as follows:
Note that the pixel clock value is in pico-seconds. You can use the
KHZ2PICOS macro to convert the pixel clock value. Most other values
-are in pixel clocks. See Documentation/fb/framebuffer.txt for further
+are in pixel clocks. See Documentation/fb/framebuffer.rst for further
details.
The ep93xxfb_mach_info structure for your board should look like the
-following:
+following::
static struct ep93xxfb_mach_info some_board_fb_info = {
.num_modes = ARRAY_SIZE(some_board_video_modes),
@@ -37,7 +37,7 @@ following:
};
The framebuffer device can be registered by adding the following to
-your board initialisation function:
+your board initialisation function::
ep93xx_register_fb(&some_board_fb_info);
@@ -50,6 +50,7 @@ to configure the controller. The video attributes flags are fully
documented in section 7 of the EP93xx users' guide. The following
flags are available:
+=============================== ==========================================
EP93XXFB_PCLK_FALLING Clock data on the falling edge of the
pixel clock. The default is to clock
data on the rising edge.
@@ -62,10 +63,12 @@ EP93XXFB_SYNC_HORIZ_HIGH Horizontal sync is active high. By
EP93XXFB_SYNC_VERT_HIGH Vertical sync is active high. By
default the vertical sync is active high.
+=============================== ==========================================
The physical address of the framebuffer can be controlled using the
following flags:
+=============================== ======================================
EP93XXFB_USE_SDCSN0 Use SDCSn[0] for the framebuffer. This
is the default setting.
@@ -74,6 +77,7 @@ EP93XXFB_USE_SDCSN1 Use SDCSn[1] for the framebuffer.
EP93XXFB_USE_SDCSN2 Use SDCSn[2] for the framebuffer.
EP93XXFB_USE_SDCSN3 Use SDCSn[3] for the framebuffer.
+=============================== ======================================
==================
Platform callbacks
@@ -87,7 +91,7 @@ blanked or unblanked.
The setup and teardown devices pass the platform_device structure as
an argument. The fb_info and ep93xxfb_mach_info structures can be
-obtained as follows:
+obtained as follows::
static int some_board_fb_setup(struct platform_device *pdev)
{
@@ -101,17 +105,17 @@ obtained as follows:
Setting the video mode
======================
-The video mode is set using the following syntax:
+The video mode is set using the following syntax::
video=XRESxYRES[-BPP][@REFRESH]
If the EP93xx video driver is built-in then the video mode is set on
-the Linux kernel command line, for example:
+the Linux kernel command line, for example::
video=ep93xx-fb:800x600-16@60
If the EP93xx video driver is built as a module then the video mode is
-set when the module is installed:
+set when the module is installed::
modprobe ep93xx-fb video=320x240
@@ -121,13 +125,14 @@ Screenpage bug
At least on the EP9315 there is a silicon bug which causes bit 27 of
the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
-an unofficial errata for this bug at:
+an unofficial errata for this bug at::
+
http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2
By default the EP93xx framebuffer driver checks if the allocated physical
address has bit 27 set. If it does, then the memory is freed and an
error is returned. The check can be disabled by adding the following
-option when loading the driver:
+option when loading the driver::
ep93xx-fb.check_screenpage_bug=0
diff --git a/Documentation/fb/fbcon.txt b/Documentation/fb/fbcon.rst
similarity index 69%
rename from Documentation/fb/fbcon.txt
rename to Documentation/fb/fbcon.rst
index 60a5ec04e8f0..cfb9f7c38f18 100644
--- a/Documentation/fb/fbcon.txt
+++ b/Documentation/fb/fbcon.rst
@@ -1,39 +1,41 @@
+=======================
The Framebuffer Console
=======================
- The framebuffer console (fbcon), as its name implies, is a text
+The framebuffer console (fbcon), as its name implies, is a text
console running on top of the framebuffer device. It has the functionality of
any standard text console driver, such as the VGA console, with the added
features that can be attributed to the graphical nature of the framebuffer.
- In the x86 architecture, the framebuffer console is optional, and
+In the x86 architecture, the framebuffer console is optional, and
some even treat it as a toy. For other architectures, it is the only available
display device, text or graphical.
- What are the features of fbcon? The framebuffer console supports
+What are the features of fbcon? The framebuffer console supports
high resolutions, varying font types, display rotation, primitive multihead,
etc. Theoretically, multi-colored fonts, blending, aliasing, and any feature
made available by the underlying graphics card are also possible.
A. Configuration
+================
- The framebuffer console can be enabled by using your favorite kernel
+The framebuffer console can be enabled by using your favorite kernel
configuration tool. It is under Device Drivers->Graphics Support->Frame
buffer Devices->Console display driver support->Framebuffer Console Support.
Select 'y' to compile support statically or 'm' for module support. The
module will be fbcon.
- In order for fbcon to activate, at least one framebuffer driver is
+In order for fbcon to activate, at least one framebuffer driver is
required, so choose from any of the numerous drivers available. For x86
systems, they almost universally have VGA cards, so vga16fb and vesafb will
always be available. However, using a chipset-specific driver will give you
more speed and features, such as the ability to change the video mode
dynamically.
- To display the penguin logo, choose any logo available in Graphics
+To display the penguin logo, choose any logo available in Graphics
support->Bootup logo.
- Also, you will need to select at least one compiled-in font, but if
+Also, you will need to select at least one compiled-in font, but if
you don't do anything, the kernel configuration tool will select one for you,
usually an 8x16 font.
@@ -44,6 +46,7 @@ fortunate to have a driver that does not alter the graphics chip, then you
will still get a VGA console.
B. Loading
+==========
Possible scenarios:
@@ -72,33 +75,33 @@ Possible scenarios:
C. Boot options
- The framebuffer console has several, largely unknown, boot options
- that can change its behavior.
+ The framebuffer console has several, largely unknown, boot options
+ that can change its behavior.
1. fbcon=font:<name>
- Select the initial font to use. The value 'name' can be any of the
- compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
- PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
+ Select the initial font to use. The value 'name' can be any of the
+ compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
+ PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
Note, not all drivers can handle font with widths not divisible by 8,
- such as vga16fb.
+ such as vga16fb.
2. fbcon=scrollback:<value>[k]
- The scrollback buffer is memory that is used to preserve display
- contents that has already scrolled past your view. This is accessed
- by using the Shift-PageUp key combination. The value 'value' is any
- integer. It defaults to 32KB. The 'k' suffix is optional, and will
- multiply the 'value' by 1024.
+ The scrollback buffer is memory that is used to preserve display
+ contents that has already scrolled past your view. This is accessed
+ by using the Shift-PageUp key combination. The value 'value' is any
+ integer. It defaults to 32KB. The 'k' suffix is optional, and will
+ multiply the 'value' by 1024.
3. fbcon=map:<0123>
- This is an interesting option. It tells which driver gets mapped to
- which console. The value '0123' is a sequence that gets repeated until
- the total length is 64 which is the number of consoles available. In
- the above example, it is expanded to 012301230123... and the mapping
- will be:
+ This is an interesting option. It tells which driver gets mapped to
+ which console. The value '0123' is a sequence that gets repeated until
+ the total length is 64 which is the number of consoles available. In
+ the above example, it is expanded to 012301230123... and the mapping
+ will be::
tty | 1 2 3 4 5 6 7 8 9 ...
fb | 0 1 2 3 0 1 2 3 0 ...
@@ -126,20 +129,20 @@ C. Boot options
4. fbcon=rotate:<n>
- This option changes the orientation angle of the console display. The
- value 'n' accepts the following:
+ This option changes the orientation angle of the console display. The
+ value 'n' accepts the following:
- 0 - normal orientation (0 degree)
- 1 - clockwise orientation (90 degrees)
- 2 - upside down orientation (180 degrees)
- 3 - counterclockwise orientation (270 degrees)
+ - 0 - normal orientation (0 degree)
+ - 1 - clockwise orientation (90 degrees)
+ - 2 - upside down orientation (180 degrees)
+ - 3 - counterclockwise orientation (270 degrees)
The angle can be changed anytime afterwards by 'echoing' the same
numbers to any one of the 2 attributes found in
/sys/class/graphics/fbcon:
- rotate - rotate the display of the active console
- rotate_all - rotate the display of all consoles
+ - rotate - rotate the display of the active console
+ - rotate_all - rotate the display of all consoles
Console rotation will only become available if Framebuffer Console
Rotation support is compiled in your kernel.
@@ -177,9 +180,9 @@ Before going on to how to attach, detach and unload the framebuffer console, an
illustration of the dependencies may help.
The console layer, as with most subsystems, needs a driver that interfaces with
-the hardware. Thus, in a VGA console:
+the hardware. Thus, in a VGA console::
-console ---> VGA driver ---> hardware.
+ console ---> VGA driver ---> hardware.
Assuming the VGA driver can be unloaded, one must first unbind the VGA driver
from the console layer before unloading the driver. The VGA driver cannot be
@@ -187,9 +190,9 @@ unloaded if it is still bound to the console layer. (See
Documentation/console/console.txt for more information).
This is more complicated in the case of the framebuffer console (fbcon),
-because fbcon is an intermediate layer between the console and the drivers:
+because fbcon is an intermediate layer between the console and the drivers::
-console ---> fbcon ---> fbdev drivers ---> hardware
+ console ---> fbcon ---> fbdev drivers ---> hardware
The fbdev drivers cannot be unloaded if bound to fbcon, and fbcon cannot
be unloaded if it's bound to the console layer.
@@ -204,12 +207,12 @@ So, how do we unbind fbcon from the console? Part of the answer is in
Documentation/console/console.txt. To summarize:
Echo a value to the bind file that represents the framebuffer console
-driver. So assuming vtcon1 represents fbcon, then:
+driver. So assuming vtcon1 represents fbcon, then::
-echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to
- console layer
-echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from
- console layer
+ echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to
+ console layer
+ echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from
+ console layer
If fbcon is detached from the console layer, your boot console driver (which is
usually VGA text mode) will take over. A few drivers (rivafb and i810fb) will
@@ -223,19 +226,19 @@ restored properly. The following is one of the several methods that you can do:
2. In your kernel configuration, ensure that CONFIG_FRAMEBUFFER_CONSOLE is set
to 'y' or 'm'. Enable one or more of your favorite framebuffer drivers.
-3. Boot into text mode and as root run:
+3. Boot into text mode and as root run::
vbetool vbestate save > <vga state file>
- The above command saves the register contents of your graphics
- hardware to <vga state file>. You need to do this step only once as
- the state file can be reused.
+ The above command saves the register contents of your graphics
+ hardware to <vga state file>. You need to do this step only once as
+ the state file can be reused.
-4. If fbcon is compiled as a module, load fbcon by doing:
+4. If fbcon is compiled as a module, load fbcon by doing::
modprobe fbcon
-5. Now to detach fbcon:
+5. Now to detach fbcon::
vbetool vbestate restore < <vga state file> && \
echo 0 > /sys/class/vtconsole/vtcon1/bind
@@ -243,7 +246,7 @@ restored properly. The following is one of the several methods that you can do:
6. That's it, you're back to VGA mode. And if you compiled fbcon as a module,
you can unload it by 'rmmod fbcon'.
-7. To reattach fbcon:
+7. To reattach fbcon::
echo 1 > /sys/class/vtconsole/vtcon1/bind
@@ -266,82 +269,82 @@ the following:
Variation 1:
- a. Before detaching fbcon, do
+ a. Before detaching fbcon, do::
- vbetool vbemode save > <vesa state file> # do once for each vesafb mode,
- # the file can be reused
+ vbetool vbemode save > <vesa state file> # do once for each vesafb mode,
+ # the file can be reused
b. Detach fbcon as in step 5.
- c. Attach fbcon
+ c. Attach fbcon::
- vbetool vbestate restore < <vesa state file> && \
+ vbetool vbestate restore < <vesa state file> && \
echo 1 > /sys/class/vtconsole/vtcon1/bind
Variation 2:
- a. Before detaching fbcon, do:
+ a. Before detaching fbcon, do::
+
echo <ID> > /sys/class/tty/console/bind
-
- vbetool vbemode get
+ vbetool vbemode get
b. Take note of the mode number
b. Detach fbcon as in step 5.
- c. Attach fbcon:
+ c. Attach fbcon::
- vbetool vbemode set <mode number> && \
- echo 1 > /sys/class/vtconsole/vtcon1/bind
+ vbetool vbemode set <mode number> && \
+ echo 1 > /sys/class/vtconsole/vtcon1/bind
Samples:
========
Here are 2 sample bash scripts that you can use to bind or unbind the
-framebuffer console driver if you are on an X86 box:
+framebuffer console driver if you are on an X86 box::
----------------------------------------------------------------------------
-#!/bin/bash
-# Unbind fbcon
+ #!/bin/bash
+ # Unbind fbcon
-# Change this to where your actual vgastate file is located
-# Or Use VGASTATE=$1 to indicate the state file at runtime
-VGASTATE=/tmp/vgastate
+ # Change this to where your actual vgastate file is located
+ # Or Use VGASTATE=$1 to indicate the state file at runtime
+ VGASTATE=/tmp/vgastate
-# path to vbetool
-VBETOOL=/usr/local/bin
+ # path to vbetool
+ VBETOOL=/usr/local/bin
-for (( i = 0; i < 16; i++))
-do
- if test -x /sys/class/vtconsole/vtcon$i; then
- if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
- = 1 ]; then
+ for (( i = 0; i < 16; i++))
+ do
+ if test -x /sys/class/vtconsole/vtcon$i; then
+ if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
+ = 1 ]; then
if test -x $VBETOOL/vbetool; then
echo Unbinding vtcon$i
$VBETOOL/vbetool vbestate restore < $VGASTATE
echo 0 > /sys/class/vtconsole/vtcon$i/bind
fi
- fi
- fi
-done
+ fi
+ fi
+ done
---------------------------------------------------------------------------
-#!/bin/bash
-# Bind fbcon
-for (( i = 0; i < 16; i++))
-do
- if test -x /sys/class/vtconsole/vtcon$i; then
- if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
- = 1 ]; then
+::
+
+ #!/bin/bash
+ # Bind fbcon
+
+ for (( i = 0; i < 16; i++))
+ do
+ if test -x /sys/class/vtconsole/vtcon$i; then
+ if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
+ = 1 ]; then
echo Unbinding vtcon$i
echo 1 > /sys/class/vtconsole/vtcon$i/bind
- fi
- fi
-done
----------------------------------------------------------------------------
+ fi
+ fi
+ done
---
Antonino Daplas <[email protected]>
diff --git a/Documentation/fb/framebuffer.txt b/Documentation/fb/framebuffer.rst
similarity index 92%
rename from Documentation/fb/framebuffer.txt
rename to Documentation/fb/framebuffer.rst
index 58c5ae2e9f59..b50b8268de92 100644
--- a/Documentation/fb/framebuffer.txt
+++ b/Documentation/fb/framebuffer.rst
@@ -1,5 +1,6 @@
- The Frame Buffer Device
- -----------------------
+=======================
+The Frame Buffer Device
+=======================
Maintained by Geert Uytterhoeven <[email protected]>
Last revised: May 10, 2001
@@ -26,7 +27,7 @@ other device in /dev. It's a character device using major 29; the minor
specifies the frame buffer number.
By convention, the following device nodes are used (numbers indicate the device
-minor numbers):
+minor numbers)::
0 = /dev/fb0 First frame buffer
1 = /dev/fb1 Second frame buffer
@@ -34,15 +35,15 @@ minor numbers):
31 = /dev/fb31 32nd frame buffer
For backwards compatibility, you may want to create the following symbolic
-links:
+links::
/dev/fb0current -> fb0
/dev/fb1current -> fb1
and so on...
-The frame buffer devices are also `normal' memory devices, this means, you can
-read and write their contents. You can, for example, make a screen snapshot by
+The frame buffer devices are also `normal` memory devices, this means, you can
+read and write their contents. You can, for example, make a screen snapshot by::
cp /dev/fb0 myfile
@@ -54,11 +55,11 @@ Application software that uses the frame buffer device (e.g. the X server) will
use /dev/fb0 by default (older software uses /dev/fb0current). You can specify
an alternative frame buffer device by setting the environment variable
$FRAMEBUFFER to the path name of a frame buffer device, e.g. (for sh/bash
-users):
+users)::
export FRAMEBUFFER=/dev/fb1
-or (for csh users):
+or (for csh users)::
setenv FRAMEBUFFER /dev/fb1
@@ -90,9 +91,9 @@ which data structures they work. Here's just a brief overview:
possible).
- You can get and set parts of the color map. Communication is done with 16
- bits per color part (red, green, blue, transparency) to support all
- existing hardware. The driver does all the computations needed to apply
- it to the hardware (round it down to less bits, maybe throw away
+ bits per color part (red, green, blue, transparency) to support all
+ existing hardware. The driver does all the computations needed to apply
+ it to the hardware (round it down to less bits, maybe throw away
transparency).
All this hardware abstraction makes the implementation of application programs
@@ -113,10 +114,10 @@ much trouble...
3. Frame Buffer Resolution Maintenance
--------------------------------------
-Frame buffer resolutions are maintained using the utility `fbset'. It can
+Frame buffer resolutions are maintained using the utility `fbset`. It can
change the video mode properties of a frame buffer device. Its main usage is
-to change the current video mode, e.g. during boot up in one of your /etc/rc.*
-or /etc/init.d/* files.
+to change the current video mode, e.g. during boot up in one of your `/etc/rc.*`
+or `/etc/init.d/*` files.
Fbset uses a video mode database stored in a configuration file, so you can
easily add your own modes and refer to them with a simple identifier.
@@ -129,8 +130,8 @@ The X server (XF68_FBDev) is the most notable application program for the frame
buffer device. Starting with XFree86 release 3.2, the X server is part of
XFree86 and has 2 modes:
- - If the `Display' subsection for the `fbdev' driver in the /etc/XF86Config
- file contains a
+ - If the `Display` subsection for the `fbdev` driver in the /etc/XF86Config
+ file contains a::
Modes "default"
@@ -146,7 +147,7 @@ XFree86 and has 2 modes:
same virtual desktop size. The frame buffer device that's used is still
/dev/fb0current (or $FRAMEBUFFER), but the available resolutions are
defined by /etc/XF86Config now. The disadvantage is that you have to
- specify the timings in a different format (but `fbset -x' may help).
+ specify the timings in a different format (but `fbset -x` may help).
To tune a video mode, you can use fbset or xvidtune. Note that xvidtune doesn't
work 100% with XF68_FBDev: the reported clock values are always incorrect.
@@ -172,29 +173,29 @@ retrace, the electron beam is turned off (blanked).
The speed at which the electron beam paints the pixels is determined by the
dotclock in the graphics board. For a dotclock of e.g. 28.37516 MHz (millions
-of cycles per second), each pixel is 35242 ps (picoseconds) long:
+of cycles per second), each pixel is 35242 ps (picoseconds) long::
1/(28.37516E6 Hz) = 35.242E-9 s
-If the screen resolution is 640x480, it will take
+If the screen resolution is 640x480, it will take::
640*35.242E-9 s = 22.555E-6 s
to paint the 640 (xres) pixels on one scanline. But the horizontal retrace
-also takes time (e.g. 272 `pixels'), so a full scanline takes
+also takes time (e.g. 272 `pixels`), so a full scanline takes::
(640+272)*35.242E-9 s = 32.141E-6 s
-We'll say that the horizontal scanrate is about 31 kHz:
+We'll say that the horizontal scanrate is about 31 kHz::
1/(32.141E-6 s) = 31.113E3 Hz
A full screen counts 480 (yres) lines, but we have to consider the vertical
-retrace too (e.g. 49 `lines'). So a full screen will take
+retrace too (e.g. 49 `lines`). So a full screen will take::
(480+49)*32.141E-6 s = 17.002E-3 s
-The vertical scanrate is about 59 Hz:
+The vertical scanrate is about 59 Hz::
1/(17.002E-3 s) = 58.815 Hz
@@ -212,7 +213,7 @@ influenced by the moments at which the synchronization pulses occur.
The following picture summarizes all timings. The horizontal retrace time is
the sum of the left margin, the right margin and the hsync length, while the
vertical retrace time is the sum of the upper margin, the lower margin and the
-vsync length.
+vsync length::
+----------+---------------------------------------------+----------+-------+
| | ↑ | | |
@@ -256,7 +257,8 @@ The frame buffer device expects all horizontal timings in number of dotclocks
6. Converting XFree86 timing values info frame buffer device timings
--------------------------------------------------------------------
-An XFree86 mode line consists of the following fields:
+An XFree86 mode line consists of the following fields::
+
"800x600" 50 800 856 976 1040 600 637 643 666
< name > DCF HR SH1 SH2 HFL VR SV1 SV2 VFL
@@ -271,19 +273,27 @@ The frame buffer device uses the following fields:
- vsync_len: length of vertical sync
1) Pixelclock:
+
xfree: in MHz
+
fb: in picoseconds (ps)
pixclock = 1000000 / DCF
2) horizontal timings:
+
left_margin = HFL - SH2
+
right_margin = SH1 - HR
+
hsync_len = SH2 - SH1
3) vertical timings:
+
upper_margin = VFL - SV2
+
lower_margin = SV1 - VR
+
vsync_len = SV2 - SV1
Good examples for VESA timings can be found in the XFree86 source tree,
@@ -303,9 +313,10 @@ and to the following documentation:
- The manual pages for fbset: fbset(8), fb.modes(5)
- The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5)
- The mighty kernel sources:
- o linux/drivers/video/
- o linux/include/linux/fb.h
- o linux/include/video/
+
+ - linux/drivers/video/
+ - linux/include/linux/fb.h
+ - linux/include/video/
@@ -330,14 +341,14 @@ and on its mirrors.
The latest version of fbset can be found at
- http://www.linux-fbdev.org/
+ http://www.linux-fbdev.org/
+
+
+10. Credits
+-----------
-
-10. Credits
-----------
-
This readme was written by Geert Uytterhoeven, partly based on the original
-`X-framebuffer.README' by Roman Hodek and Martin Schaller. Section 6 was
+`X-framebuffer.README` by Roman Hodek and Martin Schaller. Section 6 was
provided by Frank Neumann.
The frame buffer device abstraction was designed by Martin Schaller.
diff --git a/Documentation/fb/gxfb.txt b/Documentation/fb/gxfb.rst
similarity index 60%
rename from Documentation/fb/gxfb.txt
rename to Documentation/fb/gxfb.rst
index 2f640903bbb2..5738709bccbb 100644
--- a/Documentation/fb/gxfb.txt
+++ b/Documentation/fb/gxfb.rst
@@ -1,7 +1,8 @@
-[This file is cloned from VesaFB/aty128fb]
-
+=============
What is gxfb?
-=================
+=============
+
+.. [This file is cloned from VesaFB/aty128fb]
This is a graphics framebuffer driver for AMD Geode GX2 based processors.
@@ -23,9 +24,9 @@ How to use it?
==============
Switching modes is done using gxfb.mode_option=<resolution>... boot
-parameter or using `fbset' program.
+parameter or using `fbset` program.
-See Documentation/fb/modedb.txt for more information on modedb
+See Documentation/fb/modedb.rst for more information on modedb
resolutions.
@@ -42,11 +43,12 @@ You can pass kernel command line options to gxfb with gxfb.<option>.
For example, gxfb.mode_option=800x600@75.
Accepted options:
-mode_option - specify the video mode. Of the form
- <x>x<y>[-<bpp>][@<refresh>]
-vram - size of video ram (normally auto-detected)
-vt_switch - enable vt switching during suspend/resume. The vt
- switch is slow, but harmless.
+================ ==================================================
+mode_option specify the video mode. Of the form
+ <x>x<y>[-<bpp>][@<refresh>]
+vram size of video ram (normally auto-detected)
+vt_switch enable vt switching during suspend/resume. The vt
+ switch is slow, but harmless.
+================ ==================================================
---
Andres Salomon <[email protected]>
diff --git a/Documentation/fb/index.rst b/Documentation/fb/index.rst
new file mode 100644
index 000000000000..d47313714635
--- /dev/null
+++ b/Documentation/fb/index.rst
@@ -0,0 +1,50 @@
+:orphan:
+
+============
+Frame Buffer
+============
+
+.. toctree::
+ :maxdepth: 1
+
+ api
+ arkfb
+ aty128fb
+ cirrusfb
+ cmap_xfbdev
+ deferred_io
+ efifb
+ ep93xx-fb
+ fbcon
+ framebuffer
+ gxfb
+ intel810
+ intelfb
+ internals
+ lxfb
+ matroxfb
+ metronomefb
+ modedb
+ pvr2fb
+ pxafb
+ s3fb
+ sa1100fb
+ sh7760fb
+ sisfb
+ sm501
+ sm712fb
+ sstfb
+ tgafb
+ tridentfb
+ udlfb
+ uvesafb
+ vesafb
+ viafb
+ vt8623fb
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/fb/intel810.txt b/Documentation/fb/intel810.rst
similarity index 83%
rename from Documentation/fb/intel810.txt
rename to Documentation/fb/intel810.rst
index a8e9f5bca6f3..eb86098db91f 100644
--- a/Documentation/fb/intel810.txt
+++ b/Documentation/fb/intel810.rst
@@ -1,26 +1,31 @@
+================================
Intel 810/815 Framebuffer driver
- Tony Daplas <[email protected]>
- http://i810fb.sourceforge.net
+================================
- March 17, 2002
+Tony Daplas <[email protected]>
- First Released: July 2001
- Last Update: September 12, 2005
-================================================================
+http://i810fb.sourceforge.net
+
+March 17, 2002
+
+First Released: July 2001
+Last Update: September 12, 2005
A. Introduction
+===============
This is a framebuffer driver for various Intel 810/815 compatible
graphics devices. These include:
- Intel 810
- Intel 810E
- Intel 810-DC100
- Intel 815 Internal graphics only, 100Mhz FSB
- Intel 815 Internal graphics only
- Intel 815 Internal graphics and AGP
+ - Intel 810
+ - Intel 810E
+ - Intel 810-DC100
+ - Intel 815 Internal graphics only, 100Mhz FSB
+ - Intel 815 Internal graphics only
+ - Intel 815 Internal graphics and AGP
B. Features
+============
- Choice of using Discrete Video Timings, VESA Generalized Timing
Formula, or a framebuffer specific database to set the video mode
@@ -45,10 +50,11 @@ B. Features
- Can concurrently run with xfree86 running with native i810 drivers
- Hardware Cursor Support
-
+
- Supports EDID probing either by DDC/I2C or through the BIOS
C. List of available options
+=============================
a. "video=i810fb"
enables the i810 driver
@@ -158,7 +164,7 @@ C. List of available options
(default = not set)
n. "dcolor"
- Use directcolor visual instead of truecolor for pixel depths greater
+ Use directcolor visual instead of truecolor for pixel depths greater
than 8 bpp. Useful for color tuning, such as gamma control.
Recommendation: do not set
@@ -167,35 +173,37 @@ C. List of available options
o. <xres>x<yres>[-<bpp>][@<refresh>]
The driver will now accept specification of boot mode option. If this
is specified, the options 'xres' and 'yres' will be ignored. See
- Documentation/fb/modedb.txt for usage.
+ Documentation/fb/modedb.rst for usage.
D. Kernel booting
+=================
Separate each option/option-pair by commas (,) and the option from its value
-with a colon (:) as in the following:
+with a colon (:) as in the following::
-video=i810fb:option1,option2:value2
+ video=i810fb:option1,option2:value2
Sample Usage
------------
-In /etc/lilo.conf, add the line:
+In /etc/lilo.conf, add the line::
-append="video=i810fb:vram:2,xres:1024,yres:768,bpp:8,hsync1:30,hsync2:55, \
- vsync1:50,vsync2:85,accel,mtrr"
+ append="video=i810fb:vram:2,xres:1024,yres:768,bpp:8,hsync1:30,hsync2:55, \
+ vsync1:50,vsync2:85,accel,mtrr"
This will initialize the framebuffer to 1024x768 at 8bpp. The framebuffer
will use 2 MB of System RAM. MTRR support will be enabled. The refresh rate
will be computed based on the hsync1/hsync2 and vsync1/vsync2 values.
IMPORTANT:
-You must include hsync1, hsync2, vsync1 and vsync2 to enable video modes
-better than 640x480 at 60Hz. HOWEVER, if your chipset/display combination
-supports I2C and has an EDID block, you can safely exclude hsync1, hsync2,
-vsync1 and vsync2 parameters. These parameters will be taken from the EDID
-block.
+ You must include hsync1, hsync2, vsync1 and vsync2 to enable video modes
+ better than 640x480 at 60Hz. HOWEVER, if your chipset/display combination
+ supports I2C and has an EDID block, you can safely exclude hsync1, hsync2,
+ vsync1 and vsync2 parameters. These parameters will be taken from the EDID
+ block.
E. Module options
+==================
The module parameters are essentially similar to the kernel
parameters. The main difference is that you need to include a Boolean value
@@ -206,31 +214,32 @@ Example, to enable MTRR, include "mtrr=1".
Sample Usage
------------
-Using the same setup as described above, load the module like this:
+Using the same setup as described above, load the module like this::
modprobe i810fb vram=2 xres=1024 bpp=8 hsync1=30 hsync2=55 vsync1=50 \
- vsync2=85 accel=1 mtrr=1
+ vsync2=85 accel=1 mtrr=1
-Or just add the following to a configuration file in /etc/modprobe.d/
+Or just add the following to a configuration file in /etc/modprobe.d/::
options i810fb vram=2 xres=1024 bpp=16 hsync1=30 hsync2=55 vsync1=50 \
vsync2=85 accel=1 mtrr=1
-and just do a
+and just do a::
modprobe i810fb
F. Setup
+=========
- a. Do your usual method of configuring the kernel.
+ a. Do your usual method of configuring the kernel
- make menuconfig/xconfig/config
+ make menuconfig/xconfig/config
b. Under "Code maturity level options" enable "Prompt for development
and/or incomplete code/drivers".
- c. Enable agpgart support for the Intel 810/815 on-board graphics.
+ c. Enable agpgart support for the Intel 810/815 on-board graphics.
This is required. The option is under "Character Devices".
d. Under "Graphics Support", select "Intel 810/815" either statically
@@ -242,7 +251,7 @@ F. Setup
set 'Enable DDC Support' to 'y'. To make this option appear, set
'use VESA Generalized Timing Formula' to 'y'.
- f. If you want a framebuffer console, enable it under "Console
+ f. If you want a framebuffer console, enable it under "Console
Drivers".
g. Compile your kernel.
@@ -253,6 +262,7 @@ F. Setup
patch to see the chipset in action (or inaction :-).
G. Acknowledgment:
+===================
1. Geert Uytterhoeven - his excellent howto and the virtual
framebuffer driver code made this possible.
@@ -269,10 +279,9 @@ G. Acknowledgment:
optimizations possible.
H. Home Page:
+==============
A more complete, and probably updated information is provided at
http://i810fb.sourceforge.net.
-###########################
Tony
-
diff --git a/Documentation/fb/intelfb.txt b/Documentation/fb/intelfb.rst
similarity index 73%
rename from Documentation/fb/intelfb.txt
rename to Documentation/fb/intelfb.rst
index feac4e4d6968..e2d0903f4efb 100644
--- a/Documentation/fb/intelfb.txt
+++ b/Documentation/fb/intelfb.rst
@@ -1,24 +1,28 @@
+=============================================================
Intel 830M/845G/852GM/855GM/865G/915G/945G Framebuffer driver
-================================================================
+=============================================================
A. Introduction
- This is a framebuffer driver for various Intel 8xx/9xx compatible
+===============
+
+This is a framebuffer driver for various Intel 8xx/9xx compatible
graphics devices. These would include:
- Intel 830M
- Intel 845G
- Intel 852GM
- Intel 855GM
- Intel 865G
- Intel 915G
- Intel 915GM
- Intel 945G
- Intel 945GM
- Intel 945GME
- Intel 965G
- Intel 965GM
+ - Intel 830M
+ - Intel 845G
+ - Intel 852GM
+ - Intel 855GM
+ - Intel 865G
+ - Intel 915G
+ - Intel 915GM
+ - Intel 945G
+ - Intel 945GM
+ - Intel 945GME
+ - Intel 965G
+ - Intel 965GM
B. List of available options
+=============================
a. "video=intelfb"
enables the intelfb driver
@@ -39,12 +43,12 @@ B. List of available options
(default = 4 MB)
d. "voffset=<value>"
- select at what offset in MB of the logical memory to allocate the
+ select at what offset in MB of the logical memory to allocate the
framebuffer memory. The intent is to avoid the memory blocks
used by standard graphics applications (XFree86). Depending on your
- usage, adjust the value up or down, (0 for maximum usage, 63/127 MB
- for the least amount). Note, an arbitrary setting may conflict
- with XFree86.
+ usage, adjust the value up or down, (0 for maximum usage, 63/127 MB
+ for the least amount). Note, an arbitrary setting may conflict
+ with XFree86.
Recommendation: do not set
(default = 48 MB)
@@ -80,18 +84,19 @@ B. List of available options
The default parameter (not named) is the mode.
C. Kernel booting
+=================
Separate each option/option-pair by commas (,) and the option from its value
-with an equals sign (=) as in the following:
+with an equals sign (=) as in the following::
-video=intelfb:option1,option2=value2
+ video=intelfb:option1,option2=value2
Sample Usage
------------
-In /etc/lilo.conf, add the line:
+In /etc/lilo.conf, add the line::
-append="video=intelfb:mode=800x600-32@75,accel,hwcursor,vram=8"
+ append="video=intelfb:mode=800x600-32@75,accel,hwcursor,vram=8"
This will initialize the framebuffer to 800x600 at 32bpp and 75Hz. The
framebuffer will use 8 MB of System RAM. hw acceleration of text and cursor
@@ -106,8 +111,9 @@ in this directory.
D. Module options
+==================
- The module parameters are essentially similar to the kernel
+The module parameters are essentially similar to the kernel
parameters. The main difference is that you need to include a Boolean value
(1 for TRUE, and 0 for FALSE) for those options which don't need a value.
@@ -116,23 +122,24 @@ Example, to enable MTRR, include "mtrr=1".
Sample Usage
------------
-Using the same setup as described above, load the module like this:
+Using the same setup as described above, load the module like this::
modprobe intelfb mode=800x600-32@75 vram=8 accel=1 hwcursor=1
-Or just add the following to a configuration file in /etc/modprobe.d/
+Or just add the following to a configuration file in /etc/modprobe.d/::
options intelfb mode=800x600-32@75 vram=8 accel=1 hwcursor=1
-and just do a
+and just do a::
modprobe intelfb
E. Acknowledgment:
+===================
1. Geert Uytterhoeven - his excellent howto and the virtual
- framebuffer driver code made this possible.
+ framebuffer driver code made this possible.
2. Jeff Hartmann for his agpgart code.
@@ -145,5 +152,4 @@ E. Acknowledgment:
6. Andrew Morton for his kernel patches maintenance.
-###########################
Sylvain
diff --git a/Documentation/fb/internals.txt b/Documentation/fb/internals.rst
similarity index 82%
rename from Documentation/fb/internals.txt
rename to Documentation/fb/internals.rst
index 9b2a2b2f3e57..696b50aa7c24 100644
--- a/Documentation/fb/internals.txt
+++ b/Documentation/fb/internals.rst
@@ -1,13 +1,19 @@
+=============================
+Frame Buffer device internals
+=============================
This is a first start for some documentation about frame buffer device
internals.
-Geert Uytterhoeven <[email protected]>, 21 July 1998
-James Simmons <[email protected]>, Nov 26 2002
+Authors:
+
+- Geert Uytterhoeven <[email protected]>, 21 July 1998
+- James Simmons <[email protected]>, Nov 26 2002
--------------------------------------------------------------------------------
- *** STRUCTURES USED BY THE FRAME BUFFER DEVICE API ***
+Structures used by the frame buffer device API
+==============================================
The following structures play a role in the game of frame buffer devices. They
are defined in <linux/fb.h>.
@@ -40,19 +46,18 @@ are defined in <linux/fb.h>.
Generic information, API and low level information about a specific frame
buffer device instance (slot number, board address, ...).
- - struct `par'
+ - struct `par`
Device dependent information that uniquely defines the video mode for this
particular piece of hardware.
---------------------------------------------------------------------------------
-
- *** VISUALS USED BY THE FRAME BUFFER DEVICE API ***
+Visuals used by the frame buffer device API
+===========================================
Monochrome (FB_VISUAL_MONO01 and FB_VISUAL_MONO10)
--------------------------------------------------
+--------------------------------------------------
Each pixel is either black or white.
@@ -70,7 +75,7 @@ The pixel value is broken up into red, green, and blue fields.
Direct color (FB_VISUAL_DIRECTCOLOR)
------------------------------------
-The pixel value is broken up into red, green, and blue fields, each of which
+The pixel value is broken up into red, green, and blue fields, each of which
are looked up in separate red, green, and blue lookup tables.
@@ -79,4 +84,3 @@ Grayscale displays
Grayscale and static grayscale are special variants of pseudo color and static
pseudo color, where the red, green and blue components are always equal to
each other.
-
diff --git a/Documentation/fb/lxfb.txt b/Documentation/fb/lxfb.rst
similarity index 60%
rename from Documentation/fb/lxfb.txt
rename to Documentation/fb/lxfb.rst
index 38b3ca6f6ca7..863e6b98fbae 100644
--- a/Documentation/fb/lxfb.txt
+++ b/Documentation/fb/lxfb.rst
@@ -1,7 +1,9 @@
-[This file is cloned from VesaFB/aty128fb]
-
+=============
What is lxfb?
-=================
+=============
+
+.. [This file is cloned from VesaFB/aty128fb]
+
This is a graphics framebuffer driver for AMD Geode LX based processors.
@@ -23,9 +25,9 @@ How to use it?
==============
Switching modes is done using lxfb.mode_option=<resolution>... boot
-parameter or using `fbset' program.
+parameter or using `fbset` program.
-See Documentation/fb/modedb.txt for more information on modedb
+See Documentation/fb/modedb.rst for more information on modedb
resolutions.
@@ -42,11 +44,12 @@ You can pass kernel command line options to lxfb with lxfb.<option>.
For example, lxfb.mode_option=800x600@75.
Accepted options:
-mode_option - specify the video mode. Of the form
- <x>x<y>[-<bpp>][@<refresh>]
-vram - size of video ram (normally auto-detected)
-vt_switch - enable vt switching during suspend/resume. The vt
- switch is slow, but harmless.
+================ ==================================================
+mode_option specify the video mode. Of the form
+ <x>x<y>[-<bpp>][@<refresh>]
+vram size of video ram (normally auto-detected)
+vt_switch enable vt switching during suspend/resume. The vt
+ switch is slow, but harmless.
+================ ==================================================
---
Andres Salomon <[email protected]>
diff --git a/Documentation/fb/matroxfb.txt b/Documentation/fb/matroxfb.rst
similarity index 32%
rename from Documentation/fb/matroxfb.txt
rename to Documentation/fb/matroxfb.rst
index b95f5bb522f2..f1859d98606e 100644
--- a/Documentation/fb/matroxfb.txt
+++ b/Documentation/fb/matroxfb.rst
@@ -1,8 +1,10 @@
-[This file is cloned from VesaFB. Thanks go to Gerd Knorr]
-
+=================
What is matroxfb?
=================
+.. [This file is cloned from VesaFB. Thanks go to Gerd Knorr]
+
+
This is a driver for a graphic framebuffer for Matrox devices on
Alpha, Intel and PPC boxes.
@@ -23,57 +25,66 @@ How to use it?
==============
Switching modes is done using the video=matroxfb:vesa:... boot parameter
-or using `fbset' program.
+or using `fbset` program.
If you want, for example, enable a resolution of 1280x1024x24bpp you should
pass to the kernel this command line: "video=matroxfb:vesa:0x1BB".
You should compile in both vgacon (to boot if you remove you Matrox from
box) and matroxfb (for graphics mode). You should not compile-in vesafb
-unless you have primary display on non-Matrox VBE2.0 device (see
-Documentation/fb/vesafb.txt for details).
+unless you have primary display on non-Matrox VBE2.0 device (see
+Documentation/fb/vesafb.rst for details).
Currently supported video modes are (through vesa:... interface, PowerMac
has [as addon] compatibility code):
-[Graphic modes]
-
-bpp | 640x400 640x480 768x576 800x600 960x720
-----+--------------------------------------------
- 4 | 0x12 0x102
- 8 | 0x100 0x101 0x180 0x103 0x188
- 15 | 0x110 0x181 0x113 0x189
- 16 | 0x111 0x182 0x114 0x18A
- 24 | 0x1B2 0x184 0x1B5 0x18C
- 32 | 0x112 0x183 0x115 0x18B
-
-
-[Graphic modes (continued)]
-
-bpp | 1024x768 1152x864 1280x1024 1408x1056 1600x1200
-----+------------------------------------------------
- 4 | 0x104 0x106
- 8 | 0x105 0x190 0x107 0x198 0x11C
- 15 | 0x116 0x191 0x119 0x199 0x11D
- 16 | 0x117 0x192 0x11A 0x19A 0x11E
- 24 | 0x1B8 0x194 0x1BB 0x19C 0x1BF
- 32 | 0x118 0x193 0x11B 0x19B
-
-
-[Text modes]
-
-text | 640x400 640x480 1056x344 1056x400 1056x480
------+------------------------------------------------
- 8x8 | 0x1C0 0x108 0x10A 0x10B 0x10C
-8x16 | 2, 3, 7 0x109
-
-You can enter these number either hexadecimal (leading `0x') or decimal
+Graphic modes
+-------------
+
+=== ======= ======= ======= ======= =======
+bpp 640x400 640x480 768x576 800x600 960x720
+=== ======= ======= ======= ======= =======
+ 4 0x12 0x102
+ 8 0x100 0x101 0x180 0x103 0x188
+ 15 0x110 0x181 0x113 0x189
+ 16 0x111 0x182 0x114 0x18A
+ 24 0x1B2 0x184 0x1B5 0x18C
+ 32 0x112 0x183 0x115 0x18B
+=== ======= ======= ======= ======= =======
+
+
+Graphic modes (continued)
+-------------------------
+
+=== ======== ======== ========= ========= =========
+bpp 1024x768 1152x864 1280x1024 1408x1056 1600x1200
+=== ======== ======== ========= ========= =========
+ 4 0x104 0x106
+ 8 0x105 0x190 0x107 0x198 0x11C
+ 15 0x116 0x191 0x119 0x199 0x11D
+ 16 0x117 0x192 0x11A 0x19A 0x11E
+ 24 0x1B8 0x194 0x1BB 0x19C 0x1BF
+ 32 0x118 0x193 0x11B 0x19B
+=== ======== ======== ========= ========= =========
+
+
+Text modes
+----------
+
+==== ======= ======= ======== ======== ========
+text 640x400 640x480 1056x344 1056x400 1056x480
+==== ======= ======= ======== ======== ========
+ 8x8 0x1C0 0x108 0x10A 0x10B 0x10C
+8x16 2, 3, 7 0x109
+==== ======= ======= ======== ======== ========
+
+You can enter these number either hexadecimal (leading `0x`) or decimal
(0x100 = 256). You can also use value + 512 to achieve compatibility
with your old number passed to vesafb.
Non-listed number can be achieved by more complicated command-line, for
-example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32'.
+example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32`.
X11
@@ -85,7 +96,7 @@ works fine.
Running another (accelerated) X-Server like XF86_SVGA works too. But (at least)
XFree servers have big troubles in multihead configurations (even on first
-head, not even talking about second). Running XFree86 4.x accelerated mga
+head, not even talking about second). Running XFree86 4.x accelerated mga
driver is possible, but you must not enable DRI - if you do, resolution and
color depth of your X desktop must match resolution and color depths of your
virtual consoles, otherwise X will corrupt accelerator settings.
@@ -96,7 +107,7 @@ SVGALib
Driver contains SVGALib compatibility code. It is turned on by choosing textual
mode for console. You can do it at boot time by using videomode
-2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0' does this work.
+2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0` does this work.
Unfortunately, after SVGALib application exits, screen contents is corrupted.
Switching to another console and back fixes it. I hope that it is SVGALib's
problem and not mine, but I'm not sure.
@@ -106,175 +117,188 @@ Configuration
=============
You can pass kernel command line options to matroxfb with
-`video=matroxfb:option1,option2:value2,option3' (multiple options should be
-separated by comma, values are separated from options by `:').
+`video=matroxfb:option1,option2:value2,option3` (multiple options should be
+separated by comma, values are separated from options by `:`).
Accepted options:
-mem:X - size of memory (X can be in megabytes, kilobytes or bytes)
- You can only decrease value determined by driver because of
- it always probe for memory. Default is to use whole detected
- memory usable for on-screen display (i.e. max. 8 MB).
-disabled - do not load driver; you can use also `off', but `disabled'
- is here too.
-enabled - load driver, if you have `video=matroxfb:disabled' in LILO
- configuration, you can override it by this (you cannot override
- `off'). It is default.
-noaccel - do not use acceleration engine. It does not work on Alphas.
-accel - use acceleration engine. It is default.
-nopan - create initial consoles with vyres = yres, thus disabling virtual
- scrolling.
-pan - create initial consoles as tall as possible (vyres = memory/vxres).
- It is default.
-nopciretry - disable PCI retries. It is needed for some broken chipsets,
- it is autodetected for intel's 82437. In this case device does
- not comply to PCI 2.1 specs (it will not guarantee that every
- transaction terminate with success or retry in 32 PCLK).
-pciretry - enable PCI retries. It is default, except for intel's 82437.
-novga - disables VGA I/O ports. It is default if BIOS did not enable device.
- You should not use this option, some boards then do not restart
- without power off.
-vga - preserve state of VGA I/O ports. It is default. Driver does not
- enable VGA I/O if BIOS did not it (it is not safe to enable it in
- most cases).
-nobios - disables BIOS ROM. It is default if BIOS did not enable BIOS itself.
- You should not use this option, some boards then do not restart
- without power off.
-bios - preserve state of BIOS ROM. It is default. Driver does not enable
- BIOS if BIOS was not enabled before.
-noinit - tells driver, that devices were already initialized. You should use
- it if you have G100 and/or if driver cannot detect memory, you see
- strange pattern on screen and so on. Devices not enabled by BIOS
- are still initialized. It is default.
-init - driver initializes every device it knows about.
-memtype - specifies memory type, implies 'init'. This is valid only for G200
- and G400 and has following meaning:
- G200: 0 -> 2x128Kx32 chips, 2MB onboard, probably sgram
- 1 -> 2x128Kx32 chips, 4MB onboard, probably sgram
- 2 -> 2x256Kx32 chips, 4MB onboard, probably sgram
- 3 -> 2x256Kx32 chips, 8MB onboard, probably sgram
- 4 -> 2x512Kx16 chips, 8/16MB onboard, probably sdram only
- 5 -> same as above
- 6 -> 4x128Kx32 chips, 4MB onboard, probably sgram
- 7 -> 4x128Kx32 chips, 8MB onboard, probably sgram
- G400: 0 -> 2x512Kx16 SDRAM, 16/32MB
- 2x512Kx32 SGRAM, 16/32MB
- 1 -> 2x256Kx32 SGRAM, 8/16MB
- 2 -> 4x128Kx32 SGRAM, 8/16MB
- 3 -> 4x512Kx32 SDRAM, 32MB
- 4 -> 4x256Kx32 SGRAM, 16/32MB
- 5 -> 2x1Mx32 SDRAM, 32MB
- 6 -> reserved
- 7 -> reserved
- You should use sdram or sgram parameter in addition to memtype
- parameter.
-nomtrr - disables write combining on frame buffer. This slows down driver but
- there is reported minor incompatibility between GUS DMA and XFree
- under high loads if write combining is enabled (sound dropouts).
-mtrr - enables write combining on frame buffer. It speeds up video accesses
- much. It is default. You must have MTRR support enabled in kernel
- and your CPU must have MTRR (f.e. Pentium II have them).
-sgram - tells to driver that you have Gxx0 with SGRAM memory. It has no
- effect without `init'.
-sdram - tells to driver that you have Gxx0 with SDRAM memory.
- It is a default.
-inv24 - change timings parameters for 24bpp modes on Millennium and
- Millennium II. Specify this if you see strange color shadows around
- characters.
-noinv24 - use standard timings. It is the default.
-inverse - invert colors on screen (for LCD displays)
-noinverse - show true colors on screen. It is default.
-dev:X - bind driver to device X. Driver numbers device from 0 up to N,
- where device 0 is first `known' device found, 1 second and so on.
- lspci lists devices in this order.
- Default is `every' known device.
-nohwcursor - disables hardware cursor (use software cursor instead).
-hwcursor - enables hardware cursor. It is default. If you are using
- non-accelerated mode (`noaccel' or `fbset -accel false'), software
- cursor is used (except for text mode).
-noblink - disables cursor blinking. Cursor in text mode always blinks (hw
- limitation).
-blink - enables cursor blinking. It is default.
-nofastfont - disables fastfont feature. It is default.
-fastfont:X - enables fastfont feature. X specifies size of memory reserved for
- font data, it must be >= (fontwidth*fontheight*chars_in_font)/8.
+============ ===================================================================
+mem:X size of memory (X can be in megabytes, kilobytes or bytes)
+ You can only decrease value determined by driver because of
+ it always probe for memory. Default is to use whole detected
+ memory usable for on-screen display (i.e. max. 8 MB).
+disabled do not load driver; you can use also `off`, but `disabled`
+ is here too.
+enabled load driver, if you have `video=matroxfb:disabled` in LILO
+ configuration, you can override it by this (you cannot override
+ `off`). It is default.
+noaccel do not use acceleration engine. It does not work on Alphas.
+accel use acceleration engine. It is default.
+nopan create initial consoles with vyres = yres, thus disabling virtual
+ scrolling.
+pan create initial consoles as tall as possible (vyres = memory/vxres).
+ It is default.
+nopciretry disable PCI retries. It is needed for some broken chipsets,
+ it is autodetected for intel's 82437. In this case device does
+ not comply to PCI 2.1 specs (it will not guarantee that every
+ transaction terminate with success or retry in 32 PCLK).
+pciretry enable PCI retries. It is default, except for intel's 82437.
+novga disables VGA I/O ports. It is default if BIOS did not enable
+ device. You should not use this option, some boards then do not
+ restart without power off.
+vga preserve state of VGA I/O ports. It is default. Driver does not
+ enable VGA I/O if BIOS did not it (it is not safe to enable it in
+ most cases).
+nobios disables BIOS ROM. It is default if BIOS did not enable BIOS
+ itself. You should not use this option, some boards then do not
+ restart without power off.
+bios preserve state of BIOS ROM. It is default. Driver does not enable
+ BIOS if BIOS was not enabled before.
+noinit tells driver, that devices were already initialized. You should use
+ it if you have G100 and/or if driver cannot detect memory, you see
+ strange pattern on screen and so on. Devices not enabled by BIOS
+ are still initialized. It is default.
+init driver initializes every device it knows about.
+memtype specifies memory type, implies 'init'. This is valid only for G200
+ and G400 and has following meaning:
+
+ G200:
+ - 0 -> 2x128Kx32 chips, 2MB onboard, probably sgram
+ - 1 -> 2x128Kx32 chips, 4MB onboard, probably sgram
+ - 2 -> 2x256Kx32 chips, 4MB onboard, probably sgram
+ - 3 -> 2x256Kx32 chips, 8MB onboard, probably sgram
+ - 4 -> 2x512Kx16 chips, 8/16MB onboard, probably sdram only
+ - 5 -> same as above
+ - 6 -> 4x128Kx32 chips, 4MB onboard, probably sgram
+ - 7 -> 4x128Kx32 chips, 8MB onboard, probably sgram
+ G400:
+ - 0 -> 2x512Kx16 SDRAM, 16/32MB
+ - 2x512Kx32 SGRAM, 16/32MB
+ - 1 -> 2x256Kx32 SGRAM, 8/16MB
+ - 2 -> 4x128Kx32 SGRAM, 8/16MB
+ - 3 -> 4x512Kx32 SDRAM, 32MB
+ - 4 -> 4x256Kx32 SGRAM, 16/32MB
+ - 5 -> 2x1Mx32 SDRAM, 32MB
+ - 6 -> reserved
+ - 7 -> reserved
+
+ You should use sdram or sgram parameter in addition to memtype
+ parameter.
+nomtrr disables write combining on frame buffer. This slows down driver
+ but there is reported minor incompatibility between GUS DMA and
+ XFree under high loads if write combining is enabled (sound
+ dropouts).
+mtrr enables write combining on frame buffer. It speeds up video
+ accesses much. It is default. You must have MTRR support enabled
+ in kernel and your CPU must have MTRR (f.e. Pentium II have them).
+sgram tells to driver that you have Gxx0 with SGRAM memory. It has no
+ effect without `init`.
+sdram tells to driver that you have Gxx0 with SDRAM memory.
+ It is a default.
+inv24 change timings parameters for 24bpp modes on Millennium and
+ Millennium II. Specify this if you see strange color shadows
+ around characters.
+noinv24 use standard timings. It is the default.
+inverse invert colors on screen (for LCD displays)
+noinverse show true colors on screen. It is default.
+dev:X bind driver to device X. Driver numbers device from 0 up to N,
+ where device 0 is first `known` device found, 1 second and so on.
+ lspci lists devices in this order.
+ Default is `every` known device.
+nohwcursor disables hardware cursor (use software cursor instead).
+hwcursor enables hardware cursor. It is default. If you are using
+ non-accelerated mode (`noaccel` or `fbset -accel false`), software
+ cursor is used (except for text mode).
+noblink disables cursor blinking. Cursor in text mode always blinks (hw
+ limitation).
+blink enables cursor blinking. It is default.
+nofastfont disables fastfont feature. It is default.
+fastfont:X enables fastfont feature. X specifies size of memory reserved for
+ font data, it must be >= (fontwidth*fontheight*chars_in_font)/8.
It is faster on Gx00 series, but slower on older cards.
-grayscale - enable grayscale summing. It works in PSEUDOCOLOR modes (text,
- 4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters
- displayed through putc/putcs. Direct accesses to framebuffer
- can paint colors.
-nograyscale - disable grayscale summing. It is default.
-cross4MB - enables that pixel line can cross 4MB boundary. It is default for
- non-Millennium.
-nocross4MB - pixel line must not cross 4MB boundary. It is default for
- Millennium I or II, because of these devices have hardware
+grayscale enable grayscale summing. It works in PSEUDOCOLOR modes (text,
+ 4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters
+ displayed through putc/putcs. Direct accesses to framebuffer
+ can paint colors.
+nograyscale disable grayscale summing. It is default.
+cross4MB enables that pixel line can cross 4MB boundary. It is default for
+ non-Millennium.
+nocross4MB pixel line must not cross 4MB boundary. It is default for
+ Millennium I or II, because of these devices have hardware
limitations which do not allow this. But this option is
incompatible with some (if not all yet released) versions of
XF86_FBDev.
-dfp - enables digital flat panel interface. This option is incompatible with
- secondary (TV) output - if DFP is active, TV output must be
- inactive and vice versa. DFP always uses same timing as primary
- (monitor) output.
-dfp:X - use settings X for digital flat panel interface. X is number from
- 0 to 0xFF, and meaning of each individual bit is described in
- G400 manual, in description of DAC register 0x1F. For normal operation
- you should set all bits to zero, except lowest bit. This lowest bit
- selects who is source of display clocks, whether G400, or panel.
- Default value is now read back from hardware - so you should specify
- this value only if you are also using `init' parameter.
-outputs:XYZ - set mapping between CRTC and outputs. Each letter can have value
- of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter corresponds
- to primary analog output, second letter to the secondary analog output
- and third letter to the DVI output. Default setting is 100 for
- cards below G400 or G400 without DFP, 101 for G400 with DFP, and
- 111 for G450 and G550. You can set mapping only on first card,
- use matroxset for setting up other devices.
-vesa:X - selects startup videomode. X is number from 0 to 0x1FF, see table
- above for detailed explanation. Default is 640x480x8bpp if driver
- has 8bpp support. Otherwise first available of 640x350x4bpp,
- 640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
- (80x25 text is always available).
+dfp enables digital flat panel interface. This option is incompatible
+ with secondary (TV) output - if DFP is active, TV output must be
+ inactive and vice versa. DFP always uses same timing as primary
+ (monitor) output.
+dfp:X use settings X for digital flat panel interface. X is number from
+ 0 to 0xFF, and meaning of each individual bit is described in
+ G400 manual, in description of DAC register 0x1F. For normal
+ operation you should set all bits to zero, except lowest bit. This
+ lowest bit selects who is source of display clocks, whether G400,
+ or panel. Default value is now read back from hardware - so you
+ should specify this value only if you are also using `init`
+ parameter.
+outputs:XYZ set mapping between CRTC and outputs. Each letter can have value
+ of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter
+ corresponds to primary analog output, second letter to the
+ secondary analog output and third letter to the DVI output.
+ Default setting is 100 for cards below G400 or G400 without DFP,
+ 101 for G400 with DFP, and 111 for G450 and G550. You can set
+ mapping only on first card, use matroxset for setting up other
+ devices.
+vesa:X selects startup videomode. X is number from 0 to 0x1FF, see table
+ above for detailed explanation. Default is 640x480x8bpp if driver
+ has 8bpp support. Otherwise first available of 640x350x4bpp,
+ 640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
+ (80x25 text is always available).
+============ ===================================================================
-If you are not satisfied with videomode selected by `vesa' option, you
+If you are not satisfied with videomode selected by `vesa` option, you
can modify it with these options:
-xres:X - horizontal resolution, in pixels. Default is derived from `vesa'
- option.
-yres:X - vertical resolution, in pixel lines. Default is derived from `vesa'
- option.
-upper:X - top boundary: lines between end of VSYNC pulse and start of first
- pixel line of picture. Default is derived from `vesa' option.
-lower:X - bottom boundary: lines between end of picture and start of VSYNC
- pulse. Default is derived from `vesa' option.
-vslen:X - length of VSYNC pulse, in lines. Default is derived from `vesa'
- option.
-left:X - left boundary: pixels between end of HSYNC pulse and first pixel.
- Default is derived from `vesa' option.
-right:X - right boundary: pixels between end of picture and start of HSYNC
- pulse. Default is derived from `vesa' option.
-hslen:X - length of HSYNC pulse, in pixels. Default is derived from `vesa'
- option.
-pixclock:X - dotclocks, in ps (picoseconds). Default is derived from `vesa'
- option and from `fh' and `fv' options.
-sync:X - sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
- If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
- generated. If bit 5 (value 0x20) is set, sync on green is turned on.
- Do not forget that if you want sync on green, you also probably
- want composite sync.
- Default depends on `vesa'.
-depth:X - Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
- `vesa'.
+============ ===================================================================
+xres:X horizontal resolution, in pixels. Default is derived from `vesa`
+ option.
+yres:X vertical resolution, in pixel lines. Default is derived from `vesa`
+ option.
+upper:X top boundary: lines between end of VSYNC pulse and start of first
+ pixel line of picture. Default is derived from `vesa` option.
+lower:X bottom boundary: lines between end of picture and start of VSYNC
+ pulse. Default is derived from `vesa` option.
+vslen:X length of VSYNC pulse, in lines. Default is derived from `vesa`
+ option.
+left:X left boundary: pixels between end of HSYNC pulse and first pixel.
+ Default is derived from `vesa` option.
+right:X right boundary: pixels between end of picture and start of HSYNC
+ pulse. Default is derived from `vesa` option.
+hslen:X length of HSYNC pulse, in pixels. Default is derived from `vesa`
+ option.
+pixclock:X dotclocks, in ps (picoseconds). Default is derived from `vesa`
+ option and from `fh` and `fv` options.
+sync:X sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
+ If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
+ generated. If bit 5 (value 0x20) is set, sync on green is turned
+ on. Do not forget that if you want sync on green, you also probably
+ want composite sync.
+ Default depends on `vesa`.
+depth:X Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
+ `vesa`.
+============ ===================================================================
If you know capabilities of your monitor, you can specify some (or all) of
-`maxclk', `fh' and `fv'. In this case, `pixclock' is computed so that
+`maxclk`, `fh` and `fv`. In this case, `pixclock` is computed so that
pixclock <= maxclk, real_fh <= fh and real_fv <= fv.
-maxclk:X - maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
- `don't care'.
-fh:X - maximum horizontal synchronization frequency. X can be specified
- in kHz or Hz. Default is `don't care'.
-fv:X - maximum vertical frequency. X must be specified in Hz. Default is
- 70 for modes derived from `vesa' with yres <= 400, 60Hz for
- yres > 400.
+============ ==================================================================
+maxclk:X maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
+ `don`t care`.
+fh:X maximum horizontal synchronization frequency. X can be specified
+ in kHz or Hz. Default is `don't care`.
+fv:X maximum vertical frequency. X must be specified in Hz. Default is
+ 70 for modes derived from `vesa` with yres <= 400, 60Hz for
+ yres > 400.
+============ ==================================================================
Limitations
@@ -282,51 +306,58 @@ Limitations
There are known and unknown bugs, features and misfeatures.
Currently there are following known bugs:
- + SVGALib does not restore screen on exit
- + generic fbcon-cfbX procedures do not work on Alphas. Due to this,
- `noaccel' (and cfb4 accel) driver does not work on Alpha. So everyone
- with access to /dev/fb* on Alpha can hang machine (you should restrict
- access to /dev/fb* - everyone with access to this device can destroy
+
+ - SVGALib does not restore screen on exit
+ - generic fbcon-cfbX procedures do not work on Alphas. Due to this,
+ `noaccel` (and cfb4 accel) driver does not work on Alpha. So everyone
+ with access to `/dev/fb*` on Alpha can hang machine (you should restrict
+ access to `/dev/fb*` - everyone with access to this device can destroy
your monitor, believe me...).
- + 24bpp does not support correctly XF-FBDev on big-endian architectures.
- + interlaced text mode is not supported; it looks like hardware limitation,
+ - 24bpp does not support correctly XF-FBDev on big-endian architectures.
+ - interlaced text mode is not supported; it looks like hardware limitation,
but I'm not sure.
- + Gxx0 SGRAM/SDRAM is not autodetected.
- + If you are using more than one framebuffer device, you must boot kernel
+ - Gxx0 SGRAM/SDRAM is not autodetected.
+ - If you are using more than one framebuffer device, you must boot kernel
with 'video=scrollback:0'.
- + maybe more...
+ - maybe more...
+
And following misfeatures:
- + SVGALib does not restore screen on exit.
- + pixclock for text modes is limited by hardware to
- 83 MHz on G200
- 66 MHz on Millennium I
- 60 MHz on Millennium II
+
+ - SVGALib does not restore screen on exit.
+ - pixclock for text modes is limited by hardware to
+
+ - 83 MHz on G200
+ - 66 MHz on Millennium I
+ - 60 MHz on Millennium II
+
Because I have no access to other devices, I do not know specific
frequencies for them. So driver does not check this and allows you to
set frequency higher that this. It causes sparks, black holes and other
pretty effects on screen. Device was not destroyed during tests. :-)
- + my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
+ - my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
(and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
them (maybe that chip overheats, but it has a very big cooler (G100 has
none), so it should work).
- + special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
+ - special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
G16V16 are not supported
- + color keying is not supported
- + feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
+ - color keying is not supported
+ - feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
by BIOS)
- + DDC (monitor detection) is supported through dualhead driver
- + some check for input values are not so strict how it should be (you can
+ - DDC (monitor detection) is supported through dualhead driver
+ - some check for input values are not so strict how it should be (you can
specify vslen=4000 and so on).
- + maybe more...
+ - maybe more...
+
And following features:
- + 4bpp is available only on Millennium I and Millennium II. It is hardware
+
+ - 4bpp is available only on Millennium I and Millennium II. It is hardware
limitation.
- + selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
+ - selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
else selects 5:6:5 mode.
- + text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
- instead of one of 16M colors). It is due to hardware limitation of
+ - text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
+ instead of one of 16M colors). It is due to hardware limitation of
Millennium I/II and SVGALib compatibility.
@@ -334,42 +365,42 @@ Benchmarks
==========
It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
time for draw 6144000 characters on screen through /dev/vcsa
-(for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
+(for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
16 seconds, i.e. 187 MBps).
Times were obtained from one older version of driver, now they are about 3%
faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
-PCI slot, G200 in AGP 2x slot. I did not test vgacon.
+PCI slot, G200 in AGP 2x slot. I did not test vgacon::
-NOACCEL
- 8x16 12x22
- Millennium I G200 Millennium I G200
-8bpp 16.42 9.54 12.33 9.13
-16bpp 21.00 15.70 19.11 15.02
-24bpp 36.66 36.66 35.00 35.00
-32bpp 35.00 30.00 33.85 28.66
+ NOACCEL
+ 8x16 12x22
+ Millennium I G200 Millennium I G200
+ 8bpp 16.42 9.54 12.33 9.13
+ 16bpp 21.00 15.70 19.11 15.02
+ 24bpp 36.66 36.66 35.00 35.00
+ 32bpp 35.00 30.00 33.85 28.66
-ACCEL, nofastfont
- 8x16 12x22 6x11
+ ACCEL, nofastfont
+ 8x16 12x22 6x11
Millennium I G200 Millennium I G200 Millennium I G200
-8bpp 7.79 7.24 13.55 7.78 30.00 21.01
-16bpp 9.13 7.78 16.16 7.78 30.00 21.01
-24bpp 14.17 10.72 18.69 10.24 34.99 21.01
-32bpp 16.15 16.16 18.73 13.09 34.99 21.01
+ 8bpp 7.79 7.24 13.55 7.78 30.00 21.01
+ 16bpp 9.13 7.78 16.16 7.78 30.00 21.01
+ 24bpp 14.17 10.72 18.69 10.24 34.99 21.01
+ 32bpp 16.15 16.16 18.73 13.09 34.99 21.01
-ACCEL, fastfont
- 8x16 12x22 6x11
+ ACCEL, fastfont
+ 8x16 12x22 6x11
Millennium I G200 Millennium I G200 Millennium I G200
-8bpp 8.41 6.01 6.54 4.37 16.00 10.51
-16bpp 9.54 9.12 8.76 6.17 17.52 14.01
-24bpp 15.00 12.36 11.67 10.00 22.01 18.32
-32bpp 16.18 18.29* 12.71 12.74 24.44 21.00
+ 8bpp 8.41 6.01 6.54 4.37 16.00 10.51
+ 16bpp 9.54 9.12 8.76 6.17 17.52 14.01
+ 24bpp 15.00 12.36 11.67 10.00 22.01 18.32
+ 32bpp 16.18 18.29* 12.71 12.74 24.44 21.00
-TEXT
- 8x16
+ TEXT
+ 8x16
Millennium I G200
-TEXT 3.29 1.50
+ TEXT 3.29 1.50
-* Yes, it is slower than Millennium I.
+ * Yes, it is slower than Millennium I.
Dualhead G400
@@ -408,6 +439,5 @@ Driver supports dualhead G450 with some limitations:
+ kernel is not fully multihead ready, so some things are impossible to do.
+ if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
into kernel.
-
---
+
Petr Vandrovec <[email protected]>
diff --git a/Documentation/fb/metronomefb.txt b/Documentation/fb/metronomefb.rst
similarity index 98%
rename from Documentation/fb/metronomefb.txt
rename to Documentation/fb/metronomefb.rst
index 237ca412582d..63e1d31a7e54 100644
--- a/Documentation/fb/metronomefb.txt
+++ b/Documentation/fb/metronomefb.rst
@@ -1,6 +1,9 @@
- Metronomefb
- -----------
+===========
+Metronomefb
+===========
+
Maintained by Jaya Kumar <jayakumar.lkml.gmail.com>
+
Last revised: Mar 10, 2008
Metronomefb is a driver for the Metronome display controller. The controller
@@ -33,4 +36,3 @@ the physical media.
Metronomefb uses the deferred IO interface so that it can provide a memory
mappable frame buffer. It has been tested with tinyx (Xfbdev). It is known
to work at this time with xeyes, xclock, xloadimage, xpdf.
-
diff --git a/Documentation/fb/modedb.txt b/Documentation/fb/modedb.rst
similarity index 87%
rename from Documentation/fb/modedb.txt
rename to Documentation/fb/modedb.rst
index 16aa08453911..3c2397293977 100644
--- a/Documentation/fb/modedb.txt
+++ b/Documentation/fb/modedb.rst
@@ -1,6 +1,6 @@
-
-
- modedb default video mode support
+=================================
+modedb default video mode support
+=================================
Currently all frame buffer device drivers have their own video mode databases,
@@ -18,7 +18,7 @@ When a frame buffer device receives a video= option it doesn't know, it should
consider that to be a video mode option. If no frame buffer device is specified
in a video= option, fbmem considers that to be a global video mode option.
-Valid mode specifiers (mode_option argument):
+Valid mode specifiers (mode_option argument)::
<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]
<name>[-<bpp>][@<refresh>]
@@ -45,15 +45,18 @@ signals (e.g. HDMI and DVI-I). For other outputs it behaves like 'e'. If 'd'
is specified the output is disabled.
You can additionally specify which output the options matches to.
-To force the VGA output to be enabled and drive a specific mode say:
+To force the VGA output to be enabled and drive a specific mode say::
+
video=VGA-1:1280x1024@60me
-Specifying the option multiple times for different ports is possible, e.g.:
+Specifying the option multiple times for different ports is possible, e.g.::
+
video=LVDS-1:d video=HDMI-1:D
-***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo *****
+-----------------------------------------------------------------------------
What is the VESA(TM) Coordinated Video Timings (CVT)?
+=====================================================
From the VESA(TM) Website:
@@ -90,14 +93,14 @@ determined from its EDID. The version 1.3 of the EDID has extra 128-byte
blocks where additional timing information is placed. As of this time, there
is no support yet in the layer to parse this additional blocks.)
-CVT also introduced a new naming convention (should be seen from dmesg output):
+CVT also introduced a new naming convention (should be seen from dmesg output)::
<pix>M<a>[-R]
where: pix = total amount of pixels in MB (xres x yres)
- M = always present
- a = aspect ratio (3 - 4:3; 4 - 5:4; 9 - 15:9, 16:9; A - 16:10)
- -R = reduced blanking
+ M = always present
+ a = aspect ratio (3 - 4:3; 4 - 5:4; 9 - 15:9, 16:9; A - 16:10)
+ -R = reduced blanking
example: .48M3-R - 800x600 with reduced blanking
@@ -110,15 +113,15 @@ Note: VESA(TM) has restrictions on what is a standard CVT timing:
If one of the above are not satisfied, the kernel will print a warning but the
timings will still be calculated.
-***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo *****
+-----------------------------------------------------------------------------
-To find a suitable video mode, you just call
+To find a suitable video mode, you just call::
-int __init fb_find_mode(struct fb_var_screeninfo *var,
- struct fb_info *info, const char *mode_option,
- const struct fb_videomode *db, unsigned int dbsize,
- const struct fb_videomode *default_mode,
- unsigned int default_bpp)
+ int __init fb_find_mode(struct fb_var_screeninfo *var,
+ struct fb_info *info, const char *mode_option,
+ const struct fb_videomode *db, unsigned int dbsize,
+ const struct fb_videomode *default_mode,
+ unsigned int default_bpp)
with db/dbsize your non-standard video mode database, or NULL to use the
standard video mode database.
@@ -127,12 +130,13 @@ fb_find_mode() first tries the specified video mode (or any mode that matches,
e.g. there can be multiple 640x480 modes, each of them is tried). If that
fails, the default mode is tried. If that fails, it walks over all modes.
-To specify a video mode at bootup, use the following boot options:
+To specify a video mode at bootup, use the following boot options::
+
video=<driver>:<xres>x<yres>[-<bpp>][@refresh]
where <driver> is a name from the table below. Valid default modes can be
found in linux/drivers/video/modedb.c. Check your driver's documentation.
-There may be more modes.
+There may be more modes::
Drivers that support modedb boot options
Boot Name Cards Supported
diff --git a/Documentation/fb/pvr2fb.txt b/Documentation/fb/pvr2fb.rst
similarity index 36%
rename from Documentation/fb/pvr2fb.txt
rename to Documentation/fb/pvr2fb.rst
index 36bdeff585e2..fcf2c21c8fcf 100644
--- a/Documentation/fb/pvr2fb.txt
+++ b/Documentation/fb/pvr2fb.rst
@@ -1,5 +1,4 @@
-$Id: pvr2fb.txt,v 1.1 2001/05/24 05:09:16 mrbrown Exp $
-
+===============
What is pvr2fb?
===============
@@ -21,37 +20,40 @@ Configuration
=============
You can pass kernel command line options to pvr2fb with
-`video=pvr2fb:option1,option2:value2,option3' (multiple options should be
-separated by comma, values are separated from options by `:').
+`video=pvr2fb:option1,option2:value2,option3` (multiple options should be
+separated by comma, values are separated from options by `:`).
+
Accepted options:
-font:X - default font to use. All fonts are supported, including the
- SUN12x22 font which is very nice at high resolutions.
+========== ==================================================================
+font:X default font to use. All fonts are supported, including the
+ SUN12x22 font which is very nice at high resolutions.
-
-mode:X - default video mode with format [xres]x[yres]-<bpp>@<refresh rate>
- The following video modes are supported:
- 640x640-16@60, 640x480-24@60, 640x480-32@60. The Dreamcast
- defaults to 640x480-16@60. At the time of writing the
- 24bpp and 32bpp modes function poorly. Work to fix that is
- ongoing
- Note: the 640x240 mode is currently broken, and should not be
- used for any reason. It is only mentioned here as a reference.
+mode:X default video mode with format [xres]x[yres]-<bpp>@<refresh rate>
+ The following video modes are supported:
+ 640x640-16@60, 640x480-24@60, 640x480-32@60. The Dreamcast
+ defaults to 640x480-16@60. At the time of writing the
+ 24bpp and 32bpp modes function poorly. Work to fix that is
+ ongoing
-inverse - invert colors on screen (for LCD displays)
+ Note: the 640x240 mode is currently broken, and should not be
+ used for any reason. It is only mentioned here as a reference.
-nomtrr - disables write combining on frame buffer. This slows down driver
- but there is reported minor incompatibility between GUS DMA and
- XFree under high loads if write combining is enabled (sound
- dropouts). MTRR is enabled by default on systems that have it
- configured and that support it.
+inverse invert colors on screen (for LCD displays)
-cable:X - cable type. This can be any of the following: vga, rgb, and
- composite. If none is specified, we guess.
+nomtrr disables write combining on frame buffer. This slows down driver
+ but there is reported minor incompatibility between GUS DMA and
+ XFree under high loads if write combining is enabled (sound
+ dropouts). MTRR is enabled by default on systems that have it
+ configured and that support it.
-output:X - output type. This can be any of the following: pal, ntsc, and
- vga. If none is specified, we guess.
+cable:X cable type. This can be any of the following: vga, rgb, and
+ composite. If none is specified, we guess.
+
+output:X output type. This can be any of the following: pal, ntsc, and
+ vga. If none is specified, we guess.
+========== ==================================================================
X11
===
@@ -59,7 +61,6 @@ X11
XF86_FBDev has been shown to work on the Dreamcast in the past - though not yet
on any 2.6 series kernel.
---
Paul Mundt <[email protected]>
+
Updated by Adrian McMenamin <[email protected]>
-
diff --git a/Documentation/fb/pxafb.txt b/Documentation/fb/pxafb.rst
similarity index 78%
rename from Documentation/fb/pxafb.txt
rename to Documentation/fb/pxafb.rst
index d143a0a749f9..90177f5e7e76 100644
--- a/Documentation/fb/pxafb.txt
+++ b/Documentation/fb/pxafb.rst
@@ -1,59 +1,82 @@
+================================
Driver for PXA25x LCD controller
================================
The driver supports the following options, either via
options=<OPTIONS> when modular or video=pxafb:<OPTIONS> when built in.
-For example:
+For example::
+
modprobe pxafb options=vmem:2M,mode:640x480-8,passive
-or on the kernel command line
+
+or on the kernel command line::
+
video=pxafb:vmem:2M,mode:640x480-8,passive
vmem: VIDEO_MEM_SIZE
+
Amount of video memory to allocate (can be suffixed with K or M
for kilobytes or megabytes)
mode:XRESxYRES[-BPP]
+
XRES == LCCR1_PPL + 1
+
YRES == LLCR2_LPP + 1
+
The resolution of the display in pixels
+
BPP == The bit depth. Valid values are 1, 2, 4, 8 and 16.
pixclock:PIXCLOCK
+
Pixel clock in picoseconds
left:LEFT == LCCR1_BLW + 1
+
right:RIGHT == LCCR1_ELW + 1
+
hsynclen:HSYNC == LCCR1_HSW + 1
+
upper:UPPER == LCCR2_BFW
+
lower:LOWER == LCCR2_EFR
+
vsynclen:VSYNC == LCCR2_VSW + 1
+
Display margins and sync times
color | mono => LCCR0_CMS
+
umm...
active | passive => LCCR0_PAS
+
Active (TFT) or Passive (STN) display
single | dual => LCCR0_SDS
+
Single or dual panel passive display
4pix | 8pix => LCCR0_DPD
+
4 or 8 pixel monochrome single panel data
-hsync:HSYNC
-vsync:VSYNC
+hsync:HSYNC, vsync:VSYNC
+
Horizontal and vertical sync. 0 => active low, 1 => active
high.
dpc:DPC
+
Double pixel clock. 1=>true, 0=>false
outputen:POLARITY
+
Output Enable Polarity. 0 => active low, 1 => active high
pixclockpol:POLARITY
+
pixel clock polarity
0 => falling edge, 1 => rising edge
@@ -76,44 +99,50 @@ Overlay Support for PXA27x and later LCD controllers
not for such purpose).
2. overlay framebuffer is allocated dynamically according to specified
- 'struct fb_var_screeninfo', the amount is decided by:
+ 'struct fb_var_screeninfo', the amount is decided by::
- var->xres_virtual * var->yres_virtual * bpp
+ var->xres_virtual * var->yres_virtual * bpp
bpp = 16 -- for RGB565 or RGBT555
- = 24 -- for YUV444 packed
- = 24 -- for YUV444 planar
- = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr)
- = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr)
+
+ bpp = 24 -- for YUV444 packed
+
+ bpp = 24 -- for YUV444 planar
+
+ bpp = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr)
+
+ bpp = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr)
NOTE:
a. overlay does not support panning in x-direction, thus
- var->xres_virtual will always be equal to var->xres
+ var->xres_virtual will always be equal to var->xres
b. line length of overlay(s) must be on a 32-bit word boundary,
- for YUV planar modes, it is a requirement for the component
+ for YUV planar modes, it is a requirement for the component
with minimum bits per pixel, e.g. for YUV420, Cr component
for one pixel is actually 2-bits, it means the line length
should be a multiple of 16-pixels
c. starting horizontal position (XPOS) should start on a 32-bit
- word boundary, otherwise the fb_check_var() will just fail.
+ word boundary, otherwise the fb_check_var() will just fail.
d. the rectangle of the overlay should be within the base plane,
- otherwise fail
+ otherwise fail
Applications should follow the sequence below to operate an overlay
framebuffer:
- a. open("/dev/fb[1-2]", ...)
+ a. open("/dev/fb[1-2]", ...)
b. ioctl(fd, FBIOGET_VSCREENINFO, ...)
c. modify 'var' with desired parameters:
+
1) var->xres and var->yres
2) larger var->yres_virtual if more memory is required,
usually for double-buffering
3) var->nonstd for starting (x, y) and color format
4) var->{red, green, blue, transp} if RGB mode is to be used
+
d. ioctl(fd, FBIOPUT_VSCREENINFO, ...)
e. ioctl(fd, FBIOGET_FSCREENINFO, ...)
f. mmap
@@ -124,19 +153,21 @@ Overlay Support for PXA27x and later LCD controllers
and lengths of each component within the framebuffer.
4. var->nonstd is used to pass starting (x, y) position and color format,
- the detailed bit fields are shown below:
+ the detailed bit fields are shown below::
- 31 23 20 10 0
- +-----------------+---+----------+----------+
- | ... unused ... |FOR| XPOS | YPOS |
- +-----------------+---+----------+----------+
+ 31 23 20 10 0
+ +-----------------+---+----------+----------+
+ | ... unused ... |FOR| XPOS | YPOS |
+ +-----------------+---+----------+----------+
FOR - color format, as defined by OVERLAY_FORMAT_* in pxafb.h
- 0 - RGB
- 1 - YUV444 PACKED
- 2 - YUV444 PLANAR
- 3 - YUV422 PLANAR
- 4 - YUR420 PLANAR
+
+ - 0 - RGB
+ - 1 - YUV444 PACKED
+ - 2 - YUV444 PLANAR
+ - 3 - YUV422 PLANAR
+ - 4 - YUR420 PLANAR
XPOS - starting horizontal position
+
YPOS - starting vertical position
diff --git a/Documentation/fb/s3fb.txt b/Documentation/fb/s3fb.rst
similarity index 94%
rename from Documentation/fb/s3fb.txt
rename to Documentation/fb/s3fb.rst
index 2c97770bdbaa..e809d69c21a7 100644
--- a/Documentation/fb/s3fb.txt
+++ b/Documentation/fb/s3fb.rst
@@ -1,6 +1,6 @@
-
- s3fb - fbdev driver for S3 Trio/Virge chips
- ===========================================
+===========================================
+s3fb - fbdev driver for S3 Trio/Virge chips
+===========================================
Supported Hardware
@@ -56,7 +56,7 @@ Missing Features
(alias TODO list)
* secondary (not initialized by BIOS) device support
- * big endian support
+ * big endian support
* Zorro bus support
* MMIO support
* 24 bpp mode support on more cards
diff --git a/Documentation/fb/sa1100fb.txt b/Documentation/fb/sa1100fb.rst
similarity index 64%
rename from Documentation/fb/sa1100fb.txt
rename to Documentation/fb/sa1100fb.rst
index f1b4220464df..67e2650e017d 100644
--- a/Documentation/fb/sa1100fb.txt
+++ b/Documentation/fb/sa1100fb.rst
@@ -1,17 +1,19 @@
-[This file is cloned from VesaFB/matroxfb]
-
+=================
What is sa1100fb?
=================
+.. [This file is cloned from VesaFB/matroxfb]
+
+
This is a driver for a graphic framebuffer for the SA-1100 LCD
controller.
Configuration
==============
-For most common passive displays, giving the option
+For most common passive displays, giving the option::
-video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value>
+ video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value>
on the kernel command line should be enough to configure the
controller. The bits per pixel (bpp) value should be 4, 8, 12, or
@@ -27,13 +29,12 @@ sa1100fb_init_fbinfo(), sa1100fb_activate_var(),
sa1100fb_disable_lcd_controller(), and sa1100fb_enable_lcd_controller()
will probably be necessary.
-Accepted options:
+Accepted options::
-bpp:<value> Configure for <value> bits per pixel
-lccr0:<value> Configure LCD control register 0 (11.7.3)
-lccr1:<value> Configure LCD control register 1 (11.7.4)
-lccr2:<value> Configure LCD control register 2 (11.7.5)
-lccr3:<value> Configure LCD control register 3 (11.7.6)
+ bpp:<value> Configure for <value> bits per pixel
+ lccr0:<value> Configure LCD control register 0 (11.7.3)
+ lccr1:<value> Configure LCD control register 1 (11.7.4)
+ lccr2:<value> Configure LCD control register 2 (11.7.5)
+ lccr3:<value> Configure LCD control register 3 (11.7.6)
---
Mark Huang <[email protected]>
diff --git a/Documentation/fb/sh7760fb.txt b/Documentation/fb/sh7760fb.rst
similarity index 39%
rename from Documentation/fb/sh7760fb.txt
rename to Documentation/fb/sh7760fb.rst
index b994c3b10549..c3266485f810 100644
--- a/Documentation/fb/sh7760fb.txt
+++ b/Documentation/fb/sh7760fb.rst
@@ -1,3 +1,4 @@
+================================================
SH7760/SH7763 integrated LCDC Framebuffer driver
================================================
@@ -8,6 +9,7 @@ supports (in theory) resolutions ranging from 1x1 to 1024x1024,
with color depths ranging from 1 to 16 bits, on STN, DSTN and TFT Panels.
Caveats:
+
* Framebuffer memory must be a large chunk allocated at the top
of Area3 (HW requirement). Because of this requirement you should NOT
make the driver a module since at runtime it may become impossible to
@@ -23,9 +25,10 @@ Caveats:
* Rotation works only 90degress clockwise, and only if horizontal
resolution is <= 320 pixels.
-files: drivers/video/sh7760fb.c
- include/asm-sh/sh7760fb.h
- Documentation/fb/sh7760fb.txt
+Files:
+ - drivers/video/sh7760fb.c
+ - include/asm-sh/sh7760fb.h
+ - Documentation/fb/sh7760fb.rst
1. Platform setup
-----------------
@@ -50,82 +53,78 @@ Suggest you take a closer look at the SH7760 Manual, Section 30.
(http://documentation.renesas.com/eng/products/mpumcu/e602291_sh7760.pdf)
The following code illustrates what needs to be done to
-get the framebuffer working on a 640x480 TFT:
+get the framebuffer working on a 640x480 TFT::
-====================== cut here ======================================
+ #include <linux/fb.h>
+ #include <asm/sh7760fb.h>
-#include <linux/fb.h>
-#include <asm/sh7760fb.h>
+ /*
+ * NEC NL6440bc26-01 640x480 TFT
+ * dotclock 25175 kHz
+ * Xres 640 Yres 480
+ * Htotal 800 Vtotal 525
+ * HsynStart 656 VsynStart 490
+ * HsynLenn 30 VsynLenn 2
+ *
+ * The linux framebuffer layer does not use the syncstart/synclen
+ * values but right/left/upper/lower margin values. The comments
+ * for the x_margin explain how to calculate those from given
+ * panel sync timings.
+ */
+ static struct fb_videomode nl6448bc26 = {
+ .name = "NL6448BC26",
+ .refresh = 60,
+ .xres = 640,
+ .yres = 480,
+ .pixclock = 39683, /* in picoseconds! */
+ .hsync_len = 30,
+ .vsync_len = 2,
+ .left_margin = 114, /* HTOT - (HSYNSLEN + HSYNSTART) */
+ .right_margin = 16, /* HSYNSTART - XRES */
+ .upper_margin = 33, /* VTOT - (VSYNLEN + VSYNSTART) */
+ .lower_margin = 10, /* VSYNSTART - YRES */
+ .sync = FB_SYNC_HOR_HIGH_ACT | FB_SYNC_VERT_HIGH_ACT,
+ .vmode = FB_VMODE_NONINTERLACED,
+ .flag = 0,
+ };
-/*
- * NEC NL6440bc26-01 640x480 TFT
- * dotclock 25175 kHz
- * Xres 640 Yres 480
- * Htotal 800 Vtotal 525
- * HsynStart 656 VsynStart 490
- * HsynLenn 30 VsynLenn 2
- *
- * The linux framebuffer layer does not use the syncstart/synclen
- * values but right/left/upper/lower margin values. The comments
- * for the x_margin explain how to calculate those from given
- * panel sync timings.
- */
-static struct fb_videomode nl6448bc26 = {
- .name = "NL6448BC26",
- .refresh = 60,
- .xres = 640,
- .yres = 480,
- .pixclock = 39683, /* in picoseconds! */
- .hsync_len = 30,
- .vsync_len = 2,
- .left_margin = 114, /* HTOT - (HSYNSLEN + HSYNSTART) */
- .right_margin = 16, /* HSYNSTART - XRES */
- .upper_margin = 33, /* VTOT - (VSYNLEN + VSYNSTART) */
- .lower_margin = 10, /* VSYNSTART - YRES */
- .sync = FB_SYNC_HOR_HIGH_ACT | FB_SYNC_VERT_HIGH_ACT,
- .vmode = FB_VMODE_NONINTERLACED,
- .flag = 0,
-};
+ static struct sh7760fb_platdata sh7760fb_nl6448 = {
+ .def_mode = &nl6448bc26,
+ .ldmtr = LDMTR_TFT_COLOR_16, /* 16bit TFT panel */
+ .lddfr = LDDFR_8BPP, /* we want 8bit output */
+ .ldpmmr = 0x0070,
+ .ldpspr = 0x0500,
+ .ldaclnr = 0,
+ .ldickr = LDICKR_CLKSRC(LCDC_CLKSRC_EXTERNAL) |
+ LDICKR_CLKDIV(1),
+ .rotate = 0,
+ .novsync = 1,
+ .blank = NULL,
+ };
-static struct sh7760fb_platdata sh7760fb_nl6448 = {
- .def_mode = &nl6448bc26,
- .ldmtr = LDMTR_TFT_COLOR_16, /* 16bit TFT panel */
- .lddfr = LDDFR_8BPP, /* we want 8bit output */
- .ldpmmr = 0x0070,
- .ldpspr = 0x0500,
- .ldaclnr = 0,
- .ldickr = LDICKR_CLKSRC(LCDC_CLKSRC_EXTERNAL) |
- LDICKR_CLKDIV(1),
- .rotate = 0,
- .novsync = 1,
- .blank = NULL,
-};
+ /* SH7760:
+ * 0xFE300800: 256 * 4byte xRGB palette ram
+ * 0xFE300C00: 42 bytes ctrl registers
+ */
+ static struct resource sh7760_lcdc_res[] = {
+ [0] = {
+ .start = 0xFE300800,
+ .end = 0xFE300CFF,
+ .flags = IORESOURCE_MEM,
+ },
+ [1] = {
+ .start = 65,
+ .end = 65,
+ .flags = IORESOURCE_IRQ,
+ },
+ };
-/* SH7760:
- * 0xFE300800: 256 * 4byte xRGB palette ram
- * 0xFE300C00: 42 bytes ctrl registers
- */
-static struct resource sh7760_lcdc_res[] = {
- [0] = {
- .start = 0xFE300800,
- .end = 0xFE300CFF,
- .flags = IORESOURCE_MEM,
- },
- [1] = {
- .start = 65,
- .end = 65,
- .flags = IORESOURCE_IRQ,
- },
-};
-
-static struct platform_device sh7760_lcdc_dev = {
- .dev = {
- .platform_data = &sh7760fb_nl6448,
- },
- .name = "sh7760-lcdc",
- .id = -1,
- .resource = sh7760_lcdc_res,
- .num_resources = ARRAY_SIZE(sh7760_lcdc_res),
-};
-
-====================== cut here ======================================
+ static struct platform_device sh7760_lcdc_dev = {
+ .dev = {
+ .platform_data = &sh7760fb_nl6448,
+ },
+ .name = "sh7760-lcdc",
+ .id = -1,
+ .resource = sh7760_lcdc_res,
+ .num_resources = ARRAY_SIZE(sh7760_lcdc_res),
+ };
diff --git a/Documentation/fb/sisfb.txt b/Documentation/fb/sisfb.rst
similarity index 85%
rename from Documentation/fb/sisfb.txt
rename to Documentation/fb/sisfb.rst
index 2e68e503e72f..8f4e502ea12e 100644
--- a/Documentation/fb/sisfb.txt
+++ b/Documentation/fb/sisfb.rst
@@ -1,4 +1,4 @@
-
+==============
What is sisfb?
==============
@@ -41,11 +41,11 @@ statement to add the parameters to the kernel command line. Please see lilo's
parameters are given with the modprobe (or insmod) command.
Example for sisfb as part of the static kernel: Add the following line to your
-lilo.conf:
+lilo.conf::
append="video=sisfb:mode:1024x768x16,mem:12288,rate:75"
-Example for sisfb as a module: Start sisfb by typing
+Example for sisfb as a module: Start sisfb by typing::
modprobe sisfb mode=1024x768x16 rate=75 mem=12288
@@ -57,7 +57,7 @@ described above or the vesa keyword instead of mode). If compiled as a module,
the parameter format reads mode=none or mode=1024x768x16 (or whatever mode you
want to use). Using a "=" for a ":" (and vice versa) is a huge difference!
Additionally: If you give more than one argument to the in-kernel sisfb, the
-arguments are separated with ",". For example:
+arguments are separated with ",". For example::
video=sisfb:mode:1024x768x16,rate:75,mem:12288
@@ -73,6 +73,7 @@ supported options including some explanation.
The desired display mode can be specified using the keyword "mode" with
a parameter in one of the following formats:
+
- XxYxDepth or
- XxY-Depth or
- XxY-Depth@Rate or
@@ -130,29 +131,30 @@ Configuration
(Some) accepted options:
-off - Disable sisfb. This option is only understood if sisfb is
- in-kernel, not a module.
-mem:X - size of memory for the console, rest will be used for DRI/DRM. X
- is in kilobytes. On 300 series, the default is 4096, 8192 or
+========= ==================================================================
+off Disable sisfb. This option is only understood if sisfb is
+ in-kernel, not a module.
+mem:X size of memory for the console, rest will be used for DRI/DRM. X
+ is in kilobytes. On 300 series, the default is 4096, 8192 or
16384 (each in kilobyte) depending on how much video ram the card
- has. On 315/330 series, the default is the maximum available ram
+ has. On 315/330 series, the default is the maximum available ram
(since DRI/DRM is not supported for these chipsets).
-noaccel - do not use 2D acceleration engine. (Default: use acceleration)
-noypan - disable y-panning and scroll by redrawing the entire screen.
- This is much slower than y-panning. (Default: use y-panning)
-vesa:X - selects startup videomode. X is number from 0 to 0x1FF and
- represents the VESA mode number (can be given in decimal or
+noaccel do not use 2D acceleration engine. (Default: use acceleration)
+noypan disable y-panning and scroll by redrawing the entire screen.
+ This is much slower than y-panning. (Default: use y-panning)
+vesa:X selects startup videomode. X is number from 0 to 0x1FF and
+ represents the VESA mode number (can be given in decimal or
hexadecimal form, the latter prefixed with "0x").
-mode:X - selects startup videomode. Please see above for the format of
- "X".
+mode:X selects startup videomode. Please see above for the format of
+ "X".
+========= ==================================================================
Boolean options such as "noaccel" or "noypan" are to be given without a
parameter if sisfb is in-kernel (for example "video=sisfb:noypan). If
sisfb is a module, these are to be set to 1 (for example "modprobe sisfb
noypan=1").
---
+
Thomas Winischhofer <[email protected]>
+
May 27, 2004
-
-
diff --git a/Documentation/fb/sm501.txt b/Documentation/fb/sm501.rst
similarity index 65%
rename from Documentation/fb/sm501.txt
rename to Documentation/fb/sm501.rst
index 187f3b3ccb6c..03e02c8042a7 100644
--- a/Documentation/fb/sm501.txt
+++ b/Documentation/fb/sm501.rst
@@ -1,6 +1,11 @@
+=======
+sm501fb
+=======
+
Configuration:
-You can pass the following kernel command line options to sm501 videoframebuffer:
+You can pass the following kernel command line options to sm501
+videoframebuffer::
sm501fb.bpp= SM501 Display driver:
Specify bits-per-pixel if not specified by 'mode'
diff --git a/Documentation/fb/sm712fb.txt b/Documentation/fb/sm712fb.rst
similarity index 59%
rename from Documentation/fb/sm712fb.txt
rename to Documentation/fb/sm712fb.rst
index c388442edf51..994dad3b0238 100644
--- a/Documentation/fb/sm712fb.txt
+++ b/Documentation/fb/sm712fb.rst
@@ -1,5 +1,6 @@
+================
What is sm712fb?
-=================
+================
This is a graphics framebuffer driver for Silicon Motion SM712 based processors.
@@ -15,13 +16,16 @@ You should not compile-in vesafb.
Currently supported video modes are:
-[Graphic modes]
+Graphic modes
+-------------
-bpp | 640x480 800x600 1024x768 1280x1024
-----+--------------------------------------------
- 8 | 0x301 0x303 0x305 0x307
- 16 | 0x311 0x314 0x317 0x31A
- 24 | 0x312 0x315 0x318 0x31B
+=== ======= ======= ======== =========
+bpp 640x480 800x600 1024x768 1280x1024
+=== ======= ======= ======== =========
+ 8 0x301 0x303 0x305 0x307
+ 16 0x311 0x314 0x317 0x31A
+ 24 0x312 0x315 0x318 0x31B
+=== ======= ======= ======== =========
Missing Features
================
diff --git a/Documentation/fb/sstfb.txt b/Documentation/fb/sstfb.rst
similarity index 28%
rename from Documentation/fb/sstfb.txt
rename to Documentation/fb/sstfb.rst
index 13db1075e4a5..8e8c1b940359 100644
--- a/Documentation/fb/sstfb.txt
+++ b/Documentation/fb/sstfb.rst
@@ -1,93 +1,114 @@
+=====
+sstfb
+=====
Introduction
+============
- This is a frame buffer device driver for 3dfx' Voodoo Graphics
- (aka voodoo 1, aka sst1) and Voodoo² (aka Voodoo 2, aka CVG) based
- video boards. It's highly experimental code, but is guaranteed to work
- on my computer, with my "Maxi Gamer 3D" and "Maxi Gamer 3d²" boards,
- and with me "between chair and keyboard". Some people tested other
- combinations and it seems that it works.
- The main page is located at <http://sstfb.sourceforge.net>, and if
- you want the latest version, check out the CVS, as the driver is a work
- in progress, I feel uncomfortable with releasing tarballs of something
- not completely working...Don't worry, it's still more than usable
- (I eat my own dog food)
+This is a frame buffer device driver for 3dfx' Voodoo Graphics
+(aka voodoo 1, aka sst1) and Voodoo² (aka Voodoo 2, aka CVG) based
+video boards. It's highly experimental code, but is guaranteed to work
+on my computer, with my "Maxi Gamer 3D" and "Maxi Gamer 3d²" boards,
+and with me "between chair and keyboard". Some people tested other
+combinations and it seems that it works.
+The main page is located at <http://sstfb.sourceforge.net>, and if
+you want the latest version, check out the CVS, as the driver is a work
+in progress, I feel uncomfortable with releasing tarballs of something
+not completely working...Don't worry, it's still more than usable
+(I eat my own dog food)
- Please read the Bug section, and report any success or failure to me
- (Ghozlane Toumi <[email protected]>).
- BTW, If you have only one monitor , and you don't feel like playing
- with the vga passthrou cable, I can only suggest borrowing a screen
- somewhere...
+Please read the Bug section, and report any success or failure to me
+(Ghozlane Toumi <[email protected]>).
+BTW, If you have only one monitor , and you don't feel like playing
+with the vga passthrou cable, I can only suggest borrowing a screen
+somewhere...
-Installation
+Installation
+============
- This driver (should) work on ix86, with "late" 2.2.x kernel (tested
- with x = 19) and "recent" 2.4.x kernel, as a module or compiled in.
- It has been included in mainstream kernel since the infamous 2.4.10.
- You can apply the patches found in sstfb/kernel/*-2.{2|4}.x.patch,
- and copy sstfb.c to linux/drivers/video/, or apply a single patch,
- sstfb/patch-2.{2|4}.x-sstfb-yymmdd to your linux source tree.
+This driver (should) work on ix86, with "late" 2.2.x kernel (tested
+with x = 19) and "recent" 2.4.x kernel, as a module or compiled in.
+It has been included in mainstream kernel since the infamous 2.4.10.
+You can apply the patches found in `sstfb/kernel/*-2.{2|4}.x.patch`,
+and copy sstfb.c to linux/drivers/video/, or apply a single patch,
+`sstfb/patch-2.{2|4}.x-sstfb-yymmdd` to your linux source tree.
- Then configure your kernel as usual: choose "m" or "y" to 3Dfx Voodoo
- Graphics in section "console". Compile, install, have fun... and please
- drop me a report :)
+Then configure your kernel as usual: choose "m" or "y" to 3Dfx Voodoo
+Graphics in section "console". Compile, install, have fun... and please
+drop me a report :)
Module Usage
-
- Warnings.
- # You should read completely this section before issuing any command.
- # If you have only one monitor to play with, once you insmod the
+============
+
+.. warning::
+
+ #. You should read completely this section before issuing any command.
+
+ #. If you have only one monitor to play with, once you insmod the
module, the 3dfx takes control of the output, so you'll have to
plug the monitor to the "normal" video board in order to issue
the commands, or you can blindly use sst_dbg_vgapass
- in the tools directory (See Tools). The latest solution is pass the
+ in the tools directory (See Tools). The latest solution is pass the
parameter vgapass=1 when insmodding the driver. (See Kernel/Modules
Options)
- Module insertion:
- # insmod sstfb.o
- you should see some strange output from the board:
+Module insertion
+----------------
+
+ #. insmod sstfb.o
+
+ you should see some strange output from the board:
a big blue square, a green and a red small squares and a vertical
white rectangle. why? the function's name is self-explanatory:
"sstfb_test()"...
(if you don't have a second monitor, you'll have to plug your monitor
directly to the 2D videocard to see what you're typing)
- # con2fb /dev/fbx /dev/ttyx
+
+ #. con2fb /dev/fbx /dev/ttyx
+
bind a tty to the new frame buffer. if you already have a frame
- buffer driver, the voodoo fb will likely be /dev/fb1. if not,
- the device will be /dev/fb0. You can check this by doing a
+ buffer driver, the voodoo fb will likely be /dev/fb1. if not,
+ the device will be /dev/fb0. You can check this by doing a
cat /proc/fb. You can find a copy of con2fb in tools/ directory.
if you don't have another fb device, this step is superfluous,
as the console subsystem automagicaly binds ttys to the fb.
- # switch to the virtual console you just mapped. "tadaaa" ...
+ #. switch to the virtual console you just mapped. "tadaaa" ...
+
+Module removal
+--------------
+
+ #. con2fb /dev/fbx /dev/ttyx
- Module removal:
- # con2fb /dev/fbx /dev/ttyx
bind the tty to the old frame buffer so the module can be removed.
(how does it work with vgacon ? short answer : it doesn't work)
- # rmmod sstfb
+
+ #. rmmod sstfb
Kernel/Modules Options
+----------------------
- You can pass some options to the sstfb module, and via the kernel
- command line when the driver is compiled in:
- for module : insmod sstfb.o option1=value1 option2=value2 ...
- in kernel : video=sstfb:option1,option2:value2,option3 ...
-
- sstfb supports the following options :
+You can pass some options to the sstfb module, and via the kernel
+command line when the driver is compiled in:
+for module : insmod sstfb.o option1=value1 option2=value2 ...
+in kernel : video=sstfb:option1,option2:value2,option3 ...
+sstfb supports the following options:
+
+=============== =============== ===============================================
Module Kernel Description
-
+=============== =============== ===============================================
vgapass=0 vganopass Enable or disable VGA passthrou cable.
vgapass=1 vgapass When enabled, the monitor will get the signal
from the VGA board and not from the voodoo.
+
Default: nopass
mem=x mem:x Force frame buffer memory in MiB
allowed values: 0, 1, 2, 4.
+
Default: 0 (= autodetect)
inverse=1 inverse Supposed to enable inverse console.
@@ -96,79 +117,91 @@ inverse=1 inverse Supposed to enable inverse console.
clipping=1 clipping Enable or disable clipping.
clipping=0 noclipping With clipping enabled, all offscreen
reads and writes are discarded.
+
Default: enable clipping.
gfxclk=x gfxclk:x Force graphic clock frequency (in MHz).
Be careful with this option, it may be
DANGEROUS.
- Default: auto
- 50Mhz for Voodoo 1,
- 75MHz for Voodoo 2.
+
+ Default: auto
+
+ - 50Mhz for Voodoo 1,
+ - 75MHz for Voodoo 2.
slowpci=1 fastpci Enable or disable fast PCI read/writes.
slowpci=1 slowpci Default : fastpci
dev=x dev:x Attach the driver to device number x.
- 0 is the first compatible board (in
+ 0 is the first compatible board (in
lspci order)
+=============== =============== ===============================================
Tools
+=====
- These tools are mostly for debugging purposes, but you can
- find some of these interesting :
- - con2fb , maps a tty to a fbramebuffer .
- con2fb /dev/fb1 /dev/tty5
- - sst_dbg_vgapass , changes vga passthrou. You have to recompile the
- driver with SST_DEBUG and SST_DEBUG_IOCTL set to 1
- sst_dbg_vgapass /dev/fb1 1 (enables vga cable)
- sst_dbg_vgapass /dev/fb1 0 (disables vga cable)
- - glide_reset , resets the voodoo using glide
- use this after rmmoding sstfb, if the module refuses to
- reinsert .
+These tools are mostly for debugging purposes, but you can
+find some of these interesting:
+
+- `con2fb`, maps a tty to a fbramebuffer::
+
+ con2fb /dev/fb1 /dev/tty5
+
+- `sst_dbg_vgapass`, changes vga passthrou. You have to recompile the
+ driver with SST_DEBUG and SST_DEBUG_IOCTL set to 1::
+
+ sst_dbg_vgapass /dev/fb1 1 (enables vga cable)
+ sst_dbg_vgapass /dev/fb1 0 (disables vga cable)
+
+- `glide_reset`, resets the voodoo using glide
+ use this after rmmoding sstfb, if the module refuses to
+ reinsert.
Bugs
+====
- - DO NOT use glide while the sstfb module is in, you'll most likely
- hang your computer.
- - If you see some artefacts (pixels not cleaning and stuff like that),
- try turning off clipping (clipping=0), and/or using slowpci
- - the driver don't detect the 4Mb frame buffer voodoos, it seems that
- the 2 last Mbs wrap around. looking into that .
- - The driver is 16 bpp only, 24/32 won't work.
- - The driver is not your_favorite_toy-safe. this includes SMP...
- [Actually from inspection it seems to be safe - Alan]
- - When using XFree86 FBdev (X over fbdev) you may see strange color
- patterns at the border of your windows (the pixels lose the lowest
- byte -> basically the blue component and some of the green). I'm unable
- to reproduce this with XFree86-3.3, but one of the testers has this
- problem with XFree86-4. Apparently recent Xfree86-4.x solve this
- problem.
- - I didn't really test changing the palette, so you may find some weird
- things when playing with that.
- - Sometimes the driver will not recognise the DAC, and the
- initialisation will fail. This is specifically true for
- voodoo 2 boards, but it should be solved in recent versions. Please
- contact me.
- - The 24/32 is not likely to work anytime soon, knowing that the
- hardware does ... unusual things in 24/32 bpp.
- - When used with another video board, current limitations of the linux
- console subsystem can cause some troubles, specifically, you should
- disable software scrollback, as it can oops badly ...
+- DO NOT use glide while the sstfb module is in, you'll most likely
+ hang your computer.
+- If you see some artefacts (pixels not cleaning and stuff like that),
+ try turning off clipping (clipping=0), and/or using slowpci
+- the driver don't detect the 4Mb frame buffer voodoos, it seems that
+ the 2 last Mbs wrap around. looking into that .
+- The driver is 16 bpp only, 24/32 won't work.
+- The driver is not your_favorite_toy-safe. this includes SMP...
+
+ [Actually from inspection it seems to be safe - Alan]
+
+- When using XFree86 FBdev (X over fbdev) you may see strange color
+ patterns at the border of your windows (the pixels lose the lowest
+ byte -> basically the blue component and some of the green). I'm unable
+ to reproduce this with XFree86-3.3, but one of the testers has this
+ problem with XFree86-4. Apparently recent Xfree86-4.x solve this
+ problem.
+- I didn't really test changing the palette, so you may find some weird
+ things when playing with that.
+- Sometimes the driver will not recognise the DAC, and the
+ initialisation will fail. This is specifically true for
+ voodoo 2 boards, but it should be solved in recent versions. Please
+ contact me.
+- The 24/32 is not likely to work anytime soon, knowing that the
+ hardware does ... unusual things in 24/32 bpp.
+- When used with another video board, current limitations of the linux
+ console subsystem can cause some troubles, specifically, you should
+ disable software scrollback, as it can oops badly ...
Todo
+====
- - Get rid of the previous paragraph.
- - Buy more coffee.
- - test/port to other arch.
- - try to add panning using tweeks with front and back buffer .
- - try to implement accel on voodoo2, this board can actually do a
- lot in 2D even if it was sold as a 3D only board ...
+- Get rid of the previous paragraph.
+- Buy more coffee.
+- test/port to other arch.
+- try to add panning using tweeks with front and back buffer .
+- try to implement accel on voodoo2, this board can actually do a
+ lot in 2D even if it was sold as a 3D only board ...
-ghoz.
-
---
Ghozlane Toumi <[email protected]>
-$Date: 2002/05/09 20:11:45 $
+Date: 2002/05/09 20:11:45
+
http://sstfb.sourceforge.net/README
diff --git a/Documentation/fb/tgafb.txt b/Documentation/fb/tgafb.rst
similarity index 71%
rename from Documentation/fb/tgafb.txt
rename to Documentation/fb/tgafb.rst
index 250083ada8fb..0c50d2134aa4 100644
--- a/Documentation/fb/tgafb.txt
+++ b/Documentation/fb/tgafb.rst
@@ -1,15 +1,14 @@
-$Id: tgafb.txt,v 1.1.2.2 2000/04/04 06:50:18 mato Exp $
-
+==============
What is tgafb?
-===============
+==============
This is a driver for DECChip 21030 based graphics framebuffers, a.k.a. TGA
cards, which are usually found in older Digital Alpha systems. The
following models are supported:
-ZLxP-E1 (8bpp, 2 MB VRAM)
-ZLxP-E2 (32bpp, 8 MB VRAM)
-ZLxP-E3 (32bpp, 16 MB VRAM, Zbuffer)
+- ZLxP-E1 (8bpp, 2 MB VRAM)
+- ZLxP-E2 (32bpp, 8 MB VRAM)
+- ZLxP-E3 (32bpp, 16 MB VRAM, Zbuffer)
This version is an almost complete rewrite of the code written by Geert
Uytterhoeven, which was based on the original TGA console code written by
@@ -18,7 +17,7 @@ Jay Estabrook.
Major new features since Linux 2.0.x:
* Support for multiple resolutions
- * Support for fixed-frequency and other oddball monitors
+ * Support for fixed-frequency and other oddball monitors
(by allowing the video mode to be set at boot time)
User-visible changes since Linux 2.2.x:
@@ -36,19 +35,22 @@ Configuration
=============
You can pass kernel command line options to tgafb with
-`video=tgafb:option1,option2:value2,option3' (multiple options should be
-separated by comma, values are separated from options by `:').
+`video=tgafb:option1,option2:value2,option3` (multiple options should be
+separated by comma, values are separated from options by `:`).
+
Accepted options:
-font:X - default font to use. All fonts are supported, including the
- SUN12x22 font which is very nice at high resolutions.
+========== ============================================================
+font:X default font to use. All fonts are supported, including the
+ SUN12x22 font which is very nice at high resolutions.
-mode:X - default video mode. The following video modes are supported:
- 640x480-60, 800x600-56, 640x480-72, 800x600-60, 800x600-72,
+mode:X default video mode. The following video modes are supported:
+ 640x480-60, 800x600-56, 640x480-72, 800x600-60, 800x600-72,
1024x768-60, 1152x864-60, 1024x768-70, 1024x768-76,
1152x864-70, 1280x1024-61, 1024x768-85, 1280x1024-70,
1152x864-84, 1280x1024-76, 1280x1024-85
-
+========== ============================================================
+
Known Issues
============
diff --git a/Documentation/fb/tridentfb.txt b/Documentation/fb/tridentfb.rst
similarity index 70%
rename from Documentation/fb/tridentfb.txt
rename to Documentation/fb/tridentfb.rst
index 45d9de5b13a3..7921c9dee78c 100644
--- a/Documentation/fb/tridentfb.txt
+++ b/Documentation/fb/tridentfb.rst
@@ -1,3 +1,7 @@
+=========
+Tridentfb
+=========
+
Tridentfb is a framebuffer driver for some Trident chip based cards.
The following list of chips is thought to be supported although not all are
@@ -17,6 +21,7 @@ limited comparing to the range if acceleration is disabled (see list
of parameters below).
Known bugs:
+
1. The driver randomly locks up on 3DImage975 chip with acceleration
enabled. The same happens in X11 (Xorg).
2. The ramdac speeds require some more fine tuning. It is possible to
@@ -26,28 +31,30 @@ Known bugs:
How to use it?
==============
-When booting you can pass the video parameter.
-video=tridentfb
+When booting you can pass the video parameter::
-The parameters for tridentfb are concatenated with a ':' as in this example.
+ video=tridentfb
-video=tridentfb:800x600-16@75,noaccel
+The parameters for tridentfb are concatenated with a ':' as in this example::
+
+ video=tridentfb:800x600-16@75,noaccel
The second level parameters that tridentfb understands are:
-noaccel - turns off acceleration (when it doesn't work for your card)
+======== =====================================================================
+noaccel turns off acceleration (when it doesn't work for your card)
-fp - use flat panel related stuff
-crt - assume monitor is present instead of fp
+fp use flat panel related stuff
+crt assume monitor is present instead of fp
-center - for flat panels and resolutions smaller than native size center the
+center for flat panels and resolutions smaller than native size center the
image, otherwise use
stretch
-memsize - integer value in KB, use if your card's memory size is misdetected.
+memsize integer value in KB, use if your card's memory size is misdetected.
look at the driver output to see what it says when initializing.
-memdiff - integer value in KB, should be nonzero if your card reports
+memdiff integer value in KB, should be nonzero if your card reports
more memory than it actually has. For instance mine is 192K less than
detection says in all three BIOS selectable situations 2M, 4M, 8M.
Only use if your video memory is taken from main memory hence of
@@ -56,12 +63,13 @@ memdiff - integer value in KB, should be nonzero if your card reports
at the bottom this might help by not letting change to that mode
anymore.
-nativex - the width in pixels of the flat panel.If you know it (usually 1024
+nativex the width in pixels of the flat panel.If you know it (usually 1024
800 or 1280) and it is not what the driver seems to detect use it.
-bpp - bits per pixel (8,16 or 32)
-mode - a mode name like 800x600-8@75 as described in
- Documentation/fb/modedb.txt
+bpp bits per pixel (8,16 or 32)
+mode a mode name like 800x600-8@75 as described in
+ Documentation/fb/modedb.rst
+======== =====================================================================
Using insane values for the above parameters will probably result in driver
misbehaviour so take care(for instance memsize=12345678 or memdiff=23784 or
diff --git a/Documentation/fb/udlfb.txt b/Documentation/fb/udlfb.rst
similarity index 77%
rename from Documentation/fb/udlfb.txt
rename to Documentation/fb/udlfb.rst
index c985cb65dd06..732b37db3504 100644
--- a/Documentation/fb/udlfb.txt
+++ b/Documentation/fb/udlfb.rst
@@ -1,6 +1,6 @@
-
+==============
What is udlfb?
-===============
+==============
This is a driver for DisplayLink USB 2.0 era graphics chips.
@@ -100,6 +100,7 @@ options udlfb fb_defio=0 console=1 shadow=1
Accepted boolean options:
+=============== ================================================================
fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel
module to track changed areas of the framebuffer by page faults.
Standard fbdev applications that use mmap but that do not
@@ -109,7 +110,7 @@ fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel
more stable, and higher performance.
default: fb_defio=1
-console Allow fbcon to attach to udlfb provided framebuffers.
+console Allow fbcon to attach to udlfb provided framebuffers.
Can be disabled if fbcon and other clients
(e.g. X with --shared-vt) are in conflict.
default: console=1
@@ -119,6 +120,7 @@ shadow Allocate a 2nd framebuffer to shadow what's currently across
do not transmit. Spends host memory to save USB transfers.
Enabled by default. Only disable on very low memory systems.
default: shadow=1
+=============== ================================================================
Sysfs Attributes
================
@@ -126,34 +128,35 @@ Sysfs Attributes
Udlfb creates several files in /sys/class/graphics/fb?
Where ? is the sequential framebuffer id of the particular DisplayLink device
-edid If a valid EDID blob is written to this file (typically
- by a udev rule), then udlfb will use this EDID as a
- backup in case reading the actual EDID of the monitor
- attached to the DisplayLink device fails. This is
- especially useful for fixed panels, etc. that cannot
- communicate their capabilities via EDID. Reading
- this file returns the current EDID of the attached
- monitor (or last backup value written). This is
- useful to get the EDID of the attached monitor,
- which can be passed to utilities like parse-edid.
+======================== ========================================================
+edid If a valid EDID blob is written to this file (typically
+ by a udev rule), then udlfb will use this EDID as a
+ backup in case reading the actual EDID of the monitor
+ attached to the DisplayLink device fails. This is
+ especially useful for fixed panels, etc. that cannot
+ communicate their capabilities via EDID. Reading
+ this file returns the current EDID of the attached
+ monitor (or last backup value written). This is
+ useful to get the EDID of the attached monitor,
+ which can be passed to utilities like parse-edid.
-metrics_bytes_rendered 32-bit count of pixel bytes rendered
+metrics_bytes_rendered 32-bit count of pixel bytes rendered
-metrics_bytes_identical 32-bit count of how many of those bytes were found to be
- unchanged, based on a shadow framebuffer check
+metrics_bytes_identical 32-bit count of how many of those bytes were found to be
+ unchanged, based on a shadow framebuffer check
-metrics_bytes_sent 32-bit count of how many bytes were transferred over
- USB to communicate the resulting changed pixels to the
- hardware. Includes compression and protocol overhead
+metrics_bytes_sent 32-bit count of how many bytes were transferred over
+ USB to communicate the resulting changed pixels to the
+ hardware. Includes compression and protocol overhead
metrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the
- above pixels (in thousands of cycles).
+ above pixels (in thousands of cycles).
-metrics_reset Write-only. Any write to this file resets all metrics
- above to zero. Note that the 32-bit counters above
- roll over very quickly. To get reliable results, design
- performance tests to start and finish in a very short
- period of time (one minute or less is safe).
+metrics_reset Write-only. Any write to this file resets all metrics
+ above to zero. Note that the 32-bit counters above
+ roll over very quickly. To get reliable results, design
+ performance tests to start and finish in a very short
+ period of time (one minute or less is safe).
+======================== ========================================================
---
Bernie Thompson <[email protected]>
diff --git a/Documentation/fb/uvesafb.txt b/Documentation/fb/uvesafb.rst
similarity index 52%
rename from Documentation/fb/uvesafb.txt
rename to Documentation/fb/uvesafb.rst
index aa924196c366..d1c2523fbb33 100644
--- a/Documentation/fb/uvesafb.txt
+++ b/Documentation/fb/uvesafb.rst
@@ -1,4 +1,4 @@
-
+==========================================================
uvesafb - A Generic Driver for VBE2+ compliant video cards
==========================================================
@@ -49,7 +49,7 @@ The most important limitations are:
uvesafb can be compiled either as a module, or directly into the kernel.
In both cases it supports the same set of configuration options, which
-are either given on the kernel command line or as module parameters, e.g.:
+are either given on the kernel command line or as module parameters, e.g.::
video=uvesafb:1024x768-32,mtrr:3,ywrap (compiled into the kernel)
@@ -57,85 +57,90 @@ are either given on the kernel command line or as module parameters, e.g.:
Accepted options:
+======= =========================================================
ypan Enable display panning using the VESA protected mode
- interface. The visible screen is just a window of the
- video memory, console scrolling is done by changing the
- start of the window. This option is available on x86
- only and is the default option on that architecture.
+ interface. The visible screen is just a window of the
+ video memory, console scrolling is done by changing the
+ start of the window. This option is available on x86
+ only and is the default option on that architecture.
ywrap Same as ypan, but assumes your gfx board can wrap-around
- the video memory (i.e. starts reading from top if it
- reaches the end of video memory). Faster than ypan.
- Available on x86 only.
+ the video memory (i.e. starts reading from top if it
+ reaches the end of video memory). Faster than ypan.
+ Available on x86 only.
redraw Scroll by redrawing the affected part of the screen, this
- is the default on non-x86.
+ is the default on non-x86.
+======= =========================================================
(If you're using uvesafb as a module, the above three options are
- used a parameter of the scroll option, e.g. scroll=ypan.)
+used a parameter of the scroll option, e.g. scroll=ypan.)
-vgapal Use the standard VGA registers for palette changes.
+=========== ====================================================================
+vgapal Use the standard VGA registers for palette changes.
-pmipal Use the protected mode interface for palette changes.
- This is the default if the protected mode interface is
- available. Available on x86 only.
+pmipal Use the protected mode interface for palette changes.
+ This is the default if the protected mode interface is
+ available. Available on x86 only.
-mtrr:n Setup memory type range registers for the framebuffer
- where n:
- 0 - disabled (equivalent to nomtrr)
- 3 - write-combining (default)
+mtrr:n Setup memory type range registers for the framebuffer
+ where n:
- Values other than 0 and 3 will result in a warning and will be
- treated just like 3.
+ - 0 - disabled (equivalent to nomtrr)
+ - 3 - write-combining (default)
-nomtrr Do not use memory type range registers.
+ Values other than 0 and 3 will result in a warning and will be
+ treated just like 3.
+
+nomtrr Do not use memory type range registers.
vremap:n
- Remap 'n' MiB of video RAM. If 0 or not specified, remap memory
- according to video mode.
+ Remap 'n' MiB of video RAM. If 0 or not specified, remap memory
+ according to video mode.
-vtotal:n
- If the video BIOS of your card incorrectly determines the total
- amount of video RAM, use this option to override the BIOS (in MiB).
+vtotal:n If the video BIOS of your card incorrectly determines the total
+ amount of video RAM, use this option to override the BIOS (in MiB).
-<mode> The mode you want to set, in the standard modedb format. Refer to
- modedb.txt for a detailed description. When uvesafb is compiled as
- a module, the mode string should be provided as a value of the
- 'mode_option' option.
+<mode> The mode you want to set, in the standard modedb format. Refer to
+ modedb.txt for a detailed description. When uvesafb is compiled as
+ a module, the mode string should be provided as a value of the
+ 'mode_option' option.
-vbemode:x
- Force the use of VBE mode x. The mode will only be set if it's
- found in the VBE-provided list of supported modes.
- NOTE: The mode number 'x' should be specified in VESA mode number
- notation, not the Linux kernel one (eg. 257 instead of 769).
- HINT: If you use this option because normal <mode> parameter does
- not work for you and you use a X server, you'll probably want to
- set the 'nocrtc' option to ensure that the video mode is properly
- restored after console <-> X switches.
+vbemode:x Force the use of VBE mode x. The mode will only be set if it's
+ found in the VBE-provided list of supported modes.
+ NOTE: The mode number 'x' should be specified in VESA mode number
+ notation, not the Linux kernel one (eg. 257 instead of 769).
+ HINT: If you use this option because normal <mode> parameter does
+ not work for you and you use a X server, you'll probably want to
+ set the 'nocrtc' option to ensure that the video mode is properly
+ restored after console <-> X switches.
-nocrtc Do not use CRTC timings while setting the video mode. This option
- has any effect only if the Video BIOS is VBE 3.0 compliant. Use it
- if you have problems with modes set the standard way. Note that
- using this option implies that any refresh rate adjustments will
- be ignored and the refresh rate will stay at your BIOS default (60 Hz).
+nocrtc Do not use CRTC timings while setting the video mode. This option
+ has any effect only if the Video BIOS is VBE 3.0 compliant. Use it
+ if you have problems with modes set the standard way. Note that
+ using this option implies that any refresh rate adjustments will
+ be ignored and the refresh rate will stay at your BIOS default
+ (60 Hz).
-noedid Do not try to fetch and use EDID-provided modes.
+noedid Do not try to fetch and use EDID-provided modes.
-noblank Disable hardware blanking.
+noblank Disable hardware blanking.
-v86d:path
- Set path to the v86d executable. This option is only available as
- a module parameter, and not as a part of the video= string. If you
- need to use it and have uvesafb built into the kernel, use
- uvesafb.v86d="path".
+v86d:path Set path to the v86d executable. This option is only available as
+ a module parameter, and not as a part of the video= string. If you
+ need to use it and have uvesafb built into the kernel, use
+ uvesafb.v86d="path".
+=========== ====================================================================
Additionally, the following parameters may be provided. They all override the
EDID-provided values and BIOS defaults. Refer to your monitor's specs to get
the correct values for maxhf, maxvf and maxclk for your hardware.
+=========== ======================================
maxhf:n Maximum horizontal frequency (in kHz).
maxvf:n Maximum vertical frequency (in Hz).
maxclk:n Maximum pixel clock (in MHz).
+=========== ======================================
4. The sysfs interface
----------------------
@@ -146,27 +151,26 @@ additional information.
Driver attributes:
/sys/bus/platform/drivers/uvesafb
- - v86d (default: /sbin/v86d)
+ v86d
+ (default: /sbin/v86d)
+
Path to the v86d executable. v86d is started by uvesafb
if an instance of the daemon isn't already running.
Device attributes:
/sys/bus/platform/drivers/uvesafb/uvesafb.0
- - nocrtc
+ nocrtc
Use the default refresh rate (60 Hz) if set to 1.
- - oem_product_name
- - oem_product_rev
- - oem_string
- - oem_vendor
+ oem_product_name, oem_product_rev, oem_string, oem_vendor
Information about the card and its maker.
- - vbe_modes
+ vbe_modes
A list of video modes supported by the Video BIOS along with their
VBE mode numbers in hex.
- - vbe_version
+ vbe_version
A BCD value indicating the implemented VBE standard.
5. Miscellaneous
@@ -176,9 +180,9 @@ Uvesafb will set a video mode with the default refresh rate and timings
from the Video BIOS if you set pixclock to 0 in fb_var_screeninfo.
---
+
Michal Januszewski <[email protected]>
+
Last updated: 2017-10-10
Documentation of the uvesafb options is loosely based on vesafb.txt.
-
diff --git a/Documentation/fb/vesafb.txt b/Documentation/fb/vesafb.rst
similarity index 57%
rename from Documentation/fb/vesafb.txt
rename to Documentation/fb/vesafb.rst
index 413bb73235be..2ed0dfb661cf 100644
--- a/Documentation/fb/vesafb.txt
+++ b/Documentation/fb/vesafb.rst
@@ -1,4 +1,4 @@
-
+===============
What is vesafb?
===============
@@ -40,30 +40,35 @@ The graphic modes are NOT in the list which you get if you boot with
vga=ask and hit return. The mode you wish to use is derived from the
VESA mode number. Here are those VESA mode numbers:
- | 640x480 800x600 1024x768 1280x1024
-----+-------------------------------------
-256 | 0x101 0x103 0x105 0x107
-32k | 0x110 0x113 0x116 0x119
-64k | 0x111 0x114 0x117 0x11A
-16M | 0x112 0x115 0x118 0x11B
+====== ======= ======= ======== =========
+colors 640x480 800x600 1024x768 1280x1024
+====== ======= ======= ======== =========
+256 0x101 0x103 0x105 0x107
+32k 0x110 0x113 0x116 0x119
+64k 0x111 0x114 0x117 0x11A
+16M 0x112 0x115 0x118 0x11B
+====== ======= ======= ======== =========
+
The video mode number of the Linux kernel is the VESA mode number plus
-0x200.
-
+0x200:
+
Linux_kernel_mode_number = VESA_mode_number + 0x200
So the table for the Kernel mode numbers are:
- | 640x480 800x600 1024x768 1280x1024
-----+-------------------------------------
-256 | 0x301 0x303 0x305 0x307
-32k | 0x310 0x313 0x316 0x319
-64k | 0x311 0x314 0x317 0x31A
-16M | 0x312 0x315 0x318 0x31B
+====== ======= ======= ======== =========
+colors 640x480 800x600 1024x768 1280x1024
+====== ======= ======= ======== =========
+256 0x301 0x303 0x305 0x307
+32k 0x310 0x313 0x316 0x319
+64k 0x311 0x314 0x317 0x31A
+16M 0x312 0x315 0x318 0x31B
+====== ======= ======= ======== =========
To enable one of those modes you have to specify "vga=ask" in the
lilo.conf file and rerun LILO. Then you can type in the desired
-mode at the "vga=ask" prompt. For example if you like to use
+mode at the "vga=ask" prompt. For example if you like to use
1024x768x256 colors you have to say "305" at this prompt.
If this does not work, this might be because your BIOS does not support
@@ -72,10 +77,10 @@ Even if your board does, it might be the BIOS which does not. VESA BIOS
Extensions v2.0 are required, 1.2 is NOT sufficient. You will get a
"bad mode number" message if something goes wrong.
-1. Note: LILO cannot handle hex, for booting directly with
- "vga=mode-number" you have to transform the numbers to decimal.
+1. Note: LILO cannot handle hex, for booting directly with
+ "vga=mode-number" you have to transform the numbers to decimal.
2. Note: Some newer versions of LILO appear to work with those hex values,
- if you set the 0x in front of the numbers.
+ if you set the 0x in front of the numbers.
X11
===
@@ -120,62 +125,68 @@ Accepted options:
inverse use inverse color map
-ypan enable display panning using the VESA protected mode
- interface. The visible screen is just a window of the
- video memory, console scrolling is done by changing the
- start of the window.
- pro: * scrolling (fullscreen) is fast, because there is
+========= ======================================================================
+ypan enable display panning using the VESA protected mode
+ interface. The visible screen is just a window of the
+ video memory, console scrolling is done by changing the
+ start of the window.
+
+ pro:
+
+ * scrolling (fullscreen) is fast, because there is
no need to copy around data.
* You'll get scrollback (the Shift-PgUp thing),
the video memory can be used as scrollback buffer
- kontra: * scrolling only parts of the screen causes some
+
+ kontra:
+
+ * scrolling only parts of the screen causes some
ugly flicker effects (boot logo flickers for
example).
-ywrap Same as ypan, but assumes your gfx board can wrap-around
- the video memory (i.e. starts reading from top if it
- reaches the end of video memory). Faster than ypan.
+ywrap Same as ypan, but assumes your gfx board can wrap-around
+ the video memory (i.e. starts reading from top if it
+ reaches the end of video memory). Faster than ypan.
-redraw scroll by redrawing the affected part of the screen, this
- is the safe (and slow) default.
+redraw Scroll by redrawing the affected part of the screen, this
+ is the safe (and slow) default.
-vgapal Use the standard vga registers for palette changes.
- This is the default.
-pmipal Use the protected mode interface for palette changes.
+vgapal Use the standard vga registers for palette changes.
+ This is the default.
+pmipal Use the protected mode interface for palette changes.
-mtrr:n setup memory type range registers for the vesafb framebuffer
- where n:
- 0 - disabled (equivalent to nomtrr) (default)
- 1 - uncachable
- 2 - write-back
- 3 - write-combining
- 4 - write-through
+mtrr:n Setup memory type range registers for the vesafb framebuffer
+ where n:
- If you see the following in dmesg, choose the type that matches the
- old one. In this example, use "mtrr:2".
+ - 0 - disabled (equivalent to nomtrr) (default)
+ - 1 - uncachable
+ - 2 - write-back
+ - 3 - write-combining
+ - 4 - write-through
+
+ If you see the following in dmesg, choose the type that matches the
+ old one. In this example, use "mtrr:2".
...
-mtrr: type mismatch for e0000000,8000000 old: write-back new: write-combining
+mtrr: type mismatch for e0000000,8000000 old: write-back new:
+ write-combining
...
-nomtrr disable mtrr
+nomtrr disable mtrr
vremap:n
- remap 'n' MiB of video RAM. If 0 or not specified, remap memory
- according to video mode. (2.5.66 patch/idea by Antonino Daplas
- reversed to give override possibility (allocate more fb memory
- than the kernel would) to 2.4 by [email protected])
+ Remap 'n' MiB of video RAM. If 0 or not specified, remap memory
+ according to video mode. (2.5.66 patch/idea by Antonino Daplas
+ reversed to give override possibility (allocate more fb memory
+ than the kernel would) to 2.4 by [email protected])
-vtotal:n
- if the video BIOS of your card incorrectly determines the total
- amount of video RAM, use this option to override the BIOS (in MiB).
+vtotal:n If the video BIOS of your card incorrectly determines the total
+ amount of video RAM, use this option to override the BIOS (in MiB).
+========= ======================================================================
Have fun!
- Gerd
-
---
Gerd Knorr <[email protected]>
-Minor (mostly typo) changes
+Minor (mostly typo) changes
by Nico Schmoigl <[email protected]>
diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.rst
similarity index 18%
rename from Documentation/fb/viafb.txt
rename to Documentation/fb/viafb.rst
index 1cb2462a71ce..8eb7a3bb068c 100644
--- a/Documentation/fb/viafb.txt
+++ b/Documentation/fb/viafb.rst
@@ -1,165 +1,185 @@
+=======================================================
+VIA Integration Graphic Chip Console Framebuffer Driver
+=======================================================
- VIA Integration Graphic Chip Console Framebuffer Driver
-
-[Platform]
------------------------
+Platform
+--------
The console framebuffer driver is for graphics chips of
- VIA UniChrome Family(CLE266, PM800 / CN400 / CN300,
- P4M800CE / P4M800Pro / CN700 / VN800,
- CX700 / VX700, K8M890, P4M890,
- CN896 / P4M900, VX800, VX855)
+ VIA UniChrome Family
+ (CLE266, PM800 / CN400 / CN300,
+ P4M800CE / P4M800Pro / CN700 / VN800,
+ CX700 / VX700, K8M890, P4M890,
+ CN896 / P4M900, VX800, VX855)
-[Driver features]
-------------------------
+Driver features
+---------------
Device: CRT, LCD, DVI
- Support viafb_mode:
- CRT:
- 640x480(60, 75, 85, 100, 120 Hz), 720x480(60 Hz),
- 720x576(60 Hz), 800x600(60, 75, 85, 100, 120 Hz),
- 848x480(60 Hz), 856x480(60 Hz), 1024x512(60 Hz),
- 1024x768(60, 75, 85, 100 Hz), 1152x864(75 Hz),
- 1280x768(60 Hz), 1280x960(60 Hz), 1280x1024(60, 75, 85 Hz),
- 1440x1050(60 Hz), 1600x1200(60, 75 Hz), 1280x720(60 Hz),
- 1920x1080(60 Hz), 1400x1050(60 Hz), 800x480(60 Hz)
+ Support viafb_mode::
+
+ CRT:
+ 640x480(60, 75, 85, 100, 120 Hz), 720x480(60 Hz),
+ 720x576(60 Hz), 800x600(60, 75, 85, 100, 120 Hz),
+ 848x480(60 Hz), 856x480(60 Hz), 1024x512(60 Hz),
+ 1024x768(60, 75, 85, 100 Hz), 1152x864(75 Hz),
+ 1280x768(60 Hz), 1280x960(60 Hz), 1280x1024(60, 75, 85 Hz),
+ 1440x1050(60 Hz), 1600x1200(60, 75 Hz), 1280x720(60 Hz),
+ 1920x1080(60 Hz), 1400x1050(60 Hz), 800x480(60 Hz)
color depth: 8 bpp, 16 bpp, 32 bpp supports.
Support 2D hardware accelerator.
-[Using the viafb module]
--- -- --------------------
- Start viafb with default settings:
- #modprobe viafb
+Using the viafb module
+----------------------
+ Start viafb with default settings::
- Start viafb with user options:
- #modprobe viafb viafb_mode=800x600 viafb_bpp=16 viafb_refresh=60
- viafb_active_dev=CRT+DVI viafb_dvi_port=DVP1
- viafb_mode1=1024x768 viafb_bpp=16 viafb_refresh1=60
- viafb_SAMM_ON=1
+ #modprobe viafb
+
+ Start viafb with user options::
+
+ #modprobe viafb viafb_mode=800x600 viafb_bpp=16 viafb_refresh=60
+ viafb_active_dev=CRT+DVI viafb_dvi_port=DVP1
+ viafb_mode1=1024x768 viafb_bpp=16 viafb_refresh1=60
+ viafb_SAMM_ON=1
viafb_mode:
- 640x480 (default)
- 720x480
- 800x600
- 1024x768
- ......
+ - 640x480 (default)
+ - 720x480
+ - 800x600
+ - 1024x768
viafb_bpp:
- 8, 16, 32 (default:32)
+ - 8, 16, 32 (default:32)
viafb_refresh:
- 60, 75, 85, 100, 120 (default:60)
+ - 60, 75, 85, 100, 120 (default:60)
viafb_lcd_dsp_method:
- 0 : expansion (default)
- 1 : centering
+ - 0 : expansion (default)
+ - 1 : centering
viafb_lcd_mode:
- 0 : LCD panel with LSB data format input (default)
- 1 : LCD panel with MSB data format input
+ 0 : LCD panel with LSB data format input (default)
+ 1 : LCD panel with MSB data format input
viafb_lcd_panel_id:
- 0 : Resolution: 640x480, Channel: single, Dithering: Enable
- 1 : Resolution: 800x600, Channel: single, Dithering: Enable
- 2 : Resolution: 1024x768, Channel: single, Dithering: Enable (default)
- 3 : Resolution: 1280x768, Channel: single, Dithering: Enable
- 4 : Resolution: 1280x1024, Channel: dual, Dithering: Enable
- 5 : Resolution: 1400x1050, Channel: dual, Dithering: Enable
- 6 : Resolution: 1600x1200, Channel: dual, Dithering: Enable
+ - 0 : Resolution: 640x480, Channel: single, Dithering: Enable
+ - 1 : Resolution: 800x600, Channel: single, Dithering: Enable
+ - 2 : Resolution: 1024x768, Channel: single, Dithering: Enable (default)
+ - 3 : Resolution: 1280x768, Channel: single, Dithering: Enable
+ - 4 : Resolution: 1280x1024, Channel: dual, Dithering: Enable
+ - 5 : Resolution: 1400x1050, Channel: dual, Dithering: Enable
+ - 6 : Resolution: 1600x1200, Channel: dual, Dithering: Enable
- 8 : Resolution: 800x480, Channel: single, Dithering: Enable
- 9 : Resolution: 1024x768, Channel: dual, Dithering: Enable
- 10: Resolution: 1024x768, Channel: single, Dithering: Disable
- 11: Resolution: 1024x768, Channel: dual, Dithering: Disable
- 12: Resolution: 1280x768, Channel: single, Dithering: Disable
- 13: Resolution: 1280x1024, Channel: dual, Dithering: Disable
- 14: Resolution: 1400x1050, Channel: dual, Dithering: Disable
- 15: Resolution: 1600x1200, Channel: dual, Dithering: Disable
- 16: Resolution: 1366x768, Channel: single, Dithering: Disable
- 17: Resolution: 1024x600, Channel: single, Dithering: Enable
- 18: Resolution: 1280x768, Channel: dual, Dithering: Enable
- 19: Resolution: 1280x800, Channel: single, Dithering: Enable
+ - 8 : Resolution: 800x480, Channel: single, Dithering: Enable
+ - 9 : Resolution: 1024x768, Channel: dual, Dithering: Enable
+ - 10: Resolution: 1024x768, Channel: single, Dithering: Disable
+ - 11: Resolution: 1024x768, Channel: dual, Dithering: Disable
+ - 12: Resolution: 1280x768, Channel: single, Dithering: Disable
+ - 13: Resolution: 1280x1024, Channel: dual, Dithering: Disable
+ - 14: Resolution: 1400x1050, Channel: dual, Dithering: Disable
+ - 15: Resolution: 1600x1200, Channel: dual, Dithering: Disable
+ - 16: Resolution: 1366x768, Channel: single, Dithering: Disable
+ - 17: Resolution: 1024x600, Channel: single, Dithering: Enable
+ - 18: Resolution: 1280x768, Channel: dual, Dithering: Enable
+ - 19: Resolution: 1280x800, Channel: single, Dithering: Enable
viafb_accel:
- 0 : No 2D Hardware Acceleration
- 1 : 2D Hardware Acceleration (default)
+ - 0 : No 2D Hardware Acceleration
+ - 1 : 2D Hardware Acceleration (default)
viafb_SAMM_ON:
- 0 : viafb_SAMM_ON disable (default)
- 1 : viafb_SAMM_ON enable
+ - 0 : viafb_SAMM_ON disable (default)
+ - 1 : viafb_SAMM_ON enable
viafb_mode1: (secondary display device)
- 640x480 (default)
- 720x480
- 800x600
- 1024x768
- ... ...
+ - 640x480 (default)
+ - 720x480
+ - 800x600
+ - 1024x768
viafb_bpp1: (secondary display device)
- 8, 16, 32 (default:32)
+ - 8, 16, 32 (default:32)
viafb_refresh1: (secondary display device)
- 60, 75, 85, 100, 120 (default:60)
+ - 60, 75, 85, 100, 120 (default:60)
viafb_active_dev:
- This option is used to specify active devices.(CRT, DVI, CRT+LCD...)
- DVI stands for DVI or HDMI, E.g., If you want to enable HDMI,
- set viafb_active_dev=DVI. In SAMM case, the previous of
- viafb_active_dev is primary device, and the following is
- secondary device.
-
- For example:
- To enable one device, such as DVI only, we can use:
- modprobe viafb viafb_active_dev=DVI
- To enable two devices, such as CRT+DVI:
- modprobe viafb viafb_active_dev=CRT+DVI;
-
- For DuoView case, we can use:
- modprobe viafb viafb_active_dev=CRT+DVI
- OR
- modprobe viafb viafb_active_dev=DVI+CRT...
-
- For SAMM case:
- If CRT is primary and DVI is secondary, we should use:
- modprobe viafb viafb_active_dev=CRT+DVI viafb_SAMM_ON=1...
- If DVI is primary and CRT is secondary, we should use:
- modprobe viafb viafb_active_dev=DVI+CRT viafb_SAMM_ON=1...
+ This option is used to specify active devices.(CRT, DVI, CRT+LCD...)
+ DVI stands for DVI or HDMI, E.g., If you want to enable HDMI,
+ set viafb_active_dev=DVI. In SAMM case, the previous of
+ viafb_active_dev is primary device, and the following is
+ secondary device.
+
+ For example:
+
+ To enable one device, such as DVI only, we can use::
+
+ modprobe viafb viafb_active_dev=DVI
+
+ To enable two devices, such as CRT+DVI::
+
+ modprobe viafb viafb_active_dev=CRT+DVI;
+
+ For DuoView case, we can use::
+
+ modprobe viafb viafb_active_dev=CRT+DVI
+
+ OR::
+
+ modprobe viafb viafb_active_dev=DVI+CRT...
+
+ For SAMM case:
+
+ If CRT is primary and DVI is secondary, we should use::
+
+ modprobe viafb viafb_active_dev=CRT+DVI viafb_SAMM_ON=1...
+
+ If DVI is primary and CRT is secondary, we should use::
+
+ modprobe viafb viafb_active_dev=DVI+CRT viafb_SAMM_ON=1...
viafb_display_hardware_layout:
- This option is used to specify display hardware layout for CX700 chip.
- 1 : LCD only
- 2 : DVI only
- 3 : LCD+DVI (default)
- 4 : LCD1+LCD2 (internal + internal)
- 16: LCD1+ExternalLCD2 (internal + external)
+ This option is used to specify display hardware layout for CX700 chip.
+
+ - 1 : LCD only
+ - 2 : DVI only
+ - 3 : LCD+DVI (default)
+ - 4 : LCD1+LCD2 (internal + internal)
+ - 16: LCD1+ExternalLCD2 (internal + external)
viafb_second_size:
- This option is used to set second device memory size(MB) in SAMM case.
- The minimal size is 16.
+ This option is used to set second device memory size(MB) in SAMM case.
+ The minimal size is 16.
viafb_platform_epia_dvi:
- This option is used to enable DVI on EPIA - M
- 0 : No DVI on EPIA - M (default)
- 1 : DVI on EPIA - M
+ This option is used to enable DVI on EPIA - M
+
+ - 0 : No DVI on EPIA - M (default)
+ - 1 : DVI on EPIA - M
viafb_bus_width:
- When using 24 - Bit Bus Width Digital Interface,
- this option should be set.
- 12: 12-Bit LVDS or 12-Bit TMDS (default)
- 24: 24-Bit LVDS or 24-Bit TMDS
+ When using 24 - Bit Bus Width Digital Interface,
+ this option should be set.
+
+ - 12: 12-Bit LVDS or 12-Bit TMDS (default)
+ - 24: 24-Bit LVDS or 24-Bit TMDS
viafb_device_lcd_dualedge:
- When using Dual Edge Panel, this option should be set.
- 0 : No Dual Edge Panel (default)
- 1 : Dual Edge Panel
+ When using Dual Edge Panel, this option should be set.
+
+ - 0 : No Dual Edge Panel (default)
+ - 1 : Dual Edge Panel
viafb_lcd_port:
- This option is used to specify LCD output port,
- available values are "DVP0" "DVP1" "DFP_HIGHLOW" "DFP_HIGH" "DFP_LOW".
- for external LCD + external DVI on CX700(External LCD is on DVP0),
- we should use:
- modprobe viafb viafb_lcd_port=DVP0...
+ This option is used to specify LCD output port,
+ available values are "DVP0" "DVP1" "DFP_HIGHLOW" "DFP_HIGH" "DFP_LOW".
+
+ for external LCD + external DVI on CX700(External LCD is on DVP0),
+ we should use::
+
+ modprobe viafb viafb_lcd_port=DVP0...
Notes:
1. CRT may not display properly for DuoView CRT & DVI display at
@@ -176,77 +196,102 @@ Notes:
viafb doesn't support multi-head well, or it will cause screen crush.
-[Configure viafb with "fbset" tool]
------------------------------------
+Configure viafb with "fbset" tool
+---------------------------------
+
"fbset" is an inbox utility of Linux.
- 1. Inquire current viafb information, type,
- # fbset -i
- 2. Set various resolutions and viafb_refresh rates,
- # fbset <resolution-vertical_sync>
+ 1. Inquire current viafb information, type::
+
+ # fbset -i
+
+ 2. Set various resolutions and viafb_refresh rates::
+
+ # fbset <resolution-vertical_sync>
+
+ example::
+
+ # fbset "1024x768-75"
+
+ or::
+
+ # fbset -g 1024 768 1024 768 32
- example,
- # fbset "1024x768-75"
- or
- # fbset -g 1024 768 1024 768 32
Check the file "/etc/fb.modes" to find display modes available.
- 3. Set the color depth,
- # fbset -depth <value>
+ 3. Set the color depth::
- example,
- # fbset -depth 16
+ # fbset -depth <value>
+ example::
-[Configure viafb via /proc]
----------------------------
+ # fbset -depth 16
+
+
+Configure viafb via /proc
+-------------------------
The following files exist in /proc/viafb
supported_output_devices
+ This read-only file contains a full ',' separated list containing all
+ output devices that could be available on your platform. It is likely
+ that not all of those have a connector on your hardware but it should
+ provide a good starting point to figure out which of those names match
+ a real connector.
+
+ Example::
+
+ # cat /proc/viafb/supported_output_devices
+
+ iga1/output_devices, iga2/output_devices
+ These two files are readable and writable. iga1 and iga2 are the two
+ independent units that produce the screen image. Those images can be
+ forwarded to one or more output devices. Reading those files is a way
+ to query which output devices are currently used by an iga.
+
+ Example::
+
+ # cat /proc/viafb/iga1/output_devices
+
+ If there are no output devices printed the output of this iga is lost.
+ This can happen for example if only one (the other) iga is used.
+ Writing to these files allows adjusting the output devices during
+ runtime. One can add new devices, remove existing ones or switch
+ between igas. Essentially you can write a ',' separated list of device
+ names (or a single one) in the same format as the output to those
+ files. You can add a '+' or '-' as a prefix allowing simple addition
+ and removal of devices. So a prefix '+' adds the devices from your list
+ to the already existing ones, '-' removes the listed devices from the
+ existing ones and if no prefix is given it replaces all existing ones
+ with the listed ones. If you remove devices they are expected to turn
+ off. If you add devices that are already part of the other iga they are
+ removed there and added to the new one.
+
+ Examples:
+
+ Add CRT as output device to iga1::
+
+ # echo +CRT > /proc/viafb/iga1/output_devices
+
+ Remove (turn off) DVP1 and LVDS1 as output devices of iga2::
+
+ # echo -DVP1,LVDS1 > /proc/viafb/iga2/output_devices
+
+ Replace all iga1 output devices by CRT::
+
+ # echo CRT > /proc/viafb/iga1/output_devices
+
+
+Bootup with viafb
+-----------------
+
+Add the following line to your grub.conf::
- This read-only file contains a full ',' separated list containing all
- output devices that could be available on your platform. It is likely
- that not all of those have a connector on your hardware but it should
- provide a good starting point to figure out which of those names match
- a real connector.
- Example:
- # cat /proc/viafb/supported_output_devices
-
- iga1/output_devices
- iga2/output_devices
-
- These two files are readable and writable. iga1 and iga2 are the two
- independent units that produce the screen image. Those images can be
- forwarded to one or more output devices. Reading those files is a way
- to query which output devices are currently used by an iga.
- Example:
- # cat /proc/viafb/iga1/output_devices
- If there are no output devices printed the output of this iga is lost.
- This can happen for example if only one (the other) iga is used.
- Writing to these files allows adjusting the output devices during
- runtime. One can add new devices, remove existing ones or switch
- between igas. Essentially you can write a ',' separated list of device
- names (or a single one) in the same format as the output to those
- files. You can add a '+' or '-' as a prefix allowing simple addition
- and removal of devices. So a prefix '+' adds the devices from your list
- to the already existing ones, '-' removes the listed devices from the
- existing ones and if no prefix is given it replaces all existing ones
- with the listed ones. If you remove devices they are expected to turn
- off. If you add devices that are already part of the other iga they are
- removed there and added to the new one.
- Examples:
- Add CRT as output device to iga1
- # echo +CRT > /proc/viafb/iga1/output_devices
-
- Remove (turn off) DVP1 and LVDS1 as output devices of iga2
- # echo -DVP1,LVDS1 > /proc/viafb/iga2/output_devices
-
- Replace all iga1 output devices by CRT
- # echo CRT > /proc/viafb/iga1/output_devices
-
-
-[Bootup with viafb]:
---------------------
- Add the following line to your grub.conf:
append = "video=viafb:viafb_mode=1024x768,viafb_bpp=32,viafb_refresh=85"
+
+VIA Framebuffer modes
+=====================
+
+.. include:: viafb.modes
+ :literal:
diff --git a/Documentation/fb/vt8623fb.txt b/Documentation/fb/vt8623fb.rst
similarity index 85%
rename from Documentation/fb/vt8623fb.txt
rename to Documentation/fb/vt8623fb.rst
index f654576c56b7..ba1730937dd8 100644
--- a/Documentation/fb/vt8623fb.txt
+++ b/Documentation/fb/vt8623fb.rst
@@ -1,13 +1,13 @@
-
- vt8623fb - fbdev driver for graphics core in VIA VT8623 chipset
- ===============================================================
+===============================================================
+vt8623fb - fbdev driver for graphics core in VIA VT8623 chipset
+===============================================================
Supported Hardware
==================
- VIA VT8623 [CLE266] chipset and its graphics core
- (known as CastleRock or Unichrome)
+VIA VT8623 [CLE266] chipset and its graphics core
+(known as CastleRock or Unichrome)
I tested vt8623fb on VIA EPIA ML-6000
diff --git a/MAINTAINERS b/MAINTAINERS
index 8dece99b5502..9f83a79fdfdb 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4801,7 +4801,7 @@ S: Maintained
W: http://plugable.com/category/projects/udlfb/
F: drivers/video/fbdev/udlfb.c
F: include/video/udlfb.h
-F: Documentation/fb/udlfb.txt
+F: Documentation/fb/udlfb.rst
DISTRIBUTED LOCK MANAGER (DLM)
M: Christine Caulfield <[email protected]>
@@ -7944,7 +7944,7 @@ INTEL FRAMEBUFFER DRIVER (excluding 810 and 815)
M: Maik Broemme <[email protected]>
L: [email protected]
S: Maintained
-F: Documentation/fb/intelfb.txt
+F: Documentation/fb/intelfb.rst
F: drivers/video/fbdev/intelfb/
INTEL GPIO DRIVERS
@@ -14386,7 +14386,7 @@ M: Sudip Mukherjee <[email protected]>
L: [email protected]
S: Maintained
F: drivers/video/fbdev/sm712*
-F: Documentation/fb/sm712fb.txt
+F: Documentation/fb/sm712fb.rst
SIMPLE FIRMWARE INTERFACE (SFI)
M: Len Brown <[email protected]>
@@ -14456,7 +14456,7 @@ SIS FRAMEBUFFER DRIVER
M: Thomas Winischhofer <[email protected]>
W: http://www.winischhofer.net/linuxsisvga.shtml
S: Maintained
-F: Documentation/fb/sisfb.txt
+F: Documentation/fb/sisfb.rst
F: drivers/video/fbdev/sis/
F: include/video/sisfb.h
@@ -16663,7 +16663,7 @@ M: Michal Januszewski <[email protected]>
L: [email protected]
W: https://github.com/mjanusz/v86d
S: Maintained
-F: Documentation/fb/uvesafb.txt
+F: Documentation/fb/uvesafb.rst
F: drivers/video/fbdev/uvesafb.*
VF610 NAND DRIVER
diff --git a/drivers/tty/Kconfig b/drivers/tty/Kconfig
index 3b1d312bb175..0e3e4dacbc12 100644
--- a/drivers/tty/Kconfig
+++ b/drivers/tty/Kconfig
@@ -95,7 +95,7 @@ config VT_HW_CONSOLE_BINDING
See <file:Documentation/console/console.txt> for more
information. For framebuffer console users, please refer to
- <file:Documentation/fb/fbcon.txt>.
+ <file:Documentation/fb/fbcon.rst>.
config UNIX98_PTYS
bool "Unix98 PTY support" if EXPERT
diff --git a/drivers/video/fbdev/Kconfig b/drivers/video/fbdev/Kconfig
index 1b2f5f31fb6f..737b86328c9e 100644
--- a/drivers/video/fbdev/Kconfig
+++ b/drivers/video/fbdev/Kconfig
@@ -31,7 +31,7 @@ menuconfig FB
in the /dev directory, i.e. /dev/fb*.
You need an utility program called fbset to make full use of frame
- buffer devices. Please read <file:Documentation/fb/framebuffer.txt>
+ buffer devices. Please read <file:Documentation/fb/framebuffer.rst>
and the Framebuffer-HOWTO at
<http://www.munted.org.uk/programming/Framebuffer-HOWTO-1.3.html> for more
information.
@@ -241,7 +241,7 @@ config FB_CIRRUS
If you have a PCI-based system, this enables support for these
chips: GD-543x, GD-544x, GD-5480.
- Please read the file <file:Documentation/fb/cirrusfb.txt>.
+ Please read the file <file:Documentation/fb/cirrusfb.rst>.
Say N unless you have such a graphics board or plan to get one
before you next recompile the kernel.
@@ -614,7 +614,7 @@ config FB_UVESA
This driver generally provides more features than vesafb but
requires a userspace helper application called 'v86d'. See
- <file:Documentation/fb/uvesafb.txt> for more information.
+ <file:Documentation/fb/uvesafb.rst> for more information.
If unsure, say N.
@@ -629,7 +629,7 @@ config FB_VESA
This is the frame buffer device driver for generic VESA 2.0
compliant graphic cards. The older VESA 1.2 cards are not supported.
You will get a boot time penguin logo at no additional cost. Please
- read <file:Documentation/fb/vesafb.txt>. If unsure, say Y.
+ read <file:Documentation/fb/vesafb.rst>. If unsure, say Y.
config FB_EFI
bool "EFI-based Framebuffer Support"
@@ -825,7 +825,7 @@ config FB_PVR2
module load time. The parameters look like "video=pvr2:XXX", where
the meaning of XXX can be found at the end of the main source file
(<file:drivers/video/pvr2fb.c>). Please see the file
- <file:Documentation/fb/pvr2fb.txt>.
+ <file:Documentation/fb/pvr2fb.rst>.
config FB_OPENCORES
tristate "OpenCores VGA/LCD core 2.0 framebuffer support"
@@ -987,7 +987,7 @@ config FB_I810
module will be called i810fb.
For more information, please read
- <file:Documentation/fb/intel810.txt>
+ <file:Documentation/fb/intel810.rst>
config FB_I810_GTF
bool "use VESA Generalized Timing Formula"
@@ -1057,7 +1057,7 @@ config FB_INTEL
To compile this driver as a module, choose M here: the
module will be called intelfb.
- For more information, please read <file:Documentation/fb/intelfb.txt>
+ For more information, please read <file:Documentation/fb/intelfb.rst>
config FB_INTEL_DEBUG
bool "Intel driver Debug Messages"
@@ -1094,7 +1094,7 @@ config FB_MATROX
You can pass several parameters to the driver at boot time or at
module load time. The parameters look like "video=matroxfb:XXX", and
- are described in <file:Documentation/fb/matroxfb.txt>.
+ are described in <file:Documentation/fb/matroxfb.rst>.
config FB_MATROX_MILLENIUM
bool "Millennium I/II support"
@@ -1245,7 +1245,7 @@ config FB_ATY128
help
This driver supports graphics boards with the ATI Rage128 chips.
Say Y if you have such a graphics board and read
- <file:Documentation/fb/aty128fb.txt>.
+ <file:Documentation/fb/aty128fb.rst>.
To compile this driver as a module, choose M here: the
module will be called aty128fb.
@@ -1507,7 +1507,7 @@ config FB_VOODOO1
WARNING: Do not use any application that uses the 3D engine
(namely glide) while using this driver.
- Please read the <file:Documentation/fb/sstfb.txt> for supported
+ Please read the <file:Documentation/fb/sstfb.rst> for supported
options and other important info support.
config FB_VT8623
@@ -1539,7 +1539,7 @@ config FB_TRIDENT
There are also integrated versions of these chips called CyberXXXX,
CyberImage or CyberBlade. These chips are mostly found in laptops
but also on some motherboards including early VIA EPIA motherboards.
- For more information, read <file:Documentation/fb/tridentfb.txt>
+ For more information, read <file:Documentation/fb/tridentfb.rst>
Say Y if you have such a graphics board.
@@ -1778,7 +1778,7 @@ config FB_PXA_PARAMETERS
single model of flatpanel then you can safely leave this
option disabled.
- <file:Documentation/fb/pxafb.txt> describes the available parameters.
+ <file:Documentation/fb/pxafb.rst> describes the available parameters.
config PXA3XX_GCU
tristate "PXA3xx 2D graphics accelerator driver"
diff --git a/drivers/video/fbdev/matrox/matroxfb_base.c b/drivers/video/fbdev/matrox/matroxfb_base.c
index c76bef078c75..1a555f70923a 100644
--- a/drivers/video/fbdev/matrox/matroxfb_base.c
+++ b/drivers/video/fbdev/matrox/matroxfb_base.c
@@ -2502,7 +2502,7 @@ MODULE_PARM_DESC(nobios, "Disables ROM BIOS (0 or 1=disabled) (default=do not ch
module_param(noinit, int, 0);
MODULE_PARM_DESC(noinit, "Disables W/SG/SD-RAM and bus interface initialization (0 or 1=do not initialize) (default=0)");
module_param(memtype, int, 0);
-MODULE_PARM_DESC(memtype, "Memory type for G200/G400 (see Documentation/fb/matroxfb.txt for explanation) (default=3 for G200, 0 for G400)");
+MODULE_PARM_DESC(memtype, "Memory type for G200/G400 (see Documentation/fb/matroxfb.rst for explanation) (default=3 for G200, 0 for G400)");
module_param(mtrr, int, 0);
MODULE_PARM_DESC(mtrr, "This speeds up video memory accesses (0=disabled or 1) (default=1)");
module_param(sgram, int, 0);
diff --git a/drivers/video/fbdev/pxafb.c b/drivers/video/fbdev/pxafb.c
index d59c8a59f582..4282cb117b92 100644
--- a/drivers/video/fbdev/pxafb.c
+++ b/drivers/video/fbdev/pxafb.c
@@ -2068,7 +2068,7 @@ static int __init pxafb_setup_options(void)
#define pxafb_setup_options() (0)
module_param_string(options, g_options, sizeof(g_options), 0);
-MODULE_PARM_DESC(options, "LCD parameters (see Documentation/fb/pxafb.txt)");
+MODULE_PARM_DESC(options, "LCD parameters (see Documentation/fb/pxafb.rst)");
#endif
#else
diff --git a/drivers/video/fbdev/sh7760fb.c b/drivers/video/fbdev/sh7760fb.c
index 405715b60ec7..ab8fe838c776 100644
--- a/drivers/video/fbdev/sh7760fb.c
+++ b/drivers/video/fbdev/sh7760fb.c
@@ -6,7 +6,7 @@
* Manuel Lauss <[email protected]>
* (c) 2008 Nobuhiro Iwamatsu <[email protected]>
*
- * PLEASE HAVE A LOOK AT Documentation/fb/sh7760fb.txt!
+ * PLEASE HAVE A LOOK AT Documentation/fb/sh7760fb.rst!
*
* Thanks to Siegfried Schaefer <s.schaefer at schaefer-edv.de>
* for his original source and testing!
--
2.21.0
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 <[email protected]>
---
.../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 d5f01f7eb5ca..e4544f0335e3 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.
[email protected]
---
+
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
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 <[email protected]>
---
.../{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 <[email protected]>
+Copyright (C) 2007 Rodolfo Giometti <[email protected]>
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 01d9120bb83b..b982622ea7ee 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12689,7 +12689,7 @@ M: Rodolfo Giometti <[email protected]>
W: http://wiki.enneenne.com/index.php/LinuxPPS_support
L: [email protected] (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
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 <[email protected]>
---
...{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 <[email protected]> (19 May 1996)
-Carrying on the torch is: Erik Andersen <[email protected]>
-New maintainers (19 Oct 1998): Jens Axboe <[email protected]>
+===========================
+
+:Originally by: scott snyder <[email protected]> (19 May 1996)
+:Carrying on the torch is: Erik Andersen <[email protected]>
+:New maintainers (19 Oct 1998): Jens Axboe <[email protected]>
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 <[email protected]>.
- * Changer status information, and rewrite for the new Uniform CDROM driver
- * interface by Erik Andersen <[email protected]>.
- */
+::
-#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 <[email protected]>.
+ * Changer status information, and rewrite for the new Uniform CDROM driver
+ * interface by Erik Andersen <[email protected]>.
+ */
+ #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 10b77121b9bf..fd40fa26f062 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7631,7 +7631,7 @@ IDE/ATAPI DRIVERS
M: Borislav Petkov <[email protected]>
L: [email protected]
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
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.
Cc: Mauro Carvalho Chehab <[email protected]>, [email protected], Jonathan Corbet <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../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 ++-
...parameters.txt => watchdog-parameters.rst} | 672 +++++++++++++-----
.../{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 +-
15 files changed, 767 insertions(+), 316 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%)
rename Documentation/watchdog/{watchdog-parameters.txt => watchdog-parameters.rst} (42%)
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 <[email protected]>
-=========================================================
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
[email protected]. 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 <[email protected]>
+Support for ISA Cards Revision A and C
+=======================================
+
+Documentation and Driver by Ken Hollis <[email protected]>
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
([email protected])
-
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 <[email protected]>
@@ -10,7 +13,8 @@ driver which is (c) Copyright 2000 Jakob Oestergaard <[email protected]>
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 <[email protected]>
@@ -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.txt b/Documentation/watchdog/watchdog-parameters.rst
similarity index 42%
rename from Documentation/watchdog/watchdog-parameters.txt
rename to Documentation/watchdog/watchdog-parameters.rst
index 0b88e333f9e1..b121caae7798 100644
--- a/Documentation/watchdog/watchdog-parameters.txt
+++ b/Documentation/watchdog/watchdog-parameters.rst
@@ -1,410 +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
+ 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
+ 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
+ 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).
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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)
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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)
+ 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
+ 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')
+ 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
+ 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
+ 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
+ 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.
+ heartbeat:
+ Watchdog heartbeat in seconds.
(2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
iTCO_vendor_support:
-vendorsupport: iTCO vendor specific support mode, default=0 (none),
+ 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
+ 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
+ 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
+ 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
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
iop_wdt:
-nowayout: Watchdog cannot be stopped once started
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-action: after watchdog resets, generate:
+ 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
+ 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
+ nodelay:
+ Force selection of a timeout setting without initial delay
(max6373/74 only, default=0)
+
-------------------------------------------------
+
mixcomwd:
-nowayout: Watchdog cannot be stopped once started
+ 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
+ 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
+ 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
+ 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
+ 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.
+ heartbeat:
+ Watchdog heartbeats in seconds.
(default = 15)
-nowayout: Watchdog cannot be stopped once started
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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)
+ 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
+ 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)
+ 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
+ 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)
+ 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)
+ margin:
+ Watchdog margin in seconds (default 60s)
+
-------------------------------------------------
+
sb_wdog:
-timeout: Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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,
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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)
+ 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
+ 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
+ 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.
+ soft_margin:
+ Watchdog soft_margin in seconds.
(0 < soft_margin < 65536, default=60)
-nowayout: Watchdog cannot be stopped once started
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
-soft_noboot: Softdog action, set to 1 to ignore reboots, 0 to reboot
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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.
+ timeout:
+ Watchdog timeout in power of two seconds.
(1 <= timeout <= 128, default=64)
-nowayout: Watchdog cannot be stopped once started
+ 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
+ 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
+ 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
+ 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
+ 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)
+ 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
+ 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
+ nowayout:
+ Watchdog cannot be stopped once started
(default=kernel config parameter)
+
-------------------------------------------------
+
wm8350_wdt:
-nowayout: Watchdog cannot be stopped once started
+ 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
--------------------------------------------------
+ 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 <[email protected]>
@@ -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 <[email protected]>
+Alan Cox <[email protected]>
- 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 08efe50266b5..a9abccb2644b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7027,7 +7027,7 @@ F: drivers/media/usb/hdpvr/
HEWLETT PACKARD ENTERPRISE ILO NMI WATCHDOG DRIVER
M: Jerry Hoemann <[email protected]>
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
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 <[email protected]>
---
.../{amd-powernow.txt => amd-powernow.rst} | 11 +-
Documentation/cpu-freq/{core.txt => core.rst} | 66 +++---
.../{cpu-drivers.txt => cpu-drivers.rst} | 217 +++++++++---------
...pufreq-nforce2.txt => cpufreq-nforce2.rst} | 12 +-
.../{cpufreq-stats.txt => cpufreq-stats.rst} | 141 ++++++------
.../cpu-freq/{index.txt => index.rst} | 44 ++--
.../{pcc-cpufreq.txt => pcc-cpufreq.rst} | 102 ++++----
drivers/cpufreq/Kconfig.x86 | 2 +-
8 files changed, 302 insertions(+), 293 deletions(-)
rename Documentation/cpu-freq/{amd-powernow.txt => amd-powernow.rst} (91%)
rename Documentation/cpu-freq/{core.txt => core.rst} (67%)
rename Documentation/cpu-freq/{cpu-drivers.txt => cpu-drivers.rst} (57%)
rename Documentation/cpu-freq/{cpufreq-nforce2.txt => cpufreq-nforce2.rst} (65%)
rename Documentation/cpu-freq/{cpufreq-stats.txt => cpufreq-stats.rst} (31%)
rename Documentation/cpu-freq/{index.txt => index.rst} (37%)
rename Documentation/cpu-freq/{pcc-cpufreq.txt => pcc-cpufreq.rst} (80%)
diff --git a/Documentation/cpu-freq/amd-powernow.txt b/Documentation/cpu-freq/amd-powernow.rst
similarity index 91%
rename from Documentation/cpu-freq/amd-powernow.txt
rename to Documentation/cpu-freq/amd-powernow.rst
index 254da155fa47..50b2c45c3a2c 100644
--- a/Documentation/cpu-freq/amd-powernow.txt
+++ b/Documentation/cpu-freq/amd-powernow.rst
@@ -1,3 +1,7 @@
+=============================
+AMD powernow driver specifics
+=============================
+
PowerNow! and Cool'n'Quiet are AMD names for frequency
management capabilities in AMD processors. As the hardware
@@ -23,16 +27,19 @@ not supply these tables.
7th Generation: powernow-k7: Athlon, Duron, Geode.
8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron.
+
Documentation on this functionality in 8th generation processors
is available in the "BIOS and Kernel Developer's Guide", publication
-26094, in chapter 9, available for download from http://www.amd.com.
+26094, in chapter 9, available for download from http://www.amd.com.
BIOS supplied data, for powernow-k7 and for powernow-k8, may be
from either the PSB table or from ACPI objects. The ACPI support
is only available if the kernel config sets CONFIG_ACPI_PROCESSOR.
+
The powernow-k8 driver will attempt to use ACPI if so configured,
and fall back to PST if that fails.
+
The powernow-k7 driver will try to use the PSB support first, and
fall back to ACPI if the PSB support fails. A module parameter,
-acpi_force, is provided to force ACPI support to be used instead
+acpi_force, is provided to force ACPI support to be used instead
of PSB support.
diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.rst
similarity index 67%
rename from Documentation/cpu-freq/core.txt
rename to Documentation/cpu-freq/core.rst
index 073f128af5a7..c719e3cb700c 100644
--- a/Documentation/cpu-freq/core.txt
+++ b/Documentation/cpu-freq/core.rst
@@ -1,31 +1,22 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
+================================================================
+General description of the CPUFreq core and of CPUFreq notifiers
+================================================================
+Authors:
+ - Dominik Brodowski <[email protected]>
+ - David Kimdon <[email protected]>
+ - Rafael J. Wysocki <[email protected]>
+ - Viresh Kumar <[email protected]>
- L i n u x C P U F r e q
- C P U F r e q C o r e
+.. Contents:
-
- Dominik Brodowski <[email protected]>
- David Kimdon <[email protected]>
- Rafael J. Wysocki <[email protected]>
- Viresh Kumar <[email protected]>
-
-
-
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
-
-
-Contents:
----------
-1. CPUFreq core and interfaces
-2. CPUFreq notifiers
-3. CPUFreq Table Generation with Operating Performance Point (OPP)
+ 1. CPUFreq core and interfaces
+ 2. CPUFreq notifiers
+ 3. CPUFreq Table Generation with Operating Performance Point (OPP)
1. General Information
-=======================
+======================
The CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This
cpufreq code offers a standardized interface for the CPUFreq
@@ -60,18 +51,18 @@ transition notifiers.
These are notified when a new policy is intended to be set. Each
CPUFreq policy notifier is called twice for a policy transition:
-1.) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if
- they see a need for this - may it be thermal considerations or
- hardware limitations.
+1) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if
+ they see a need for this - may it be thermal considerations or
+ hardware limitations.
-2.) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy
- - if two hardware drivers failed to agree on a new policy before this
+2) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy -
+ if two hardware drivers failed to agree on a new policy before this
stage, the incompatible hardware shall be shut down, and the user
informed of this.
The phase is specified in the second argument to the notifier.
-The third argument, a void *pointer, points to a struct cpufreq_policy
+The third argument, a `void *` pointer, points to a struct cpufreq_policy
consisting of several values, including min, max (the lower and upper
frequencies (in kHz) of the new policy).
@@ -88,23 +79,27 @@ CPUFREQ_POSTCHANGE.
The third argument is a struct cpufreq_freqs with the following
values:
-cpu - number of the affected CPU
-old - old frequency
-new - new frequency
-flags - flags of the cpufreq driver
+
+======= ===========================
+cpu number of the affected CPU
+old old frequency
+new new frequency
+flags flags of the cpufreq driver
+======= ===========================
3. CPUFreq Table Generation with Operating Performance Point (OPP)
==================================================================
For details about OPP, see Documentation/power/opp.txt
-dev_pm_opp_init_cpufreq_table -
+dev_pm_opp_init_cpufreq_table
This function provides a ready to use conversion routine to translate
the OPP layer's internal information about the available frequencies
into a format readily providable to cpufreq.
WARNING: Do not use this function in interrupt context.
- Example:
+ Example::
+
soc_pm_init()
{
/* Do things */
@@ -117,4 +112,5 @@ dev_pm_opp_init_cpufreq_table -
NOTE: This function is available only if CONFIG_CPU_FREQ is enabled in
addition to CONFIG_PM_OPP.
-dev_pm_opp_free_cpufreq_table - Free up the table allocated by dev_pm_opp_init_cpufreq_table
+dev_pm_opp_free_cpufreq_table
+ Free up the table allocated by dev_pm_opp_init_cpufreq_table
diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.rst
similarity index 57%
rename from Documentation/cpu-freq/cpu-drivers.txt
rename to Documentation/cpu-freq/cpu-drivers.rst
index 6e353d00cdc6..9cc2559bc34b 100644
--- a/Documentation/cpu-freq/cpu-drivers.txt
+++ b/Documentation/cpu-freq/cpu-drivers.rst
@@ -1,35 +1,25 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
-
-
- L i n u x C P U F r e q
-
- C P U D r i v e r s
-
- - information for developers -
-
-
- Dominik Brodowski <[email protected]>
- Rafael J. Wysocki <[email protected]>
- Viresh Kumar <[email protected]>
-
-
-
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
-
-
-Contents:
----------
-1. What To Do?
-1.1 Initialization
-1.2 Per-CPU Initialization
-1.3 verify
-1.4 target/target_index or setpolicy?
-1.5 target/target_index
-1.6 setpolicy
-1.7 get_intermediate and target_intermediate
-2. Frequency Table Helpers
+===============================================
+How to implement a new cpufreq processor driver
+===============================================
+
+.. information for developers
+
+Authors:
+ - Dominik Brodowski <[email protected]>
+ - Rafael J. Wysocki <[email protected]>
+ - Viresh Kumar <[email protected]>
+
+.. Contents:
+
+ 1. What To Do?
+ 1.1 Initialization
+ 1.2 Per-CPU Initialization
+ 1.3 verify
+ 1.4 target/target_index or setpolicy?
+ 1.5 target/target_index
+ 1.6 setpolicy
+ 1.7 get_intermediate and target_intermediate
+ 2. Frequency Table Helpers
@@ -46,59 +36,73 @@ on what is necessary:
First of all, in an __initcall level 7 (module_init()) or later
function check whether this kernel runs on the right CPU and the right
-chipset. If so, register a struct cpufreq_driver with the CPUfreq core
-using cpufreq_register_driver()
+chipset. If so, register a `struct cpufreq_driver` with the CPUfreq core
+using `cpufreq_register_driver()`
-What shall this struct cpufreq_driver contain?
+What shall this `struct cpufreq_driver` contain?
- .name - The name of this driver.
+.name
+ The name of this driver.
- .init - A pointer to the per-policy initialization function.
+.init
+ A pointer to the per-policy initialization function.
- .verify - A pointer to a "verification" function.
+.verify
+ A pointer to a "verification" function.
- .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See
- below on the differences.
+.setpolicy **or** .fast_switch **or** .target **or** .target_index
+ See below on the differences.
And optionally
- .flags - Hints for the cpufreq core.
+.flags
+ Hints for the cpufreq core.
- .driver_data - cpufreq driver specific data.
+.driver_data
+ cpufreq driver specific data.
- .resolve_freq - Returns the most appropriate frequency for a target
- frequency. Doesn't change the frequency though.
+.resolve_freq
+ Returns the most appropriate frequency for a target
+ frequency. Doesn't change the frequency though.
- .get_intermediate and target_intermediate - Used to switch to stable
- frequency while changing CPU frequency.
+.get_intermediate and target_intermediate
+ Used to switch to stable frequency while changing CPU frequency.
- .get - Returns current frequency of the CPU.
+.get
+ Returns current frequency of the CPU.
- .bios_limit - Returns HW/BIOS max frequency limitations for the CPU.
+.bios_limit
+ Returns HW/BIOS max frequency limitations for the CPU.
- .exit - A pointer to a per-policy cleanup function called during
- CPU_POST_DEAD phase of cpu hotplug process.
+.exit
+ A pointer to a per-policy cleanup function called during
+ CPU_POST_DEAD phase of cpu hotplug process.
- .stop_cpu - A pointer to a per-policy stop function called during
- CPU_DOWN_PREPARE phase of cpu hotplug process.
+.stop_cpu
+ A pointer to a per-policy stop function called during
+ CPU_DOWN_PREPARE phase of cpu hotplug process.
- .suspend - A pointer to a per-policy suspend function which is called
- with interrupts disabled and _after_ the governor is stopped for the
- policy.
+.suspend
+ A pointer to a per-policy suspend function which is called with
+ interrupts disabled and **after** the governor is stopped for the policy.
- .resume - A pointer to a per-policy resume function which is called
- with interrupts disabled and _before_ the governor is started again.
+.resume
+ A pointer to a per-policy resume function which is called
+ with interrupts disabled and **before** the governor is started again.
- .ready - A pointer to a per-policy ready function which is called after
- the policy is fully initialized.
+.ready
+ A pointer to a per-policy ready function which is called after
+ the policy is fully initialized.
- .attr - A pointer to a NULL-terminated list of "struct freq_attr" which
- allow to export values to sysfs.
+.attr
+ A pointer to a NULL-terminated list of `struct freq_attr` which
+ allow to export values to sysfs.
- .boost_enabled - If set, boost frequencies are enabled.
+.boost_enabled
+ If set, boost frequencies are enabled.
- .set_boost - A pointer to a per-policy function to enable/disable boost
- frequencies.
+.set_boost
+ A pointer to a per-policy function to enable/disable boost frequencies.
1.2 Per-CPU Initialization
@@ -108,37 +112,42 @@ Whenever a new CPU is registered with the device model, or after the
cpufreq driver registers itself, the per-policy initialization function
cpufreq_driver.init is called if no cpufreq policy existed for the CPU.
Note that the .init() and .exit() routines are called only once for the
-policy and not for each CPU managed by the policy. It takes a struct
-cpufreq_policy *policy as argument. What to do now?
+policy and not for each CPU managed by the policy. It takes a `struct
+cpufreq_policy *policy` as argument. What to do now?
If necessary, activate the CPUfreq support on your CPU.
Then, the driver must fill in the following values:
-policy->cpuinfo.min_freq _and_
-policy->cpuinfo.max_freq - the minimum and maximum frequency
- (in kHz) which is supported by
- this CPU
-policy->cpuinfo.transition_latency the time it takes on this CPU to
- switch between two frequencies in
- nanoseconds (if appropriate, else
- specify CPUFREQ_ETERNAL)
-
-policy->cur The current operating frequency of
- this CPU (if appropriate)
-policy->min,
-policy->max,
-policy->policy and, if necessary,
-policy->governor must contain the "default policy" for
- this CPU. A few moments later,
- cpufreq_driver.verify and either
- cpufreq_driver.setpolicy or
- cpufreq_driver.target/target_index is called
- with these values.
-policy->cpus Update this with the masks of the
- (online + offline) CPUs that do DVFS
- along with this CPU (i.e. that share
- clock/voltage rails with it).
++---------------------------------------+--------------------------------------+
+| policy->cpuinfo.min_freq **and** | |
+| policy->cpuinfo.max_freq | the minimum and maximum frequency |
+| | (in kHz) which is supported by |
+| | this CPU |
++---------------------------------------+--------------------------------------+
+| policy->cpuinfo.transition_latency | the time it takes on this CPU to |
+| | switch between two frequencies in |
+| | nanoseconds (if appropriate, else |
+| | specify CPUFREQ_ETERNAL) |
++---------------------------------------+--------------------------------------+
+| policy->cur | The current operating frequency of |
+| | this CPU (if appropriate) |
++---------------------------------------+--------------------------------------+
+| policy->min, | |
+| policy->max, | |
+| policy->policy and, if necessary, | |
+| policy->governor | must contain the "default policy" |
+| | for this CPU. A few moments later, |
+| | cpufreq_driver.verify and either |
+| | cpufreq_driver.setpolicy or |
+| | cpufreq_driver.target/target_index |
+| | is called with these values. |
++---------------------------------------+--------------------------------------+
+| policy->cpus | Update this with the masks of the |
+| | (online + offline) CPUs that do DVFS |
+| | along with this CPU (i.e. that share |
+| | clock/voltage rails with it). |
++---------------------------------------+--------------------------------------+
For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the
frequency table helpers might be helpful. See the section 2 for more information
@@ -151,8 +160,8 @@ on them.
When the user decides a new policy (consisting of
"policy,governor,min,max") shall be set, this policy must be validated
so that incompatible values can be corrected. For verifying these
-values cpufreq_verify_within_limits(struct cpufreq_policy *policy,
-unsigned int min_freq, unsigned int max_freq) function might be helpful.
+values `cpufreq_verify_within_limits(struct cpufreq_policy *policy,
+unsigned int min_freq, unsigned int max_freq)` function might be helpful.
See section 2 for details on frequency table helpers.
You need to make sure that at least one valid frequency (or operating
@@ -163,7 +172,7 @@ policy->max first, and only if this is no solution, decrease policy->min.
1.4 target or target_index or setpolicy or fast_switch?
-------------------------------------------------------
-Most cpufreq drivers or even most cpu frequency scaling algorithms
+Most cpufreq drivers or even most cpu frequency scaling algorithms
only allow the CPU frequency to be set to predefined fixed values. For
these, you use the ->target(), ->target_index() or ->fast_switch()
callbacks.
@@ -175,8 +184,8 @@ limits on their own. These shall use the ->setpolicy() callback.
1.5. target/target_index
------------------------
-The target_index call has two arguments: struct cpufreq_policy *policy,
-and unsigned int index (into the exposed frequency table).
+The target_index call has two arguments: `struct cpufreq_policy *policy`,
+and `unsigned int index` (into the exposed frequency table).
The CPUfreq driver must set the new frequency when called here. The
actual frequency must be determined by freq_table[index].frequency.
@@ -184,10 +193,10 @@ actual frequency must be determined by freq_table[index].frequency.
It should always restore to earlier frequency (i.e. policy->restore_freq) in
case of errors, even if we switched to intermediate frequency earlier.
-Deprecated:
+Deprecated
----------
-The target call has three arguments: struct cpufreq_policy *policy,
-unsigned int target_frequency, unsigned int relation.
+The target call has three arguments: `struct cpufreq_policy *policy`,
+`unsigned int target_frequency`, `unsigned int relation`.
The CPUfreq driver must set the new frequency when called here. The
actual frequency must be determined using the following rules:
@@ -210,14 +219,14 @@ Not all drivers are expected to implement it, as sleeping from within
this callback isn't allowed. This callback must be highly optimized to
do switching as fast as possible.
-This function has two arguments: struct cpufreq_policy *policy and
-unsigned int target_frequency.
+This function has two arguments: `struct cpufreq_policy *policy` and
+`unsigned int target_frequency`.
1.7 setpolicy
-------------
-The setpolicy call only takes a struct cpufreq_policy *policy as
+The setpolicy call only takes a `struct cpufreq_policy *policy` as
argument. You need to set the lower limit of the in-processor or
in-chipset dynamic frequency switching to policy->min, the upper limit
to policy->max, and -if supported- select a performance-oriented
@@ -278,10 +287,10 @@ table.
cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,
excluding CPUFREQ_ENTRY_INVALID frequencies.
-Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and
-"table" - the cpufreq_frequency_table * you want to iterate over.
+Use arguments "pos" - a `cpufreq_frequency_table *` as a loop cursor and
+"table" - the `cpufreq_frequency_table *` you want to iterate over.
-For example:
+For example::
struct cpufreq_frequency_table *pos, *driver_freq_table;
diff --git a/Documentation/cpu-freq/cpufreq-nforce2.txt b/Documentation/cpu-freq/cpufreq-nforce2.rst
similarity index 65%
rename from Documentation/cpu-freq/cpufreq-nforce2.txt
rename to Documentation/cpu-freq/cpufreq-nforce2.rst
index babce1315026..d40700bd5083 100644
--- a/Documentation/cpu-freq/cpufreq-nforce2.txt
+++ b/Documentation/cpu-freq/cpufreq-nforce2.rst
@@ -1,3 +1,6 @@
+=================================
+nVidia nForce2 platform specifics
+=================================
The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms.
@@ -6,14 +9,15 @@ can be controlled independently from the PCI/AGP clock.
The module has two options:
+ ======== ======================================
fid: multiplier * 10 (for example 8.5 = 85)
min_fsb: minimum FSB
+ ======== ======================================
If not set, fid is calculated from the current CPU speed and the FSB.
min_fsb defaults to FSB at boot time - 50 MHz.
-IMPORTANT: The available range is limited downwards!
- Also the minimum available FSB can differ, for systems
+IMPORTANT:
+ The available range is limited downwards!
+ Also the minimum available FSB can differ, for systems
booting with 200 MHz, 150 should always work.
-
-
diff --git a/Documentation/cpu-freq/cpufreq-stats.txt b/Documentation/cpu-freq/cpufreq-stats.rst
similarity index 31%
rename from Documentation/cpu-freq/cpufreq-stats.txt
rename to Documentation/cpu-freq/cpufreq-stats.rst
index 14378cecb172..3e33712b496e 100644
--- a/Documentation/cpu-freq/cpufreq-stats.txt
+++ b/Documentation/cpu-freq/cpufreq-stats.rst
@@ -1,21 +1,20 @@
+==========================================
+General description of sysfs cpufreq stats
+==========================================
- CPU frequency and voltage scaling statistics in the Linux(TM) kernel
+.. information for users
- L i n u x c p u f r e q - s t a t s d r i v e r
+Author: Venkatesh Pallipadi <[email protected]>
- - information for users -
-
-
- Venkatesh Pallipadi <[email protected]>
-
-Contents
-1. Introduction
-2. Statistics Provided (with example)
-3. Configuring cpufreq-stats
+.. Contents
+ 1. Introduction
+ 2. Statistics Provided (with example)
+ 3. Configuring cpufreq-stats
1. Introduction
+===============
cpufreq-stats is a driver that provides CPU frequency statistics for each CPU.
These statistics are provided in /sysfs as a bunch of read_only interfaces. This
@@ -28,6 +27,7 @@ that may be running on your CPU. So, it will work with any cpufreq_driver.
2. Statistics Provided (with example)
+=====================================
cpufreq stats provides following statistics (explained in detail below).
- time_in_state
@@ -39,78 +39,79 @@ All the statistics will be from the time the stats driver has been inserted
statistic is done. Obviously, stats driver will not have any information
about the frequency transitions before the stats driver insertion.
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l
-total 0
-drwxr-xr-x 2 root root 0 May 14 16:06 .
-drwxr-xr-x 3 root root 0 May 14 15:58 ..
---w------- 1 root root 4096 May 14 16:06 reset
--r--r--r-- 1 root root 4096 May 14 16:06 time_in_state
--r--r--r-- 1 root root 4096 May 14 16:06 total_trans
--r--r--r-- 1 root root 4096 May 14 16:06 trans_table
---------------------------------------------------------------------------------
+::
-- reset
-Write-only attribute that can be used to reset the stat counters. This can be
-useful for evaluating system behaviour under different governors without the
-need for a reboot.
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l
+ total 0
+ drwxr-xr-x 2 root root 0 May 14 16:06 .
+ drwxr-xr-x 3 root root 0 May 14 15:58 ..
+ --w------- 1 root root 4096 May 14 16:06 reset
+ -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state
+ -r--r--r-- 1 root root 4096 May 14 16:06 total_trans
+ -r--r--r-- 1 root root 4096 May 14 16:06 trans_table
-- time_in_state
-This gives the amount of time spent in each of the frequencies supported by
-this CPU. The cat output will have "<frequency> <time>" pair in each line, which
-will mean this CPU spent <time> usertime units of time at <frequency>. Output
-will have one line for each of the supported frequencies. usertime units here
-is 10mS (similar to other time exported in /proc).
+reset
+ Write-only attribute that can be used to reset the stat counters. This can be
+ useful for evaluating system behaviour under different governors without the
+ need for a reboot.
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state
-3600000 2089
-3400000 136
-3200000 34
-3000000 67
-2800000 172488
---------------------------------------------------------------------------------
+time_in_state
+ This gives the amount of time spent in each of the frequencies supported by
+ this CPU. The cat output will have "<frequency> <time>" pair in each line,
+ which will mean this CPU spent <time> usertime units of time at <frequency>.
+ Output will have one line for each of the supported frequencies. usertime
+ units here is 10mS (similar to other time exported in /proc).
+::
-- total_trans
-This gives the total number of frequency transitions on this CPU. The cat
-output will have a single count which is the total number of frequency
-transitions.
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state
+ 3600000 2089
+ 3400000 136
+ 3200000 34
+ 3000000 67
+ 2800000 172488
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
-20
---------------------------------------------------------------------------------
-- trans_table
-This will give a fine grained information about all the CPU frequency
-transitions. The cat output here is a two dimensional matrix, where an entry
-<i,j> (row i, column j) represents the count of number of transitions from
-Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
-which the driver has provided the frequency table initially to the cpufreq core
-and so can be sorted (ascending or descending) or unsorted. The output here
-also contains the actual freq values for each row and column for better
-readability.
+total_trans
+ This gives the total number of frequency transitions on this CPU. The cat
+ output will have a single count which is the total number of frequency
+ transitions.
-If the transition table is bigger than PAGE_SIZE, reading this will
-return an -EFBIG error.
+::
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table
- From : To
- : 3600000 3400000 3200000 3000000 2800000
- 3600000: 0 5 0 0 0
- 3400000: 4 0 2 0 0
- 3200000: 0 1 0 2 0
- 3000000: 0 0 1 0 3
- 2800000: 0 0 0 2 0
---------------------------------------------------------------------------------
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
+ 20
+trans_table
+ This will give a fine grained information about all the CPU frequency
+ transitions. The cat output here is a two dimensional matrix, where an entry
+ <i,j> (row i, column j) represents the count of number of transitions from
+ Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
+ which the driver has provided the frequency table initially to the cpufreq
+ core and so can be sorted (ascending or descending) or unsorted. The output
+ here also contains the actual freq values for each row and column for better
+ readability.
+
+ If the transition table is bigger than PAGE_SIZE, reading this will
+ return an -EFBIG error.
+
+::
+
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table
+ From : To
+ : 3600000 3400000 3200000 3000000 2800000
+ 3600000: 0 5 0 0 0
+ 3400000: 4 0 2 0 0
+ 3200000: 0 1 0 2 0
+ 3000000: 0 0 1 0 3
+ 2800000: 0 0 0 2 0
3. Configuring cpufreq-stats
+============================
-To configure cpufreq-stats in your kernel
-Config Main Menu
+To configure cpufreq-stats in your kernel::
+
+ Config Main Menu
Power management options (ACPI, APM) --->
CPU Frequency scaling --->
[*] CPU Frequency scaling
diff --git a/Documentation/cpu-freq/index.txt b/Documentation/cpu-freq/index.rst
similarity index 37%
rename from Documentation/cpu-freq/index.txt
rename to Documentation/cpu-freq/index.rst
index c15e75386a05..10e6c05f60f6 100644
--- a/Documentation/cpu-freq/index.txt
+++ b/Documentation/cpu-freq/index.rst
@@ -1,39 +1,35 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
+:orphan:
+==============================================================
+CPU frequency and voltage scaling code in the Linux(TM) kernel
+==============================================================
- L i n u x C P U F r e q
+Author: Dominik Brodowski <[email protected]>
+Clock scaling allows you to change the clock speed of the CPUs on the
+fly. This is a nice method to save battery power, because the lower
+the clock speed, the less power the CPU consumes.
- Dominik Brodowski <[email protected]>
+.. toctree::
+ :maxdepth: 1
+ core
+ cpufreq-stats
+ cpu-drivers
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
+ amd-powernow
+ cpufreq-nforce2
+ pcc-cpufreq
+.. only:: subproject and html
+ Indices
+ =======
-Documents in this directory:
-----------------------------
-
-amd-powernow.txt - AMD powernow driver specific file.
-
-core.txt - General description of the CPUFreq core and
- of CPUFreq notifiers.
-
-cpu-drivers.txt - How to implement a new cpufreq processor driver.
-
-cpufreq-nforce2.txt - nVidia nForce2 platform specific file.
-
-cpufreq-stats.txt - General description of sysfs cpufreq stats.
-
-index.txt - File index, Mailing list and Links (this document)
-
-pcc-cpufreq.txt - PCC cpufreq driver specific file.
-
+ * :ref:`genindex`
Mailing List
------------
diff --git a/Documentation/cpu-freq/pcc-cpufreq.txt b/Documentation/cpu-freq/pcc-cpufreq.rst
similarity index 80%
rename from Documentation/cpu-freq/pcc-cpufreq.txt
rename to Documentation/cpu-freq/pcc-cpufreq.rst
index 9e3c3b33514c..d846a36536e4 100644
--- a/Documentation/cpu-freq/pcc-cpufreq.txt
+++ b/Documentation/cpu-freq/pcc-cpufreq.rst
@@ -1,45 +1,38 @@
-/*
- * pcc-cpufreq.txt - PCC interface documentation
- *
- * Copyright (C) 2009 Red Hat, Matthew Garrett <[email protected]>
- * Copyright (C) 2009 Hewlett-Packard Development Company, L.P.
- * Nagananda Chumbalkar <[email protected]>
- *
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *
- * 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
- * the Free Software Foundation; version 2 of the License.
- *
- * 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, GOOD TITLE or NON
- * INFRINGEMENT. See the GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- */
-
-
- Processor Clocking Control Driver
- ---------------------------------
-
-Contents:
----------
-1. Introduction
-1.1 PCC interface
-1.1.1 Get Average Frequency
-1.1.2 Set Desired Frequency
-1.2 Platforms affected
-2. Driver and /sys details
-2.1 scaling_available_frequencies
-2.2 cpuinfo_transition_latency
-2.3 cpuinfo_cur_freq
-2.4 related_cpus
-3. Caveats
+==========================================================
+Processor Clocking Control Driver cpufreq driver specifics
+==========================================================
+
+
+.. pcc-cpufreq.txt - PCC interface documentation
+
+ Copyright (C) 2009 Red Hat, Matthew Garrett <[email protected]>
+ Copyright (C) 2009 Hewlett-Packard Development Company, L.P.
+ Nagananda Chumbalkar <[email protected]>
+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ 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
+ the Free Software Foundation; version 2 of the License.
+
+ 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, GOOD TITLE or NON
+ INFRINGEMENT. See the GNU General Public License for more details.
+
+
+.. Contents:
+ 1. Introduction
+ 1.1 PCC interface
+ 1.1.1 Get Average Frequency
+ 1.1.2 Set Desired Frequency
+ 1.2 Platforms affected
+ 2. Driver and /sys details
+ 2.1 scaling_available_frequencies
+ 2.2 cpuinfo_transition_latency
+ 2.3 cpuinfo_cur_freq
+ 2.4 related_cpus
+ 3. Caveats
1. Introduction:
----------------
@@ -72,6 +65,7 @@ memory region. The shared memory region header contains the "command" and
doorbell.
The following commands are supported by the PCC interface:
+
* Get Average Frequency
* Set Desired Frequency
@@ -140,7 +134,9 @@ Internally, there is no need for the driver to convert the "target" frequency
to a corresponding P-state.
The VERSION number for the driver will be of the format v.xy.ab.
-eg: 1.00.02
+eg::
+
+ 1.00.02
----- --
| |
| -- this will increase with bug fixes/enhancements to the driver
@@ -168,21 +164,21 @@ A) Often cpuinfo_cur_freq will show a value different than what is declared
in the scaling_available_frequencies or scaling_cur_freq, or scaling_max_freq.
This is due to "turbo boost" available on recent Intel processors. If certain
conditions are met the BIOS can achieve a slightly higher speed than requested
-by OSPM. An example:
+by OSPM. An example::
-scaling_cur_freq : 2933000
-cpuinfo_cur_freq : 3196000
+ scaling_cur_freq : 2933000
+ cpuinfo_cur_freq : 3196000
B) There is a round-off error associated with the cpuinfo_cur_freq value.
Since the driver obtains the current frequency as a "percentage" (%) of the
nominal frequency from the BIOS, sometimes, the values displayed by
-scaling_cur_freq and cpuinfo_cur_freq may not match. An example:
+scaling_cur_freq and cpuinfo_cur_freq may not match. An example::
-scaling_cur_freq : 1600000
-cpuinfo_cur_freq : 1583000
+ scaling_cur_freq : 1600000
+ cpuinfo_cur_freq : 1583000
In this example, the nominal frequency is 2933 MHz. The driver obtains the
-current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency:
+current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency::
54% of 2933 MHz = 1583 MHz
@@ -191,10 +187,10 @@ corresponds to the frequency of the P0 P-state.
2.4 related_cpus:
-----------------
-The related_cpus field is identical to affected_cpus.
+The related_cpus field is identical to affected_cpus:
-affected_cpus : 4
-related_cpus : 4
+ affected_cpus : 4
+ related_cpus : 4
Currently, the PCC driver does not evaluate _PSD. The platforms that support
PCC do not implement SW_ALL. So OSPM doesn't need to perform any coordination
diff --git a/drivers/cpufreq/Kconfig.x86 b/drivers/cpufreq/Kconfig.x86
index dfa6457deaf6..336a295fac4c 100644
--- a/drivers/cpufreq/Kconfig.x86
+++ b/drivers/cpufreq/Kconfig.x86
@@ -25,7 +25,7 @@ config X86_PCC_CPUFREQ
This driver adds support for the PCC interface.
For details, take a look at:
- <file:Documentation/cpu-freq/pcc-cpufreq.txt>.
+ <file:Documentation/cpu-freq/pcc-cpufreq.rst>.
To compile this driver as a module, choose M here: the
module will be called pcc-cpufreq.
--
2.21.0
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 <[email protected]>
---
...ault-injection.txt => fault-injection.rst} | 265 +++++++++---------
Documentation/fault-injection/index.rst | 20 ++
...r-inject.txt => notifier-error-inject.rst} | 18 +-
...injection.txt => nvme-fault-injection.rst} | 174 ++++++------
...rovoke-crashes.txt => provoke-crashes.rst} | 40 ++-
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 +-
12 files changed, 290 insertions(+), 241 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%)
rename Documentation/fault-injection/{nvme-fault-injection.txt => nvme-fault-injection.rst} (19%)
rename Documentation/fault-injection/{provoke-crashes.txt => provoke-crashes.rst} (45%)
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.txt b/Documentation/fault-injection/nvme-fault-injection.rst
similarity index 19%
rename from Documentation/fault-injection/nvme-fault-injection.txt
rename to Documentation/fault-injection/nvme-fault-injection.rst
index 8fbf3bf60b62..bbb1bf3e8650 100644
--- a/Documentation/fault-injection/nvme-fault-injection.txt
+++ b/Documentation/fault-injection/nvme-fault-injection.rst
@@ -16,101 +16,105 @@ 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:
+ 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
-cp: cannot stat ‘/mnt/a.file’: Input/output error
+Expected Result::
-Message from dmesg:
+ cp: cannot stat ‘/mnt/a.file’: Input/output error
-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
+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
+ 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
-Expected Result:
+ cp a.file /mnt
-command success without error
+Expected Result::
-Message from dmesg:
+ command success without error
-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
+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.txt b/Documentation/fault-injection/provoke-crashes.rst
similarity index 45%
rename from Documentation/fault-injection/provoke-crashes.txt
rename to Documentation/fault-injection/provoke-crashes.rst
index 7a9d3d81525b..9279a3e12278 100644
--- a/Documentation/fault-injection/provoke-crashes.txt
+++ b/Documentation/fault-injection/provoke-crashes.rst
@@ -1,3 +1,7 @@
+===============
+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
@@ -8,31 +12,37 @@ 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}]
+Usage::
- recur_count : Recursion level for the stack overflow test. Default is 10.
+ insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
+ [cpoint_count={>0}]
- 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
+recur_count
+ Recursion level for the stack overflow test. Default is 10.
- 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_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_count : Indicates the number of times the crash point is to be hit
- to trigger an action. The default is 10.
+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.,
+<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
+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 <[email protected]>
*
- * 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
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 <[email protected]>
---
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
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 <[email protected]>
---
.../{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
This is the only LaTeX documentation file inside the documentation.
Instead of having a Latex document directly there, convert
it to ReST format, as this is the format we're using for docs.
For now, let's keep the extension as .txt in order to avoid
warnings when building the documentation with Sphinx.
The next patch patch will rename it to .rst and add it to the
building system.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/cdrom/Makefile | 21 -
...{cdrom-standard.tex => cdrom-standard.txt} | 1491 +++++++++--------
drivers/cdrom/cdrom.c | 2 +-
3 files changed, 765 insertions(+), 749 deletions(-)
delete mode 100644 Documentation/cdrom/Makefile
rename Documentation/cdrom/{cdrom-standard.tex => cdrom-standard.txt} (26%)
diff --git a/Documentation/cdrom/Makefile b/Documentation/cdrom/Makefile
deleted file mode 100644
index a19e321928e1..000000000000
--- a/Documentation/cdrom/Makefile
+++ /dev/null
@@ -1,21 +0,0 @@
-LATEXFILE = cdrom-standard
-
-all:
- make clean
- latex $(LATEXFILE)
- latex $(LATEXFILE)
- @if [ -x `which gv` ]; then \
- `dvips -q -t letter -o $(LATEXFILE).ps $(LATEXFILE).dvi` ;\
- `gv -antialias -media letter -nocenter $(LATEXFILE).ps` ;\
- else \
- `xdvi $(LATEXFILE).dvi &` ;\
- fi
- make sortofclean
-
-clean:
- rm -f $(LATEXFILE).ps $(LATEXFILE).dvi $(LATEXFILE).aux $(LATEXFILE).log
-
-sortofclean:
- rm -f $(LATEXFILE).aux $(LATEXFILE).log
-
-
diff --git a/Documentation/cdrom/cdrom-standard.tex b/Documentation/cdrom/cdrom-standard.txt
similarity index 26%
rename from Documentation/cdrom/cdrom-standard.tex
rename to Documentation/cdrom/cdrom-standard.txt
index f7cd455973f7..dde4f7f7fdbf 100644
--- a/Documentation/cdrom/cdrom-standard.tex
+++ b/Documentation/cdrom/cdrom-standard.txt
@@ -1,488 +1,480 @@
-\documentclass{article}
-\def\version{$Id: cdrom-standard.tex,v 1.9 1997/12/28 15:42:49 david Exp $}
-\newcommand{\newsection}[1]{\newpage\section{#1}}
+=======================
+A Linux CD-ROM standard
+=======================
-\evensidemargin=0pt
-\oddsidemargin=0pt
-\topmargin=-\headheight \advance\topmargin by -\headsep
-\textwidth=15.99cm \textheight=24.62cm % normal A4, 1'' margin
+:Author: David van Leeuwen <[email protected]>
+:Date: 12 March 1999
+:Updated by: Erik Andersen ([email protected])
+:Updated by: Jens Axboe ([email protected])
-\def\linux{{\sc Linux}}
-\def\cdrom{{\sc cd-rom}}
-\def\UCD{{\sc Uniform cd-rom Driver}}
-\def\cdromc{{\tt {cdrom.c}}}
-\def\cdromh{{\tt {cdrom.h}}}
-\def\fo{\sl} % foreign words
-\def\ie{{\fo i.e.}}
-\def\eg{{\fo e.g.}}
-\everymath{\it} \everydisplay{\it}
-\catcode `\_=\active \def_{\_\penalty100 }
-\catcode`\<=\active \def<#1>{{\langle\hbox{\rm#1}\rangle}}
+Introduction
+============
-\begin{document}
-\title{A \linux\ \cdrom\ standard}
-\author{David van Leeuwen\\{\normalsize\tt [email protected]}
-\\{\footnotesize updated by Erik Andersen {\tt([email protected])}}
-\\{\footnotesize updated by Jens Axboe {\tt([email protected])}}}
-\date{12 March 1999}
-
-\maketitle
-
-\newsection{Introduction}
-
-\linux\ is probably the Unix-like operating system that supports
+Linux is probably the Unix-like operating system that supports
the widest variety of hardware devices. The reasons for this are
-presumably
-\begin{itemize}
-\item
- The large list of hardware devices available for the many platforms
- that \linux\ now supports (\ie, i386-PCs, Sparc Suns, etc.)
-\item
- The open design of the operating system, such that anybody can write a
- driver for \linux.
-\item
- There is plenty of source code around as examples of how to write a driver.
-\end{itemize}
-The openness of \linux, and the many different types of available
-hardware has allowed \linux\ to support many different hardware devices.
-Unfortunately, the very openness that has allowed \linux\ to support
+presumably
+
+- The large list of hardware devices available for the many platforms
+ that Linux now supports (i.e., i386-PCs, Sparc Suns, etc.)
+- The open design of the operating system, such that anybody can write a
+ driver for Linux.
+- There is plenty of source code around as examples of how to write a driver.
+
+The openness of Linux, and the many different types of available
+hardware has allowed Linux to support many different hardware devices.
+Unfortunately, the very openness that has allowed Linux to support
all these different devices has also allowed the behavior of each
device driver to differ significantly from one device to another.
-This divergence of behavior has been very significant for \cdrom\
-devices; the way a particular drive reacts to a `standard' $ioctl()$
+This divergence of behavior has been very significant for CD-ROM
+devices; the way a particular drive reacts to a `standard` *ioctl()*
call varies greatly from one device driver to another. To avoid making
-their drivers totally inconsistent, the writers of \linux\ \cdrom\
+their drivers totally inconsistent, the writers of Linux CD-ROM
drivers generally created new device drivers by understanding, copying,
and then changing an existing one. Unfortunately, this practice did not
-maintain uniform behavior across all the \linux\ \cdrom\ drivers.
+maintain uniform behavior across all the Linux CD-ROM drivers.
This document describes an effort to establish Uniform behavior across
-all the different \cdrom\ device drivers for \linux. This document also
-defines the various $ioctl$s, and how the low-level \cdrom\ device
-drivers should implement them. Currently (as of the \linux\ 2.1.$x$
-development kernels) several low-level \cdrom\ device drivers, including
+all the different CD-ROM device drivers for Linux. This document also
+defines the various *ioctl()'s*, and how the low-level CD-ROM device
+drivers should implement them. Currently (as of the Linux 2.1.\ *x*
+development kernels) several low-level CD-ROM device drivers, including
both IDE/ATAPI and SCSI, now use this Uniform interface.
-When the \cdrom\ was developed, the interface between the \cdrom\ drive
+When the CD-ROM was developed, the interface between the CD-ROM drive
and the computer was not specified in the standards. As a result, many
-different \cdrom\ interfaces were developed. Some of them had their
+different CD-ROM interfaces were developed. Some of them had their
own proprietary design (Sony, Mitsumi, Panasonic, Philips), other
manufacturers adopted an existing electrical interface and changed
the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply
adapted their drives to one or more of the already existing electrical
interfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage and
-most of the `NoName' manufacturers). In cases where a new drive really
+most of the `NoName` manufacturers). In cases where a new drive really
brought its own interface or used its own command set and flow control
scheme, either a separate driver had to be written, or an existing
-driver had to be enhanced. History has delivered us \cdrom\ support for
-many of these different interfaces. Nowadays, almost all new \cdrom\
+driver had to be enhanced. History has delivered us CD-ROM support for
+many of these different interfaces. Nowadays, almost all new CD-ROM
drives are either IDE/ATAPI or SCSI, and it is very unlikely that any
manufacturer will create a new interface. Even finding drives for the
old proprietary interfaces is getting difficult.
When (in the 1.3.70's) I looked at the existing software interface,
-which was expressed through \cdromh, it appeared to be a rather wild
-set of commands and data formats.\footnote{I cannot recollect what
-kernel version I looked at, then, presumably 1.2.13 and 1.3.34---the
-latest kernel that I was indirectly involved in.} It seemed that many
+which was expressed through `cdrom.h`, it appeared to be a rather wild
+set of commands and data formats [#f1]_. It seemed that many
features of the software interface had been added to accommodate the
-capabilities of a particular drive, in an {\fo ad hoc\/} manner. More
-importantly, it appeared that the behavior of the `standard' commands
-was different for most of the different drivers: \eg, some drivers
-close the tray if an $open()$ call occurs when the tray is open, while
+capabilities of a particular drive, in an *ad hoc* manner. More
+importantly, it appeared that the behavior of the `standard` commands
+was different for most of the different drivers: e. g., some drivers
+close the tray if an *open()* call occurs when the tray is open, while
others do not. Some drivers lock the door upon opening the device, to
prevent an incoherent file system, but others don't, to allow software
ejection. Undoubtedly, the capabilities of the different drives vary,
but even when two drives have the same capability their drivers'
behavior was usually different.
-I decided to start a discussion on how to make all the \linux\ \cdrom\
+.. [#f1]
+ I cannot recollect what kernel version I looked at, then,
+ presumably 1.2.13 and 1.3.34 --- the latest kernel that I was
+ indirectly involved in.
+
+I decided to start a discussion on how to make all the Linux CD-ROM
drivers behave more uniformly. I began by contacting the developers of
-the many \cdrom\ drivers found in the \linux\ kernel. Their reactions
-encouraged me to write the \UCD\ which this document is intended to
-describe. The implementation of the \UCD\ is in the file \cdromc. This
-driver is intended to be an additional software layer that sits on top
-of the low-level device drivers for each \cdrom\ drive. By adding this
-additional layer, it is possible to have all the different \cdrom\
-devices behave {\em exactly\/} the same (insofar as the underlying
+the many CD-ROM drivers found in the Linux kernel. Their reactions
+encouraged me to write the Uniform CD-ROM Driver which this document is
+intended to describe. The implementation of the Uniform CD-ROM Driver is
+in the file `cdrom.c`. This driver is intended to be an additional software
+layer that sits on top of the low-level device drivers for each CD-ROM drive.
+By adding this additional layer, it is possible to have all the different
+CD-ROM devices behave **exactly** the same (insofar as the underlying
hardware will allow).
-The goal of the \UCD\ is {\em not\/} to alienate driver developers who
-have not yet taken steps to support this effort. The goal of \UCD\ is
-simply to give people writing application programs for \cdrom\ drives
-{\em one\/} \linux\ \cdrom\ interface with consistent behavior for all
-\cdrom\ devices. In addition, this also provides a consistent interface
-between the low-level device driver code and the \linux\ kernel. Care
-is taken that 100\,\% compatibility exists with the data structures and
-programmer's interface defined in \cdromh. This guide was written to
-help \cdrom\ driver developers adapt their code to use the \UCD\ code
-defined in \cdromc.
+The goal of the Uniform CD-ROM Driver is **not** to alienate driver developers
+whohave not yet taken steps to support this effort. The goal of Uniform CD-ROM
+Driver is simply to give people writing application programs for CD-ROM drives
+**one** Linux CD-ROM interface with consistent behavior for all
+CD-ROM devices. In addition, this also provides a consistent interface
+between the low-level device driver code and the Linux kernel. Care
+is taken that 100% compatibility exists with the data structures and
+programmer's interface defined in `cdrom.h`. This guide was written to
+help CD-ROM driver developers adapt their code to use the Uniform CD-ROM
+Driver code defined in `cdrom.c`.
Personally, I think that the most important hardware interfaces are
the IDE/ATAPI drives and, of course, the SCSI drives, but as prices
of hardware drop continuously, it is also likely that people may have
-more than one \cdrom\ drive, possibly of mixed types. It is important
+more than one CD-ROM drive, possibly of mixed types. It is important
that these drives behave in the same way. In December 1994, one of the
-cheapest \cdrom\ drives was a Philips cm206, a double-speed proprietary
-drive. In the months that I was busy writing a \linux\ driver for it,
+cheapest CD-ROM drives was a Philips cm206, a double-speed proprietary
+drive. In the months that I was busy writing a Linux driver for it,
proprietary drives became obsolete and IDE/ATAPI drives became the
standard. At the time of the last update to this document (November
-1997) it is becoming difficult to even {\em find} anything less than a
-16 speed \cdrom\ drive, and 24 speed drives are common.
+1997) it is becoming difficult to even **find** anything less than a
+16 speed CD-ROM drive, and 24 speed drives are common.
-\newsection{Standardizing through another software level}
-\label{cdrom.c}
+.. _cdrom_api:
+
+Standardizing through another software level
+============================================
At the time this document was conceived, all drivers directly
-implemented the \cdrom\ $ioctl()$ calls through their own routines. This
+implemented the CD-ROM *ioctl()* calls through their own routines. This
led to the danger of different drivers forgetting to do important things
like checking that the user was giving the driver valid data. More
importantly, this led to the divergence of behavior, which has already
been discussed.
-For this reason, the \UCD\ was created to enforce consistent \cdrom\
-drive behavior, and to provide a common set of services to the various
-low-level \cdrom\ device drivers. The \UCD\ now provides another
-software-level, that separates the $ioctl()$ and $open()$ implementation
+For this reason, the Uniform CD-ROM Driver was created to enforce consistent
+CD-ROM drive behavior, and to provide a common set of services to the various
+low-level CD-ROM device drivers. The Uniform CD-ROM Driver now provides another
+software-level, that separates the *ioctl()* and *open()* implementation
from the actual hardware implementation. Note that this effort has
made few changes which will affect a user's application programs. The
greatest change involved moving the contents of the various low-level
-\cdrom\ drivers' header files to the kernel's cdrom directory. This was
+CD-ROM drivers\' header files to the kernel's cdrom directory. This was
done to help ensure that the user is only presented with only one cdrom
-interface, the interface defined in \cdromh.
+interface, the interface defined in `cdrom.h`.
-\cdrom\ drives are specific enough (\ie, different from other
+CD-ROM drives are specific enough (i. e., different from other
block-devices such as floppy or hard disc drives), to define a set
-of common {\em \cdrom\ device operations}, $<cdrom-device>_dops$.
+of common **CD-ROM device operations**, *<cdrom-device>_dops*.
These operations are different from the classical block-device file
-operations, $<block-device>_fops$.
+operations, *<block-device>_fops*.
-The routines for the \UCD\ interface level are implemented in the file
-\cdromc. In this file, the \UCD\ interfaces with the kernel as a block
-device by registering the following general $struct\ file_operations$:
-$$
-\halign{$#$\ \hfil&$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-struct& file_operations\ cdrom_fops = \{\hidewidth\cr
- &NULL, & lseek \cr
- &block_read, & read---general block-dev read \cr
- &block_write, & write---general block-dev write \cr
- &NULL, & readdir \cr
- &NULL, & select \cr
- &cdrom_ioctl, & ioctl \cr
- &NULL, & mmap \cr
- &cdrom_open, & open \cr
- &cdrom_release, & release \cr
- &NULL, & fsync \cr
- &NULL, & fasync \cr
- &cdrom_media_changed, & media change \cr
- &NULL & revalidate \cr
-\};\cr
-}
-$$
+The routines for the Uniform CD-ROM Driver interface level are implemented
+in the file `cdrom.c`. In this file, the Uniform CD-ROM Driver interfaces
+with the kernel as a block device by registering the following general
+*struct file_operations*::
-Every active \cdrom\ device shares this $struct$. The routines
-declared above are all implemented in \cdromc, since this file is the
-place where the behavior of all \cdrom-devices is defined and
-standardized. The actual interface to the various types of \cdrom\
-hardware is still performed by various low-level \cdrom-device
-drivers. These routines simply implement certain {\em capabilities\/}
-that are common to all \cdrom\ (and really, all removable-media
+ struct file_operations cdrom_fops = {
+ NULL, /∗ lseek ∗/
+ block _read , /∗ read—general block-dev read ∗/
+ block _write, /∗ write—general block-dev write ∗/
+ NULL, /∗ readdir ∗/
+ NULL, /∗ select ∗/
+ cdrom_ioctl, /∗ ioctl ∗/
+ NULL, /∗ mmap ∗/
+ cdrom_open, /∗ open ∗/
+ cdrom_release, /∗ release ∗/
+ NULL, /∗ fsync ∗/
+ NULL, /∗ fasync ∗/
+ cdrom_media_changed, /∗ media change ∗/
+ NULL /∗ revalidate ∗/
+ };
+
+Every active CD-ROM device shares this *struct*. The routines
+declared above are all implemented in `cdrom.c`, since this file is the
+place where the behavior of all CD-ROM-devices is defined and
+standardized. The actual interface to the various types of CD-ROM
+hardware is still performed by various low-level CD-ROM-device
+drivers. These routines simply implement certain **capabilities**
+that are common to all CD-ROM (and really, all removable-media
devices).
-Registration of a low-level \cdrom\ device driver is now done through
-the general routines in \cdromc, not through the Virtual File System
-(VFS) any more. The interface implemented in \cdromc\ is carried out
+Registration of a low-level CD-ROM device driver is now done through
+the general routines in `cdrom.c`, not through the Virtual File System
+(VFS) any more. The interface implemented in `cdrom.c` is carried out
through two general structures that contain information about the
capabilities of the driver, and the specific drives on which the
driver operates. The structures are:
-\begin{description}
-\item[$cdrom_device_ops$]
+
+cdrom_device_ops
This structure contains information about the low-level driver for a
- \cdrom\ device. This structure is conceptually connected to the major
+ CD-ROM device. This structure is conceptually connected to the major
number of the device (although some drivers may have different
major numbers, as is the case for the IDE driver).
-\item[$cdrom_device_info$]
- This structure contains information about a particular \cdrom\ drive,
+
+cdrom_device_info
+ This structure contains information about a particular CD-ROM drive,
such as its device name, speed, etc. This structure is conceptually
connected to the minor number of the device.
-\end{description}
-Registering a particular \cdrom\ drive with the \UCD\ is done by the
-low-level device driver though a call to:
-$$register_cdrom(struct\ cdrom_device_info * <device>_info)
-$$
-The device information structure, $<device>_info$, contains all the
+Registering a particular CD-ROM drive with the Uniform CD-ROM Driver
+is done by the low-level device driver though a call to::
+
+ register_cdrom(struct cdrom_device_info * <device>_info)
+
+The device information structure, *<device>_info*, contains all the
information needed for the kernel to interface with the low-level
-\cdrom\ device driver. One of the most important entries in this
-structure is a pointer to the $cdrom_device_ops$ structure of the
+CD-ROM device driver. One of the most important entries in this
+structure is a pointer to the *cdrom_device_ops* structure of the
low-level driver.
-The device operations structure, $cdrom_device_ops$, contains a list
+The device operations structure, *cdrom_device_ops*, contains a list
of pointers to the functions which are implemented in the low-level
-device driver. When \cdromc\ accesses a \cdrom\ device, it does it
+device driver. When `cdrom.c` accesses a CD-ROM device, it does it
through the functions in this structure. It is impossible to know all
-the capabilities of future \cdrom\ drives, so it is expected that this
+the capabilities of future CD-ROM drives, so it is expected that this
list may need to be expanded from time to time as new technologies are
developed. For example, CD-R and CD-R/W drives are beginning to become
popular, and support will soon need to be added for them. For now, the
-current $struct$ is:
-$$
-\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&
- $/*$ \rm# $*/$\hfil\cr
-struct& cdrom_device_ops\ \{ \hidewidth\cr
- &int& (* open)(struct\ cdrom_device_info *, int)\cr
- &void& (* release)(struct\ cdrom_device_info *);\cr
- &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr
- &unsigned\ int& (* check_events)(struct\ cdrom_device_info *, unsigned\ int, int);\cr
- &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr
- &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr
- &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr
- &int& (* select_speed)(struct\ cdrom_device_info *, int);\cr
- &int& (* select_disc)(struct\ cdrom_device_info *, int);\cr
- &int& (* get_last_session) (struct\ cdrom_device_info *,
- struct\ cdrom_multisession *{});\cr
- &int& (* get_mcn)(struct\ cdrom_device_info *, struct\ cdrom_mcn *{});\cr
- &int& (* reset)(struct\ cdrom_device_info *);\cr
- &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int,
- void *{});\cr
-\noalign{\medskip}
- &const\ int& capability;& capability flags \cr
- &int& (* generic_packet)(struct\ cdrom_device_info *, struct\ packet_command *{});\cr
-\};\cr
-}
-$$
+current *struct* is::
+
+ struct cdrom_device_ops {
+ int (*open)(struct cdrom_device_info *, int)
+ void (*release)(struct cdrom_device_info *);
+ int (*drive_status)(struct cdrom_device_info *, int);
+ unsigned int (*check_events)(struct cdrom_device_info *,
+ unsigned int, int);
+ int (*media_changed)(struct cdrom_device_info *, int);
+ int (*tray_move)(struct cdrom_device_info *, int);
+ int (*lock_door)(struct cdrom_device_info *, int);
+ int (*select_speed)(struct cdrom_device_info *, int);
+ int (*select_disc)(struct cdrom_device_info *, int);
+ int (*get_last_session) (struct cdrom_device_info *,
+ struct cdrom_multisession *);
+ int (*get_mcn)(struct cdrom_device_info *, struct cdrom_mcn *);
+ int (*reset)(struct cdrom_device_info *);
+ int (*audio_ioctl)(struct cdrom_device_info *,
+ unsigned int, void *);
+ const int capability; /* capability flags */
+ int (*generic_packet)(struct cdrom_device_info *,
+ struct packet_command *);
+ };
+
When a low-level device driver implements one of these capabilities,
-it should add a function pointer to this $struct$. When a particular
-function is not implemented, however, this $struct$ should contain a
-NULL instead. The $capability$ flags specify the capabilities of the
-\cdrom\ hardware and/or low-level \cdrom\ driver when a \cdrom\ drive
-is registered with the \UCD.
+it should add a function pointer to this *struct*. When a particular
+function is not implemented, however, this *struct* should contain a
+NULL instead. The *capability* flags specify the capabilities of the
+CD-ROM hardware and/or low-level CD-ROM driver when a CD-ROM drive
+is registered with the Uniform CD-ROM Driver.
Note that most functions have fewer parameters than their
-$blkdev_fops$ counterparts. This is because very little of the
-information in the structures $inode$ and $file$ is used. For most
-drivers, the main parameter is the $struct$ $cdrom_device_info$, from
+*blkdev_fops* counterparts. This is because very little of the
+information in the structures *inode* and *file* is used. For most
+drivers, the main parameter is the *struct* *cdrom_device_info*, from
which the major and minor number can be extracted. (Most low-level
-\cdrom\ drivers don't even look at the major and minor number though,
+CD-ROM drivers don't even look at the major and minor number though,
since many of them only support one device.) This will be available
-through $dev$ in $cdrom_device_info$ described below.
+through *dev* in *cdrom_device_info* described below.
The drive-specific, minor-like information that is registered with
-\cdromc, currently contains the following fields:
-$$
-\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&
- $/*$ \rm# $*/$\hfil\cr
-struct& cdrom_device_info\ \{ \hidewidth\cr
- & const\ struct\ cdrom_device_ops *& ops;& device operations for this major\cr
- & struct\ list_head& list;& linked list of all device_info\cr
- & struct\ gendisk *& disk;& matching block layer disk\cr
- & void *& handle;& driver-dependent data\cr
-\noalign{\medskip}
- & int& mask;& mask of capability: disables them \cr
- & int& speed;& maximum speed for reading data \cr
- & int& capacity;& number of discs in a jukebox \cr
-\noalign{\medskip}
- &unsigned\ int& options : 30;& options flags \cr
- &unsigned& mc_flags : 2;& media-change buffer flags \cr
- &unsigned\ int& vfs_events;& cached events for vfs path\cr
- &unsigned\ int& ioctl_events;& cached events for ioctl path\cr
- & int& use_count;& number of times device is opened\cr
- & char& name[20];& name of the device type\cr
-\noalign{\medskip}
- &__u8& sanyo_slot : 2;& Sanyo 3-CD changer support\cr
- &__u8& keeplocked : 1;& CDROM_LOCKDOOR status\cr
- &__u8& reserved : 5;& not used yet\cr
- & int& cdda_method;& see CDDA_* flags\cr
- &__u8& last_sense;& saves last sense key\cr
- &__u8& media_written;& dirty flag, DVD+RW bookkeeping\cr
- &unsigned\ short& mmc3_profile;& current MMC3 profile\cr
- & int& for_data;& unknown:TBD\cr
- & int\ (* exit)\ (struct\ cdrom_device_info *);&& unknown:TBD\cr
- & int& mrw_mode_page;& which MRW mode page is in use\cr
-\}\cr
-}$$
-Using this $struct$, a linked list of the registered minor devices is
-built, using the $next$ field. The device number, the device operations
+`cdrom.c`, currently contains the following fields::
+
+ struct cdrom_device_info {
+ const struct cdrom_device_ops * ops; /* device operations for this major */
+ struct list_head list; /* linked list of all device_info */
+ struct gendisk * disk; /* matching block layer disk */
+ void * handle; /* driver-dependent data */
+
+ int mask; /* mask of capability: disables them */
+ int speed; /* maximum speed for reading data */
+ int capacity; /* number of discs in a jukebox */
+
+ unsigned int options:30; /* options flags */
+ unsigned mc_flags:2; /* media-change buffer flags */
+ unsigned int vfs_events; /* cached events for vfs path */
+ unsigned int ioctl_events; /* cached events for ioctl path */
+ int use_count; /* number of times device is opened */
+ char name[20]; /* name of the device type */
+
+ __u8 sanyo_slot : 2; /* Sanyo 3-CD changer support */
+ __u8 keeplocked : 1; /* CDROM_LOCKDOOR status */
+ __u8 reserved : 5; /* not used yet */
+ int cdda_method; /* see CDDA_* flags */
+ __u8 last_sense; /* saves last sense key */
+ __u8 media_written; /* dirty flag, DVD+RW bookkeeping */
+ unsigned short mmc3_profile; /* current MMC3 profile */
+ int for_data; /* unknown:TBD */
+ int (*exit)(struct cdrom_device_info *);/* unknown:TBD */
+ int mrw_mode_page; /* which MRW mode page is in use */
+ };
+
+Using this *struct*, a linked list of the registered minor devices is
+built, using the *next* field. The device number, the device operations
struct and specifications of properties of the drive are stored in this
structure.
-The $mask$ flags can be used to mask out some of the capabilities listed
-in $ops\to capability$, if a specific drive doesn't support a feature
-of the driver. The value $speed$ specifies the maximum head-rate of the
-drive, measured in units of normal audio speed (176\,kB/sec raw data or
-150\,kB/sec file system data). The parameters are declared $const$
+The *mask* flags can be used to mask out some of the capabilities listed
+in *ops->capability*, if a specific drive doesn't support a feature
+of the driver. The value *speed* specifies the maximum head-rate of the
+drive, measured in units of normal audio speed (176kB/sec raw data or
+150kB/sec file system data). The parameters are declared *const*
because they describe properties of the drive, which don't change after
registration.
-A few registers contain variables local to the \cdrom\ drive. The
-flags $options$ are used to specify how the general \cdrom\ routines
+A few registers contain variables local to the CD-ROM drive. The
+flags *options* are used to specify how the general CD-ROM routines
should behave. These various flags registers should provide enough
-flexibility to adapt to the different users' wishes (and {\em not\/} the
-`arbitrary' wishes of the author of the low-level device driver, as is
-the case in the old scheme). The register $mc_flags$ is used to buffer
-the information from $media_changed()$ to two separate queues. Other
-data that is specific to a minor drive, can be accessed through $handle$,
+flexibility to adapt to the different users' wishes (and **not** the
+`arbitrary` wishes of the author of the low-level device driver, as is
+the case in the old scheme). The register *mc_flags* is used to buffer
+the information from *media_changed()* to two separate queues. Other
+data that is specific to a minor drive, can be accessed through *handle*,
which can point to a data structure specific to the low-level driver.
-The fields $use_count$, $next$, $options$ and $mc_flags$ need not be
+The fields *use_count*, *next*, *options* and *mc_flags* need not be
initialized.
-The intermediate software layer that \cdromc\ forms will perform some
+The intermediate software layer that `cdrom.c` forms will perform some
additional bookkeeping. The use count of the device (the number of
-processes that have the device opened) is registered in $use_count$. The
-function $cdrom_ioctl()$ will verify the appropriate user-memory regions
+processes that have the device opened) is registered in *use_count*. The
+function *cdrom_ioctl()* will verify the appropriate user-memory regions
for read and write, and in case a location on the CD is transferred,
-it will `sanitize' the format by making requests to the low-level
+it will `sanitize` the format by making requests to the low-level
drivers in a standard format, and translating all formats between the
user-software and low level drivers. This relieves much of the drivers'
memory checking and format checking and translation. Also, the necessary
structures will be declared on the program stack.
The implementation of the functions should be as defined in the
-following sections. Two functions {\em must\/} be implemented, namely
-$open()$ and $release()$. Other functions may be omitted, their
+following sections. Two functions **must** be implemented, namely
+*open()* and *release()*. Other functions may be omitted, their
corresponding capability flags will be cleared upon registration.
Generally, a function returns zero on success and negative on error. A
function call should return only after the command has completed, but of
course waiting for the device should not use processor time.
-\subsection{$Int\ open(struct\ cdrom_device_info * cdi, int\ purpose)$}
+::
-$Open()$ should try to open the device for a specific $purpose$, which
+ int open(struct cdrom_device_info *cdi, int purpose)
+
+*Open()* should try to open the device for a specific *purpose*, which
can be either:
-\begin{itemize}
-\item[0] Open for reading data, as done by {\tt {mount()}} (2), or the
-user commands {\tt {dd}} or {\tt {cat}}.
-\item[1] Open for $ioctl$ commands, as done by audio-CD playing
-programs.
-\end{itemize}
-Notice that any strategic code (closing tray upon $open()$, etc.)\ is
-done by the calling routine in \cdromc, so the low-level routine
+
+- Open for reading data, as done by `mount()` (2), or the
+ user commands `dd` or `cat`.
+- Open for *ioctl* commands, as done by audio-CD playing programs.
+
+Notice that any strategic code (closing tray upon *open()*, etc.) is
+done by the calling routine in `cdrom.c`, so the low-level routine
should only be concerned with proper initialization, such as spinning
-up the disc, etc. % and device-use count
+up the disc, etc.
+::
-\subsection{$Void\ release(struct\ cdrom_device_info * cdi)$}
-
+ void release(struct cdrom_device_info *cdi)
Device-specific actions should be taken such as spinning down the device.
However, strategic actions such as ejection of the tray, or unlocking
-the door, should be left over to the general routine $cdrom_release()$.
-This is the only function returning type $void$.
+the door, should be left over to the general routine *cdrom_release()*.
+This is the only function returning type *void*.
-\subsection{$Int\ drive_status(struct\ cdrom_device_info * cdi, int\ slot_nr)$}
-\label{drive status}
+.. _cdrom_drive_status:
-The function $drive_status$, if implemented, should provide
+::
+
+ int drive_status(struct cdrom_device_info *cdi, int slot_nr)
+
+The function *drive_status*, if implemented, should provide
information on the status of the drive (not the status of the disc,
which may or may not be in the drive). If the drive is not a changer,
-$slot_nr$ should be ignored. In \cdromh\ the possibilities are listed:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDS_NO_INFO& no information available\cr
-CDS_NO_DISC& no disc is inserted, tray is closed\cr
-CDS_TRAY_OPEN& tray is opened\cr
-CDS_DRIVE_NOT_READY& something is wrong, tray is moving?\cr
-CDS_DISC_OK& a disc is loaded and everything is fine\cr
-}
-$$
+*slot_nr* should be ignored. In `cdrom.h` the possibilities are listed::
-\subsection{$Int\ media_changed(struct\ cdrom_device_info * cdi, int\ disc_nr)$}
-This function is very similar to the original function in $struct\
-file_operations$. It returns 1 if the medium of the device $cdi\to
-dev$ has changed since the last call, and 0 otherwise. The parameter
-$disc_nr$ identifies a specific slot in a juke-box, it should be
-ignored for single-disc drives. Note that by `re-routing' this
-function through $cdrom_media_changed()$, we can implement separate
-queues for the VFS and a new $ioctl()$ function that can report device
-changes to software (\eg, an auto-mounting daemon).
+ CDS_NO_INFO /* no information available */
+ CDS_NO_DISC /* no disc is inserted, tray is closed */
+ CDS_TRAY_OPEN /* tray is opened */
+ CDS_DRIVE_NOT_READY /* something is wrong, tray is moving? */
+ CDS_DISC_OK /* a disc is loaded and everything is fine */
-\subsection{$Int\ tray_move(struct\ cdrom_device_info * cdi, int\ position)$}
+::
+
+ int media_changed(struct cdrom_device_info *cdi, int disc_nr)
+
+This function is very similar to the original function in $struct
+file_operations*. It returns 1 if the medium of the device *cdi->dev*
+has changed since the last call, and 0 otherwise. The parameter
+*disc_nr* identifies a specific slot in a juke-box, it should be
+ignored for single-disc drives. Note that by `re-routing` this
+function through *cdrom_media_changed()*, we can implement separate
+queues for the VFS and a new *ioctl()* function that can report device
+changes to software (e. g., an auto-mounting daemon).
+
+::
+
+ int tray_move(struct cdrom_device_info *cdi, int position)
This function, if implemented, should control the tray movement. (No
-other function should control this.) The parameter $position$ controls
+other function should control this.) The parameter *position* controls
the desired direction of movement:
-\begin{itemize}
-\item[0] Close tray
-\item[1] Open tray
-\end{itemize}
+
+- 0 Close tray
+- 1 Open tray
+
This function returns 0 upon success, and a non-zero value upon
error. Note that if the tray is already in the desired position, no
-action need be taken, and the return value should be 0.
+action need be taken, and the return value should be 0.
-\subsection{$Int\ lock_door(struct\ cdrom_device_info * cdi, int\ lock)$}
+::
+
+ int lock_door(struct cdrom_device_info *cdi, int lock)
This function (and no other code) controls locking of the door, if the
-drive allows this. The value of $lock$ controls the desired locking
+drive allows this. The value of *lock* controls the desired locking
state:
-\begin{itemize}
-\item[0] Unlock door, manual opening is allowed
-\item[1] Lock door, tray cannot be ejected manually
-\end{itemize}
+
+- 0 Unlock door, manual opening is allowed
+- 1 Lock door, tray cannot be ejected manually
+
This function returns 0 upon success, and a non-zero value upon
error. Note that if the door is already in the requested state, no
-action need be taken, and the return value should be 0.
+action need be taken, and the return value should be 0.
-\subsection{$Int\ select_speed(struct\ cdrom_device_info * cdi, int\ speed)$}
+::
-Some \cdrom\ drives are capable of changing their head-speed. There
-are several reasons for changing the speed of a \cdrom\ drive. Badly
-pressed \cdrom s may benefit from less-than-maximum head rate. Modern
-\cdrom\ drives can obtain very high head rates (up to $24\times$ is
-common). It has been reported that these drives can make reading
+ int select_speed(struct cdrom_device_info *cdi, int speed)
+
+Some CD-ROM drives are capable of changing their head-speed. There
+are several reasons for changing the speed of a CD-ROM drive. Badly
+pressed CD-ROM s may benefit from less-than-maximum head rate. Modern
+CD-ROM drives can obtain very high head rates (up to *24x* is
+common). It has been reported that these drives can make reading
errors at these high speeds, reducing the speed can prevent data loss
-in these circumstances. Finally, some of these drives can
-make an annoyingly loud noise, which a lower speed may reduce. %Finally,
-%although the audio-low-pass filters probably aren't designed for it,
-%more than real-time playback of audio might be used for high-speed
-%copying of audio tracks.
+in these circumstances. Finally, some of these drives can
+make an annoyingly loud noise, which a lower speed may reduce.
This function specifies the speed at which data is read or audio is
-played back. The value of $speed$ specifies the head-speed of the
-drive, measured in units of standard cdrom speed (176\,kB/sec raw data
-or 150\,kB/sec file system data). So to request that a \cdrom\ drive
-operate at 300\,kB/sec you would call the CDROM_SELECT_SPEED $ioctl$
-with $speed=2$. The special value `0' means `auto-selection', \ie,
+played back. The value of *speed* specifies the head-speed of the
+drive, measured in units of standard cdrom speed (176kB/sec raw data
+or 150kB/sec file system data). So to request that a CD-ROM drive
+operate at 300kB/sec you would call the CDROM_SELECT_SPEED *ioctl*
+with *speed=2*. The special value `0` means `auto-selection`, i. e.,
maximum data-rate or real-time audio rate. If the drive doesn't have
-this `auto-selection' capability, the decision should be made on the
+this `auto-selection` capability, the decision should be made on the
current disc loaded and the return value should be positive. A negative
return value indicates an error.
-\subsection{$Int\ select_disc(struct\ cdrom_device_info * cdi, int\ number)$}
+::
+
+ int select_disc(struct cdrom_device_info *cdi, int number)
If the drive can store multiple discs (a juke-box) this function
will perform disc selection. It should return the number of the
selected disc on success, a negative value on error. Currently, only
the ide-cd driver supports this functionality.
-\subsection{$Int\ get_last_session(struct\ cdrom_device_info * cdi, struct\
- cdrom_multisession * ms_info)$}
+::
-This function should implement the old corresponding $ioctl()$. For
-device $cdi\to dev$, the start of the last session of the current disc
-should be returned in the pointer argument $ms_info$. Note that
-routines in \cdromc\ have sanitized this argument: its requested
-format will {\em always\/} be of the type $CDROM_LBA$ (linear block
+ int get_last_session(struct cdrom_device_info *cdi,
+ struct cdrom_multisession *ms_info)
+
+This function should implement the old corresponding *ioctl()*. For
+device *cdi->dev*, the start of the last session of the current disc
+should be returned in the pointer argument *ms_info*. Note that
+routines in `cdrom.c` have sanitized this argument: its requested
+format will **always** be of the type *CDROM_LBA* (linear block
addressing mode), whatever the calling software requested. But
sanitization goes even further: the low-level implementation may
-return the requested information in $CDROM_MSF$ format if it wishes so
-(setting the $ms_info\rightarrow addr_format$ field appropriately, of
-course) and the routines in \cdromc\ will make the transformation if
+return the requested information in *CDROM_MSF* format if it wishes so
+(setting the *ms_info->addr_format* field appropriately, of
+course) and the routines in `cdrom.c` will make the transformation if
necessary. The return value is 0 upon success.
-\subsection{$Int\ get_mcn(struct\ cdrom_device_info * cdi, struct\
- cdrom_mcn * mcn)$}
+::
-Some discs carry a `Media Catalog Number' (MCN), also called
-`Universal Product Code' (UPC). This number should reflect the number
+ int get_mcn(struct cdrom_device_info *cdi,
+ struct cdrom_mcn *mcn)
+
+Some discs carry a `Media Catalog Number` (MCN), also called
+`Universal Product Code` (UPC). This number should reflect the number
that is generally found in the bar-code on the product. Unfortunately,
the few discs that carry such a number on the disc don't even use the
same format. The return argument to this function is a pointer to a
-pre-declared memory region of type $struct\ cdrom_mcn$. The MCN is
+pre-declared memory region of type *struct cdrom_mcn*. The MCN is
expected as a 13-character string, terminated by a null-character.
-\subsection{$Int\ reset(struct\ cdrom_device_info * cdi)$}
+::
+
+ int reset(struct cdrom_device_info *cdi)
This call should perform a hard-reset on the drive (although in
circumstances that a hard-reset is necessary, a drive may very well not
@@ -491,536 +483,581 @@ caller only after the drive has finished resetting. If the drive is no
longer listening, it may be wise for the underlying low-level cdrom
driver to time out.
-\subsection{$Int\ audio_ioctl(struct\ cdrom_device_info * cdi, unsigned\
- int\ cmd, void * arg)$}
+::
-Some of the \cdrom-$ioctl$s defined in \cdromh\ can be
+ int audio_ioctl(struct cdrom_device_info *cdi,
+ unsigned int cmd, void *arg)
+
+Some of the CD-ROM-\ *ioctl()*\ 's defined in `cdrom.h` can be
implemented by the routines described above, and hence the function
-$cdrom_ioctl$ will use those. However, most $ioctl$s deal with
+*cdrom_ioctl* will use those. However, most *ioctl()*\ 's deal with
audio-control. We have decided to leave these to be accessed through a
-single function, repeating the arguments $cmd$ and $arg$. Note that
-the latter is of type $void*{}$, rather than $unsigned\ long\
-int$. The routine $cdrom_ioctl()$ does do some useful things,
-though. It sanitizes the address format type to $CDROM_MSF$ (Minutes,
+single function, repeating the arguments *cmd* and *arg*. Note that
+the latter is of type *void*, rather than *unsigned long int*.
+The routine *cdrom_ioctl()* does do some useful things,
+though. It sanitizes the address format type to *CDROM_MSF* (Minutes,
Seconds, Frames) for all audio calls. It also verifies the memory
-location of $arg$, and reserves stack-memory for the argument. This
-makes implementation of the $audio_ioctl()$ much simpler than in the
+location of *arg*, and reserves stack-memory for the argument. This
+makes implementation of the *audio_ioctl()* much simpler than in the
old driver scheme. For example, you may look up the function
-$cm206_audio_ioctl()$ in {\tt {cm206.c}} that should be updated with
-this documentation.
+*cm206_audio_ioctl()* `cm206.c` that should be updated with
+this documentation.
-An unimplemented ioctl should return $-ENOSYS$, but a harmless request
-(\eg, $CDROMSTART$) may be ignored by returning 0 (success). Other
+An unimplemented ioctl should return *-ENOSYS*, but a harmless request
+(e. g., *CDROMSTART*) may be ignored by returning 0 (success). Other
errors should be according to the standards, whatever they are. When
-an error is returned by the low-level driver, the \UCD\ tries whenever
-possible to return the error code to the calling program. (We may decide
-to sanitize the return value in $cdrom_ioctl()$ though, in order to
-guarantee a uniform interface to the audio-player software.)
+an error is returned by the low-level driver, the Uniform CD-ROM Driver
+tries whenever possible to return the error code to the calling program.
+(We may decide to sanitize the return value in *cdrom_ioctl()* though, in
+order to guarantee a uniform interface to the audio-player software.)
-\subsection{$Int\ dev_ioctl(struct\ cdrom_device_info * cdi, unsigned\ int\
- cmd, unsigned\ long\ arg)$}
+::
-Some $ioctl$s seem to be specific to certain \cdrom\ drives. That is,
+ int dev_ioctl(struct cdrom_device_info *cdi,
+ unsigned int cmd, unsigned long arg)
+
+Some *ioctl()'s* seem to be specific to certain CD-ROM drives. That is,
they are introduced to service some capabilities of certain drives. In
-fact, there are 6 different $ioctl$s for reading data, either in some
+fact, there are 6 different *ioctl()'s* for reading data, either in some
particular kind of format, or audio data. Not many drives support
reading audio tracks as data, I believe this is because of protection
of copyrights of artists. Moreover, I think that if audio-tracks are
-supported, it should be done through the VFS and not via $ioctl$s. A
+supported, it should be done through the VFS and not via *ioctl()'s*. A
problem here could be the fact that audio-frames are 2352 bytes long,
so either the audio-file-system should ask for 75264 bytes at once
(the least common multiple of 512 and 2352), or the drivers should
bend their backs to cope with this incoherence (to which I would be
-opposed). Furthermore, it is very difficult for the hardware to find
+opposed). Furthermore, it is very difficult for the hardware to find
the exact frame boundaries, since there are no synchronization headers
-in audio frames. Once these issues are resolved, this code should be
-standardized in \cdromc.
-
-Because there are so many $ioctl$s that seem to be introduced to
-satisfy certain drivers,\footnote{Is there software around that
- actually uses these? I'd be interested!} any `non-standard' $ioctl$s
-are routed through the call $dev_ioctl()$. In principle, `private'
-$ioctl$s should be numbered after the device's major number, and not
-the general \cdrom\ $ioctl$ number, {\tt {0x53}}. Currently the
-non-supported $ioctl$s are: {\it CDROMREADMODE1, CDROMREADMODE2,
- CDROMREADAUDIO, CDROMREADRAW, CDROMREADCOOKED, CDROMSEEK,
- CDROMPLAY\-BLK and CDROM\-READALL}.
-
-
-\subsection{\cdrom\ capabilities}
-\label{capability}
-
-Instead of just implementing some $ioctl$ calls, the interface in
-\cdromc\ supplies the possibility to indicate the {\em capabilities\/}
-of a \cdrom\ drive. This can be done by ORing any number of
-capability-constants that are defined in \cdromh\ at the registration
-phase. Currently, the capabilities are any of:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDC_CLOSE_TRAY& can close tray by software control\cr
-CDC_OPEN_TRAY& can open tray\cr
-CDC_LOCK& can lock and unlock the door\cr
-CDC_SELECT_SPEED& can select speed, in units of $\sim$150\,kB/s\cr
-CDC_SELECT_DISC& drive is juke-box\cr
-CDC_MULTI_SESSION& can read sessions $>\rm1$\cr
-CDC_MCN& can read Media Catalog Number\cr
-CDC_MEDIA_CHANGED& can report if disc has changed\cr
-CDC_PLAY_AUDIO& can perform audio-functions (play, pause, etc)\cr
-CDC_RESET& hard reset device\cr
-CDC_IOCTLS& driver has non-standard ioctls\cr
-CDC_DRIVE_STATUS& driver implements drive status\cr
-}
-$$
-The capability flag is declared $const$, to prevent drivers from
+in audio frames. Once these issues are resolved, this code should be
+standardized in `cdrom.c`.
+
+Because there are so many *ioctl()'s* that seem to be introduced to
+satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
+are routed through the call *dev_ioctl()*. In principle, `private`
+*ioctl()*\ 's should be numbered after the device's major number, and not
+the general CD-ROM *ioctl* number, `0x53`. Currently the
+non-supported *ioctl()'s* are:
+
+ CDROMREADMODE1, CDROMREADMODE2, CDROMREADAUDIO, CDROMREADRAW,
+ CDROMREADCOOKED, CDROMSEEK, CDROMPLAY-BLK and CDROM-READALL
+
+.. [#f2]
+
+ Is there software around that actually uses these? I'd be interested!
+
+.. _cdrom_capabilities:
+
+CD-ROM capabilities
+-------------------
+
+Instead of just implementing some *ioctl* calls, the interface in
+`cdrom.c` supplies the possibility to indicate the **capabilities**
+of a CD-ROM drive. This can be done by ORing any number of
+capability-constants that are defined in `cdrom.h` at the registration
+phase. Currently, the capabilities are any of::
+
+ CDC_CLOSE_TRAY /* can close tray by software control */
+ CDC_OPEN_TRAY /* can open tray */
+ CDC_LOCK /* can lock and unlock the door */
+ CDC_SELECT_SPEED /* can select speed, in units of * sim*150 ,kB/s */
+ CDC_SELECT_DISC /* drive is juke-box */
+ CDC_MULTI_SESSION /* can read sessions *> rm1* */
+ CDC_MCN /* can read Media Catalog Number */
+ CDC_MEDIA_CHANGED /* can report if disc has changed */
+ CDC_PLAY_AUDIO /* can perform audio-functions (play, pause, etc) */
+ CDC_RESET /* hard reset device */
+ CDC_IOCTLS /* driver has non-standard ioctls */
+ CDC_DRIVE_STATUS /* driver implements drive status */
+
+The capability flag is declared *const*, to prevent drivers from
accidentally tampering with the contents. The capability fags actually
-inform \cdromc\ of what the driver can do. If the drive found
+inform `cdrom.c` of what the driver can do. If the drive found
by the driver does not have the capability, is can be masked out by
-the $cdrom_device_info$ variable $mask$. For instance, the SCSI \cdrom\
-driver has implemented the code for loading and ejecting \cdrom's, and
-hence its corresponding flags in $capability$ will be set. But a SCSI
-\cdrom\ drive might be a caddy system, which can't load the tray, and
-hence for this drive the $cdrom_device_info$ struct will have set
-the $CDC_CLOSE_TRAY$ bit in $mask$.
+the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
+driver has implemented the code for loading and ejecting CD-ROM's, and
+hence its corresponding flags in *capability* will be set. But a SCSI
+CD-ROM drive might be a caddy system, which can't load the tray, and
+hence for this drive the *cdrom_device_info* struct will have set
+the *CDC_CLOSE_TRAY* bit in *mask*.
-In the file \cdromc\ you will encounter many constructions of the type
-$$\it
-if\ (cdo\rightarrow capability \mathrel\& \mathord{\sim} cdi\rightarrow mask
- \mathrel{\&} CDC_<capability>) \ldots
-$$
-There is no $ioctl$ to set the mask\dots The reason is that
-I think it is better to control the {\em behavior\/} rather than the
-{\em capabilities}.
+In the file `cdrom.c` you will encounter many constructions of the type::
-\subsection{Options}
+ if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
-A final flag register controls the {\em behavior\/} of the \cdrom\
+There is no *ioctl* to set the mask... The reason is that
+I think it is better to control the **behavior** rather than the
+**capabilities**.
+
+Options
+-------
+
+A final flag register controls the **behavior** of the CD-ROM
drives, in order to satisfy different users' wishes, hopefully
independently of the ideas of the respective author who happened to
-have made the drive's support available to the \linux\ community. The
-current behavior options are:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDO_AUTO_CLOSE& try to close tray upon device $open()$\cr
-CDO_AUTO_EJECT& try to open tray on last device $close()$\cr
-CDO_USE_FFLAGS& use $file_pointer\rightarrow f_flags$ to indicate
- purpose for $open()$\cr
-CDO_LOCK& try to lock door if device is opened\cr
-CDO_CHECK_TYPE& ensure disc type is data if opened for data\cr
-}
-$$
+have made the drive's support available to the Linux community. The
+current behavior options are::
-The initial value of this register is $CDO_AUTO_CLOSE \mathrel|
-CDO_USE_FFLAGS \mathrel| CDO_LOCK$, reflecting my own view on user
+ CDO_AUTO_CLOSE /* try to close tray upon device open() */
+ CDO_AUTO_EJECT /* try to open tray on last device close() */
+ CDO_USE_FFLAGS /* use file_pointer->f_flags to indicate purpose for open() */
+ CDO_LOCK /* try to lock door if device is opened */
+ CDO_CHECK_TYPE /* ensure disc type is data if opened for data */
+
+The initial value of this register is
+`CDO_AUTO_CLOSE | CDO_USE_FFLAGS | CDO_LOCK`, reflecting my own view on user
interface and software standards. Before you protest, there are two
-new $ioctl$s implemented in \cdromc, that allow you to control the
-behavior by software. These are:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDROM_SET_OPTIONS& set options specified in $(int)\ arg$\cr
-CDROM_CLEAR_OPTIONS& clear options specified in $(int)\ arg$\cr
-}
-$$
-One option needs some more explanation: $CDO_USE_FFLAGS$. In the next
+new *ioctl()'s* implemented in `cdrom.c`, that allow you to control the
+behavior by software. These are::
+
+ CDROM_SET_OPTIONS /* set options specified in (int)arg */
+ CDROM_CLEAR_OPTIONS /* clear options specified in (int)arg */
+
+One option needs some more explanation: *CDO_USE_FFLAGS*. In the next
newsection we explain what the need for this option is.
-A software package {\tt setcd}, available from the Debian distribution
-and {\tt sunsite.unc.edu}, allows user level control of these flags.
+A software package `setcd`, available from the Debian distribution
+and `sunsite.unc.edu`, allows user level control of these flags.
-\newsection{The need to know the purpose of opening the \cdrom\ device}
-Traditionally, Unix devices can be used in two different `modes',
+The need to know the purpose of opening the CD-ROM device
+=========================================================
+
+Traditionally, Unix devices can be used in two different `modes`,
either by reading/writing to the device file, or by issuing
-controlling commands to the device, by the device's $ioctl()$
-call. The problem with \cdrom\ drives, is that they can be used for
+controlling commands to the device, by the device's *ioctl()*
+call. The problem with CD-ROM drives, is that they can be used for
two entirely different purposes. One is to mount removable
-file systems, \cdrom s, the other is to play audio CD's. Audio commands
-are implemented entirely through $ioctl$s, presumably because the
+file systems, CD-ROM's, the other is to play audio CD's. Audio commands
+are implemented entirely through *ioctl()\'s*, presumably because the
first implementation (SUN?) has been such. In principle there is
-nothing wrong with this, but a good control of the `CD player' demands
-that the device can {\em always\/} be opened in order to give the
-$ioctl$ commands, regardless of the state the drive is in.
+nothing wrong with this, but a good control of the `CD player` demands
+that the device can **always** be opened in order to give the
+*ioctl* commands, regardless of the state the drive is in.
On the other hand, when used as a removable-media disc drive (what the
-original purpose of \cdrom s is) we would like to make sure that the
+original purpose of CD-ROM s is) we would like to make sure that the
disc drive is ready for operation upon opening the device. In the old
-scheme, some \cdrom\ drivers don't do any integrity checking, resulting
+scheme, some CD-ROM drivers don't do any integrity checking, resulting
in a number of i/o errors reported by the VFS to the kernel when an
-attempt for mounting a \cdrom\ on an empty drive occurs. This is not a
-particularly elegant way to find out that there is no \cdrom\ inserted;
+attempt for mounting a CD-ROM on an empty drive occurs. This is not a
+particularly elegant way to find out that there is no CD-ROM inserted;
it more-or-less looks like the old IBM-PC trying to read an empty floppy
drive for a couple of seconds, after which the system complains it
-can't read from it. Nowadays we can {\em sense\/} the existence of a
+can't read from it. Nowadays we can **sense** the existence of a
removable medium in a drive, and we believe we should exploit that
fact. An integrity check on opening of the device, that verifies the
-availability of a \cdrom\ and its correct type (data), would be
+availability of a CD-ROM and its correct type (data), would be
desirable.
-These two ways of using a \cdrom\ drive, principally for data and
+These two ways of using a CD-ROM drive, principally for data and
secondarily for playing audio discs, have different demands for the
-behavior of the $open()$ call. Audio use simply wants to open the
+behavior of the *open()* call. Audio use simply wants to open the
device in order to get a file handle which is needed for issuing
-$ioctl$ commands, while data use wants to open for correct and
+*ioctl* commands, while data use wants to open for correct and
reliable data transfer. The only way user programs can indicate what
-their {\em purpose\/} of opening the device is, is through the $flags$
-parameter (see {\tt {open(2)}}). For \cdrom\ devices, these flags aren't
+their *purpose* of opening the device is, is through the *flags*
+parameter (see `open(2)`). For CD-ROM devices, these flags aren't
implemented (some drivers implement checking for write-related flags,
but this is not strictly necessary if the device file has correct
permission flags). Most option flags simply don't make sense to
-\cdrom\ devices: $O_CREAT$, $O_NOCTTY$, $O_TRUNC$, $O_APPEND$, and
-$O_SYNC$ have no meaning to a \cdrom.
+CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
+*O_SYNC* have no meaning to a CD-ROM.
-We therefore propose to use the flag $O_NONBLOCK$ to indicate
-that the device is opened just for issuing $ioctl$
-commands. Strictly, the meaning of $O_NONBLOCK$ is that opening and
+We therefore propose to use the flag *O_NONBLOCK* to indicate
+that the device is opened just for issuing *ioctl*
+commands. Strictly, the meaning of *O_NONBLOCK* is that opening and
subsequent calls to the device don't cause the calling process to
-wait. We could interpret this as ``don't wait until someone has
-inserted some valid data-\cdrom.'' Thus, our proposal of the
-implementation for the $open()$ call for \cdrom s is:
-\begin{itemize}
-\item If no other flags are set than $O_RDONLY$, the device is opened
-for data transfer, and the return value will be 0 only upon successful
-initialization of the transfer. The call may even induce some actions
-on the \cdrom, such as closing the tray.
-\item If the option flag $O_NONBLOCK$ is set, opening will always be
-successful, unless the whole device doesn't exist. The drive will take
-no actions whatsoever.
-\end{itemize}
+wait. We could interpret this as don't wait until someone has
+inserted some valid data-CD-ROM. Thus, our proposal of the
+implementation for the *open()* call for CD-ROM s is:
-\subsection{And what about standards?}
+- If no other flags are set than *O_RDONLY*, the device is opened
+ for data transfer, and the return value will be 0 only upon successful
+ initialization of the transfer. The call may even induce some actions
+ on the CD-ROM, such as closing the tray.
+- If the option flag *O_NONBLOCK* is set, opening will always be
+ successful, unless the whole device doesn't exist. The drive will take
+ no actions whatsoever.
+
+And what about standards?
+-------------------------
You might hesitate to accept this proposal as it comes from the
-\linux\ community, and not from some standardizing institute. What
+Linux community, and not from some standardizing institute. What
about SUN, SGI, HP and all those other Unix and hardware vendors?
Well, these companies are in the lucky position that they generally
control both the hardware and software of their supported products,
and are large enough to set their own standard. They do not have to
deal with a dozen or more different, competing hardware
-configurations.\footnote{Incidentally, I think that SUN's approach to
-mounting \cdrom s is very good in origin: under Solaris a
-volume-daemon automatically mounts a newly inserted \cdrom\ under {\tt
-{/cdrom/$<volume-name>$/}}. In my opinion they should have pushed this
-further and have {\em every\/} \cdrom\ on the local area network be
-mounted at the similar location, \ie, no matter in which particular
-machine you insert a \cdrom, it will always appear at the same
-position in the directory tree, on every system. When I wanted to
-implement such a user-program for \linux, I came across the
-differences in behavior of the various drivers, and the need for an
-$ioctl$ informing about media changes.}
-
-We believe that using $O_NONBLOCK$ to indicate that a device is being opened
-for $ioctl$ commands only can be easily introduced in the \linux\
+configurations\ [#f3]_.
+
+.. [#f3]
+
+ Incidentally, I think that SUN's approach to mounting CD-ROM s is very
+ good in origin: under Solaris a volume-daemon automatically mounts a
+ newly inserted CD-ROM under `/cdrom/*<volume-name>*`.
+
+ In my opinion they should have pushed this
+ further and have **every** CD-ROM on the local area network be
+ mounted at the similar location, i. e., no matter in which particular
+ machine you insert a CD-ROM, it will always appear at the same
+ position in the directory tree, on every system. When I wanted to
+ implement such a user-program for Linux, I came across the
+ differences in behavior of the various drivers, and the need for an
+ *ioctl* informing about media changes.
+
+We believe that using *O_NONBLOCK* to indicate that a device is being opened
+for *ioctl* commands only can be easily introduced in the Linux
community. All the CD-player authors will have to be informed, we can
-even send in our own patches to the programs. The use of $O_NONBLOCK$
+even send in our own patches to the programs. The use of *O_NONBLOCK*
has most likely no influence on the behavior of the CD-players on
-other operating systems than \linux. Finally, a user can always revert
-to old behavior by a call to $ioctl(file_descriptor, CDROM_CLEAR_OPTIONS,
-CDO_USE_FFLAGS)$.
+other operating systems than Linux. Finally, a user can always revert
+to old behavior by a call to
+*ioctl(file_descriptor, CDROM_CLEAR_OPTIONS, CDO_USE_FFLAGS)*.
-\subsection{The preferred strategy of $open()$}
+The preferred strategy of *open()*
+----------------------------------
-The routines in \cdromc\ are designed in such a way that run-time
-configuration of the behavior of \cdrom\ devices (of {\em any\/} type)
-can be carried out, by the $CDROM_SET/CLEAR_OPTIONS$ $ioctls$. Thus, various
+The routines in `cdrom.c` are designed in such a way that run-time
+configuration of the behavior of CD-ROM devices (of **any** type)
+can be carried out, by the *CDROM_SET/CLEAR_OPTIONS* *ioctls*. Thus, various
modes of operation can be set:
-\begin{description}
-\item[$CDO_AUTO_CLOSE \mathrel| CDO_USE_FFLAGS \mathrel| CDO_LOCK$] This
-is the default setting. (With $CDO_CHECK_TYPE$ it will be better, in the
-future.) If the device is not yet opened by any other process, and if
-the device is being opened for data ($O_NONBLOCK$ is not set) and the
-tray is found to be open, an attempt to close the tray is made. Then,
-it is verified that a disc is in the drive and, if $CDO_CHECK_TYPE$ is
-set, that it contains tracks of type `data mode 1.' Only if all tests
-are passed is the return value zero. The door is locked to prevent file
-system corruption. If the drive is opened for audio ($O_NONBLOCK$ is
-set), no actions are taken and a value of 0 will be returned.
-\item[$CDO_AUTO_CLOSE \mathrel| CDO_AUTO_EJECT \mathrel| CDO_LOCK$] This
-mimics the behavior of the current sbpcd-driver. The option flags are
-ignored, the tray is closed on the first open, if necessary. Similarly,
-the tray is opened on the last release, \ie, if a \cdrom\ is unmounted,
-it is automatically ejected, such that the user can replace it.
-\end{description}
+
+`CDO_AUTO_CLOSE | CDO_USE_FFLAGS | CDO_LOCK`
+ This is the default setting. (With *CDO_CHECK_TYPE* it will be better, in
+ the future.) If the device is not yet opened by any other process, and if
+ the device is being opened for data (*O_NONBLOCK* is not set) and the
+ tray is found to be open, an attempt to close the tray is made. Then,
+ it is verified that a disc is in the drive and, if *CDO_CHECK_TYPE* is
+ set, that it contains tracks of type `data mode 1`. Only if all tests
+ are passed is the return value zero. The door is locked to prevent file
+ system corruption. If the drive is opened for audio (*O_NONBLOCK* is
+ set), no actions are taken and a value of 0 will be returned.
+
+`CDO_AUTO_CLOSE | CDO_AUTO_EJECT | CDO_LOCK`
+ This mimics the behavior of the current sbpcd-driver. The option flags are
+ ignored, the tray is closed on the first open, if necessary. Similarly,
+ the tray is opened on the last release, i. e., if a CD-ROM is unmounted,
+ it is automatically ejected, such that the user can replace it.
+
We hope that these option can convince everybody (both driver
-maintainers and user program developers) to adopt the new \cdrom\
+maintainers and user program developers) to adopt the new CD-ROM
driver scheme and option flag interpretation.
-\newsection{Description of routines in \cdromc}
+Description of routines in `cdrom.c`
+====================================
-Only a few routines in \cdromc\ are exported to the drivers. In this
+Only a few routines in `cdrom.c` are exported to the drivers. In this
new section we will discuss these, as well as the functions that `take
-over' the \cdrom\ interface to the kernel. The header file belonging
-to \cdromc\ is called \cdromh. Formerly, some of the contents of this
-file were placed in the file {\tt {ucdrom.h}}, but this file has now been
-merged back into \cdromh.
+over' the CD-ROM interface to the kernel. The header file belonging
+to `cdrom.c` is called `cdrom.h`. Formerly, some of the contents of this
+file were placed in the file `ucdrom.h`, but this file has now been
+merged back into `cdrom.h`.
-\subsection{$Struct\ file_operations\ cdrom_fops$}
+::
-The contents of this structure were described in section~\ref{cdrom.c}.
-A pointer to this structure is assigned to the $fops$ field
-of the $struct gendisk$.
+ struct file_operations cdrom_fops
-\subsection{$Int\ register_cdrom( struct\ cdrom_device_info\ * cdi)$}
+The contents of this structure were described in cdrom_api_.
+A pointer to this structure is assigned to the *fops* field
+of the *struct gendisk*.
-This function is used in about the same way one registers $cdrom_fops$
+::
+
+ int register_cdrom(struct cdrom_device_info *cdi)
+
+This function is used in about the same way one registers *cdrom_fops*
with the kernel, the device operations and information structures,
-as described in section~\ref{cdrom.c}, should be registered with the
-\UCD:
-$$
-register_cdrom(\&<device>_info));
-$$
+as described in cdrom_api_, should be registered with the
+Uniform CD-ROM Driver::
+
+ register_cdrom(&<device>_info);
+
+
This function returns zero upon success, and non-zero upon
-failure. The structure $<device>_info$ should have a pointer to the
-driver's $<device>_dops$, as in
-$$
-\vbox{\halign{&$#$\hfil\cr
-struct\ &cdrom_device_info\ <device>_info = \{\cr
-& <device>_dops;\cr
-&\ldots\cr
-\}\cr
-}}$$
-Note that a driver must have one static structure, $<device>_dops$, while
-it may have as many structures $<device>_info$ as there are minor devices
-active. $Register_cdrom()$ builds a linked list from these.
+failure. The structure *<device>_info* should have a pointer to the
+driver's *<device>_dops*, as in::
-\subsection{$Void\ unregister_cdrom(struct\ cdrom_device_info * cdi)$}
+ struct cdrom_device_info <device>_info = {
+ <device>_dops;
+ ...
+ }
-Unregistering device $cdi$ with minor number $MINOR(cdi\to dev)$ removes
+Note that a driver must have one static structure, *<device>_dops*, while
+it may have as many structures *<device>_info* as there are minor devices
+active. *Register_cdrom()* builds a linked list from these.
+
+
+::
+
+ void unregister_cdrom(struct cdrom_device_info *cdi)
+
+Unregistering device *cdi* with minor number *MINOR(cdi->dev)* removes
the minor device from the list. If it was the last registered minor for
the low-level driver, this disconnects the registered device-operation
-routines from the \cdrom\ interface. This function returns zero upon
+routines from the CD-ROM interface. This function returns zero upon
success, and non-zero upon failure.
-\subsection{$Int\ cdrom_open(struct\ inode * ip, struct\ file * fp)$}
+::
+
+ int cdrom_open(struct inode * ip, struct file * fp)
This function is not called directly by the low-level drivers, it is
-listed in the standard $cdrom_fops$. If the VFS opens a file, this
+listed in the standard *cdrom_fops*. If the VFS opens a file, this
function becomes active. A strategy is implemented in this routine,
taking care of all capabilities and options that are set in the
-$cdrom_device_ops$ connected to the device. Then, the program flow is
-transferred to the device_dependent $open()$ call.
+*cdrom_device_ops* connected to the device. Then, the program flow is
+transferred to the device_dependent *open()* call.
-\subsection{$Void\ cdrom_release(struct\ inode *ip, struct\ file
-*fp)$}
+::
-This function implements the reverse-logic of $cdrom_open()$, and then
-calls the device-dependent $release()$ routine. When the use-count has
-reached 0, the allocated buffers are flushed by calls to $sync_dev(dev)$
-and $invalidate_buffers(dev)$.
+ void cdrom_release(struct inode *ip, struct file *fp)
+This function implements the reverse-logic of *cdrom_open()*, and then
+calls the device-dependent *release()* routine. When the use-count has
+reached 0, the allocated buffers are flushed by calls to *sync_dev(dev)*
+and *invalidate_buffers(dev)*.
-\subsection{$Int\ cdrom_ioctl(struct\ inode *ip, struct\ file *fp,
-unsigned\ int\ cmd, unsigned\ long\ arg)$}
-\label{cdrom-ioctl}
-This function handles all the standard $ioctl$ requests for \cdrom\
+.. _cdrom_ioctl:
+
+::
+
+ int cdrom_ioctl(struct inode *ip, struct file *fp,
+ unsigned int cmd, unsigned long arg)
+
+This function handles all the standard *ioctl* requests for CD-ROM
devices in a uniform way. The different calls fall into three
-categories: $ioctl$s that can be directly implemented by device
-operations, ones that are routed through the call $audio_ioctl()$, and
+categories: *ioctl()'s* that can be directly implemented by device
+operations, ones that are routed through the call *audio_ioctl()*, and
the remaining ones, that are presumable device-dependent. Generally, a
negative return value indicates an error.
-\subsubsection{Directly implemented $ioctl$s}
-\label{ioctl-direct}
+Directly implemented *ioctl()'s*
+--------------------------------
-The following `old' \cdrom-$ioctl$s are implemented by directly
-calling device-operations in $cdrom_device_ops$, if implemented and
+The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
+calling device-operations in *cdrom_device_ops*, if implemented and
not masked:
-\begin{description}
-\item[CDROMMULTISESSION] Requests the last session on a \cdrom.
-\item[CDROMEJECT] Open tray.
-\item[CDROMCLOSETRAY] Close tray.
-\item[CDROMEJECT_SW] If $arg\not=0$, set behavior to auto-close (close
-tray on first open) and auto-eject (eject on last release), otherwise
-set behavior to non-moving on $open()$ and $release()$ calls.
-\item[CDROM_GET_MCN] Get the Media Catalog Number from a CD.
-\end{description}
-\subsubsection{$Ioctl$s routed through $audio_ioctl()$}
-\label{ioctl-audio}
+`CDROMMULTISESSION`
+ Requests the last session on a CD-ROM.
+`CDROMEJECT`
+ Open tray.
+`CDROMCLOSETRAY`
+ Close tray.
+`CDROMEJECT_SW`
+ If *arg\not=0*, set behavior to auto-close (close
+ tray on first open) and auto-eject (eject on last release), otherwise
+ set behavior to non-moving on *open()* and *release()* calls.
+`CDROM_GET_MCN`
+ Get the Media Catalog Number from a CD.
-The following set of $ioctl$s are all implemented through a call to
-the $cdrom_fops$ function $audio_ioctl()$. Memory checks and
-allocation are performed in $cdrom_ioctl()$, and also sanitization of
-address format ($CDROM_LBA$/$CDROM_MSF$) is done.
-\begin{description}
-\item[CDROMSUBCHNL] Get sub-channel data in argument $arg$ of type $struct\
-cdrom_subchnl *{}$.
-\item[CDROMREADTOCHDR] Read Table of Contents header, in $arg$ of type
-$struct\ cdrom_tochdr *{}$.
-\item[CDROMREADTOCENTRY] Read a Table of Contents entry in $arg$ and
-specified by $arg$ of type $struct\ cdrom_tocentry *{}$.
-\item[CDROMPLAYMSF] Play audio fragment specified in Minute, Second,
-Frame format, delimited by $arg$ of type $struct\ cdrom_msf *{}$.
-\item[CDROMPLAYTRKIND] Play audio fragment in track-index format
-delimited by $arg$ of type $struct\ \penalty-1000 cdrom_ti *{}$.
-\item[CDROMVOLCTRL] Set volume specified by $arg$ of type $struct\
-cdrom_volctrl *{}$.
-\item[CDROMVOLREAD] Read volume into by $arg$ of type $struct\
-cdrom_volctrl *{}$.
-\item[CDROMSTART] Spin up disc.
-\item[CDROMSTOP] Stop playback of audio fragment.
-\item[CDROMPAUSE] Pause playback of audio fragment.
-\item[CDROMRESUME] Resume playing.
-\end{description}
+*Ioctl*s routed through *audio_ioctl()*
+---------------------------------------
-\subsubsection{New $ioctl$s in \cdromc}
+The following set of *ioctl()'s* are all implemented through a call to
+the *cdrom_fops* function *audio_ioctl()*. Memory checks and
+allocation are performed in *cdrom_ioctl()*, and also sanitization of
+address format (*CDROM_LBA*/*CDROM_MSF*) is done.
-The following $ioctl$s have been introduced to allow user programs to
-control the behavior of individual \cdrom\ devices. New $ioctl$
+`CDROMSUBCHNL`
+ Get sub-channel data in argument *arg* of type
+ `struct cdrom_subchnl *`.
+`CDROMREADTOCHDR`
+ Read Table of Contents header, in *arg* of type
+ `struct cdrom_tochdr *`.
+`CDROMREADTOCENTRY`
+ Read a Table of Contents entry in *arg* and specified by *arg*
+ of type `struct cdrom_tocentry *`.
+`CDROMPLAYMSF`
+ Play audio fragment specified in Minute, Second, Frame format,
+ delimited by *arg* of type `struct cdrom_msf *`.
+`CDROMPLAYTRKIND`
+ Play audio fragment in track-index format delimited by *arg*
+ of type `struct cdrom_ti *`.
+`CDROMVOLCTRL`
+ Set volume specified by *arg* of type `struct cdrom_volctrl *`.
+`CDROMVOLREAD`
+ Read volume into by *arg* of type `struct cdrom_volctrl *`.
+`CDROMSTART`
+ Spin up disc.
+`CDROMSTOP`
+ Stop playback of audio fragment.
+`CDROMPAUSE`
+ Pause playback of audio fragment.
+`CDROMRESUME`
+ Resume playing.
+
+New *ioctl()'s* in `cdrom.c`
+----------------------------
+
+The following *ioctl()'s* have been introduced to allow user programs to
+control the behavior of individual CD-ROM devices. New *ioctl*
commands can be identified by the underscores in their names.
-\begin{description}
-\item[CDROM_SET_OPTIONS] Set options specified by $arg$. Returns the
-option flag register after modification. Use $arg = \rm0$ for reading
-the current flags.
-\item[CDROM_CLEAR_OPTIONS] Clear options specified by $arg$. Returns
- the option flag register after modification.
-\item[CDROM_SELECT_SPEED] Select head-rate speed of disc specified as
- by $arg$ in units of standard cdrom speed (176\,kB/sec raw data or
- 150\,kB/sec file system data). The value 0 means `auto-select', \ie,
- play audio discs at real time and data discs at maximum speed. The value
- $arg$ is checked against the maximum head rate of the drive found in the
- $cdrom_dops$.
-\item[CDROM_SELECT_DISC] Select disc numbered $arg$ from a juke-box.
- First disc is numbered 0. The number $arg$ is checked against the
- maximum number of discs in the juke-box found in the $cdrom_dops$.
-\item[CDROM_MEDIA_CHANGED] Returns 1 if a disc has been changed since
- the last call. Note that calls to $cdrom_media_changed$ by the VFS
- are treated by an independent queue, so both mechanisms will detect
- a media change once. For juke-boxes, an extra argument $arg$
- specifies the slot for which the information is given. The special
- value $CDSL_CURRENT$ requests that information about the currently
- selected slot be returned.
-\item[CDROM_DRIVE_STATUS] Returns the status of the drive by a call to
- $drive_status()$. Return values are defined in section~\ref{drive
- status}. Note that this call doesn't return information on the
- current playing activity of the drive; this can be polled through an
- $ioctl$ call to $CDROMSUBCHNL$. For juke-boxes, an extra argument
- $arg$ specifies the slot for which (possibly limited) information is
- given. The special value $CDSL_CURRENT$ requests that information
- about the currently selected slot be returned.
-\item[CDROM_DISC_STATUS] Returns the type of the disc currently in the
- drive. It should be viewed as a complement to $CDROM_DRIVE_STATUS$.
- This $ioctl$ can provide \emph {some} information about the current
- disc that is inserted in the drive. This functionality used to be
- implemented in the low level drivers, but is now carried out
- entirely in \UCD.
-
- The history of development of the CD's use as a carrier medium for
- various digital information has lead to many different disc types.
- This $ioctl$ is useful only in the case that CDs have \emph {only
- one} type of data on them. While this is often the case, it is
- also very common for CDs to have some tracks with data, and some
- tracks with audio. Because this is an existing interface, rather
- than fixing this interface by changing the assumptions it was made
- under, thereby breaking all user applications that use this
- function, the \UCD\ implements this $ioctl$ as follows: If the CD in
- question has audio tracks on it, and it has absolutely no CD-I, XA,
- or data tracks on it, it will be reported as $CDS_AUDIO$. If it has
- both audio and data tracks, it will return $CDS_MIXED$. If there
- are no audio tracks on the disc, and if the CD in question has any
- CD-I tracks on it, it will be reported as $CDS_XA_2_2$. Failing
- that, if the CD in question has any XA tracks on it, it will be
- reported as $CDS_XA_2_1$. Finally, if the CD in question has any
- data tracks on it, it will be reported as a data CD ($CDS_DATA_1$).
- This $ioctl$ can return:
- $$
- \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
- CDS_NO_INFO& no information available\cr
- CDS_NO_DISC& no disc is inserted, or tray is opened\cr
- CDS_AUDIO& Audio disc (2352 audio bytes/frame)\cr
- CDS_DATA_1& data disc, mode 1 (2048 user bytes/frame)\cr
- CDS_XA_2_1& mixed data (XA), mode 2, form 1 (2048 user bytes)\cr
- CDS_XA_2_2& mixed data (XA), mode 2, form 1 (2324 user bytes)\cr
- CDS_MIXED& mixed audio/data disc\cr
- }
- $$
- For some information concerning frame layout of the various disc
- types, see a recent version of \cdromh.
+`CDROM_SET_OPTIONS`
+ Set options specified by *arg*. Returns the option flag register
+ after modification. Use *arg = \rm0* for reading the current flags.
+`CDROM_CLEAR_OPTIONS`
+ Clear options specified by *arg*. Returns the option flag register
+ after modification.
+`CDROM_SELECT_SPEED`
+ Select head-rate speed of disc specified as by *arg* in units
+ of standard cdrom speed (176\,kB/sec raw data or
+ 150kB/sec file system data). The value 0 means `auto-select`,
+ i. e., play audio discs at real time and data discs at maximum speed.
+ The value *arg* is checked against the maximum head rate of the
+ drive found in the *cdrom_dops*.
+`CDROM_SELECT_DISC`
+ Select disc numbered *arg* from a juke-box.
-\item[CDROM_CHANGER_NSLOTS] Returns the number of slots in a
- juke-box.
-\item[CDROMRESET] Reset the drive.
-\item[CDROM_GET_CAPABILITY] Returns the $capability$ flags for the
- drive. Refer to section \ref{capability} for more information on
- these flags.
-\item[CDROM_LOCKDOOR] Locks the door of the drive. $arg == \rm0$
- unlocks the door, any other value locks it.
-\item[CDROM_DEBUG] Turns on debugging info. Only root is allowed
- to do this. Same semantics as CDROM_LOCKDOOR.
-\end{description}
+ First disc is numbered 0. The number *arg* is checked against the
+ maximum number of discs in the juke-box found in the *cdrom_dops*.
+`CDROM_MEDIA_CHANGED`
+ Returns 1 if a disc has been changed since the last call.
+ Note that calls to *cdrom_media_changed* by the VFS are treated
+ by an independent queue, so both mechanisms will detect a
+ media change once. For juke-boxes, an extra argument *arg*
+ specifies the slot for which the information is given. The special
+ value *CDSL_CURRENT* requests that information about the currently
+ selected slot be returned.
+`CDROM_DRIVE_STATUS`
+ Returns the status of the drive by a call to
+ *drive_status()*. Return values are defined in cdrom_drive_status_.
+ Note that this call doesn't return information on the
+ current playing activity of the drive; this can be polled through
+ an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
+ *arg* specifies the slot for which (possibly limited) information is
+ given. The special value *CDSL_CURRENT* requests that information
+ about the currently selected slot be returned.
+`CDROM_DISC_STATUS`
+ Returns the type of the disc currently in the drive.
+ It should be viewed as a complement to *CDROM_DRIVE_STATUS*.
+ This *ioctl* can provide *some* information about the current
+ disc that is inserted in the drive. This functionality used to be
+ implemented in the low level drivers, but is now carried out
+ entirely in Uniform CD-ROM Driver.
-\subsubsection{Device dependent $ioctl$s}
+ The history of development of the CD's use as a carrier medium for
+ various digital information has lead to many different disc types.
+ This *ioctl* is useful only in the case that CDs have \emph {only
+ one} type of data on them. While this is often the case, it is
+ also very common for CDs to have some tracks with data, and some
+ tracks with audio. Because this is an existing interface, rather
+ than fixing this interface by changing the assumptions it was made
+ under, thereby breaking all user applications that use this
+ function, the Uniform CD-ROM Driver implements this *ioctl* as
+ follows: If the CD in question has audio tracks on it, and it has
+ absolutely no CD-I, XA, or data tracks on it, it will be reported
+ as *CDS_AUDIO*. If it has both audio and data tracks, it will
+ return *CDS_MIXED*. If there are no audio tracks on the disc, and
+ if the CD in question has any CD-I tracks on it, it will be
+ reported as *CDS_XA_2_2*. Failing that, if the CD in question
+ has any XA tracks on it, it will be reported as *CDS_XA_2_1*.
+ Finally, if the CD in question has any data tracks on it,
+ it will be reported as a data CD (*CDS_DATA_1*).
-Finally, all other $ioctl$s are passed to the function $dev_ioctl()$,
-if implemented. No memory allocation or verification is carried out.
+ This *ioctl* can return::
-\newsection{How to update your driver}
+ CDS_NO_INFO /* no information available */
+ CDS_NO_DISC /* no disc is inserted, or tray is opened */
+ CDS_AUDIO /* Audio disc (2352 audio bytes/frame) */
+ CDS_DATA_1 /* data disc, mode 1 (2048 user bytes/frame) */
+ CDS_XA_2_1 /* mixed data (XA), mode 2, form 1 (2048 user bytes) */
+ CDS_XA_2_2 /* mixed data (XA), mode 2, form 1 (2324 user bytes) */
+ CDS_MIXED /* mixed audio/data disc */
-\begin{enumerate}
-\item Make a backup of your current driver.
-\item Get hold of the files \cdromc\ and \cdromh, they should be in
+ For some information concerning frame layout of the various disc
+ types, see a recent version of `cdrom.h`.
+
+`CDROM_CHANGER_NSLOTS`
+ Returns the number of slots in a juke-box.
+`CDROMRESET`
+ Reset the drive.
+`CDROM_GET_CAPABILITY`
+ Returns the *capability* flags for the drive. Refer to section
+ cdrom_capabilities_ for more information on these flags.
+`CDROM_LOCKDOOR`
+ Locks the door of the drive. `arg == 0` unlocks the door,
+ any other value locks it.
+`CDROM_DEBUG`
+ Turns on debugging info. Only root is allowed to do this.
+ Same semantics as CDROM_LOCKDOOR.
+
+
+Device dependent *ioctl()'s*
+----------------------------
+
+Finally, all other *ioctl()'s* are passed to the function *dev_ioctl()*,
+if implemented. No memory allocation or verification is carried out.
+
+How to update your driver
+=========================
+
+- Make a backup of your current driver.
+- Get hold of the files `cdrom.c` and `cdrom.h`, they should be in
the directory tree that came with this documentation.
-\item Make sure you include \cdromh.
-\item Change the 3rd argument of $register_blkdev$ from
-$\&<your-drive>_fops$ to $\&cdrom_fops$.
-\item Just after that line, add the following to register with the \UCD:
- $$register_cdrom(\&<your-drive>_info);$$
- Similarly, add a call to $unregister_cdrom()$ at the appropriate place.
-\item Copy an example of the device-operations $struct$ to your
- source, \eg, from {\tt {cm206.c}} $cm206_dops$, and change all
+- Make sure you include `cdrom.h`.
+- Change the 3rd argument of *register_blkdev* from `&<your-drive>_fops`
+ to `&cdrom_fops`.
+- Just after that line, add the following to register with the Uniform
+ CD-ROM Driver::
+
+ register_cdrom(&<your-drive>_info);*
+
+ Similarly, add a call to *unregister_cdrom()* at the appropriate place.
+- Copy an example of the device-operations *struct* to your
+ source, e. g., from `cm206.c` *cm206_dops*, and change all
entries to names corresponding to your driver, or names you just
happen to like. If your driver doesn't support a certain function,
- make the entry $NULL$. At the entry $capability$ you should list all
+ make the entry *NULL*. At the entry *capability* you should list all
capabilities your driver currently supports. If your driver
has a capability that is not listed, please send me a message.
-\item Copy the $cdrom_device_info$ declaration from the same example
+- Copy the *cdrom_device_info* declaration from the same example
driver, and modify the entries according to your needs. If your
driver dynamically determines the capabilities of the hardware, this
- structure should also be declared dynamically.
-\item Implement all functions in your $<device>_dops$ structure,
- according to prototypes listed in \cdromh, and specifications given
- in section~\ref{cdrom.c}. Most likely you have already implemented
+ structure should also be declared dynamically.
+- Implement all functions in your `<device>_dops` structure,
+ according to prototypes listed in `cdrom.h`, and specifications given
+ in cdrom_api_. Most likely you have already implemented
the code in a large part, and you will almost certainly need to adapt the
prototype and return values.
-\item Rename your $<device>_ioctl()$ function to $audio_ioctl$ and
+- Rename your `<device>_ioctl()` function to *audio_ioctl* and
change the prototype a little. Remove entries listed in the first
- part in section~\ref{cdrom-ioctl}, if your code was OK, these are
+ part in cdrom_ioctl_, if your code was OK, these are
just calls to the routines you adapted in the previous step.
-\item You may remove all remaining memory checking code in the
- $audio_ioctl()$ function that deals with audio commands (these are
- listed in the second part of section~\ref{cdrom-ioctl}). There is no
- need for memory allocation either, so most $case$s in the $switch$
- statement look similar to:
- $$
- case\ CDROMREADTOCENTRY\colon get_toc_entry\bigl((struct\
- cdrom_tocentry *{})\ arg\bigr);
- $$
-\item All remaining $ioctl$ cases must be moved to a separate
- function, $<device>_ioctl$, the device-dependent $ioctl$s. Note that
+- You may remove all remaining memory checking code in the
+ *audio_ioctl()* function that deals with audio commands (these are
+ listed in the second part of cdrom_ioctl_. There is no
+ need for memory allocation either, so most *case*s in the *switch*
+ statement look similar to::
+
+ case CDROMREADTOCENTRY:
+ get_toc_entry\bigl((struct cdrom_tocentry *) arg);
+
+- All remaining *ioctl* cases must be moved to a separate
+ function, *<device>_ioctl*, the device-dependent *ioctl()'s*. Note that
memory checking and allocation must be kept in this code!
-\item Change the prototypes of $<device>_open()$ and
- $<device>_release()$, and remove any strategic code (\ie, tray
+- Change the prototypes of *<device>_open()* and
+ *<device>_release()*, and remove any strategic code (i. e., tray
movement, door locking, etc.).
-\item Try to recompile the drivers. We advise you to use modules, both
- for {\tt {cdrom.o}} and your driver, as debugging is much easier this
+- Try to recompile the drivers. We advise you to use modules, both
+ for `cdrom.o` and your driver, as debugging is much easier this
way.
-\end{enumerate}
-\newsection{Thanks}
+Thanks
+======
-Thanks to all the people involved. First, Erik Andersen, who has
-taken over the torch in maintaining \cdromc\ and integrating much
-\cdrom-related code in the 2.1-kernel. Thanks to Scott Snyder and
+Thanks to all the people involved. First, Erik Andersen, who has
+taken over the torch in maintaining `cdrom.c` and integrating much
+CD-ROM-related code in the 2.1-kernel. Thanks to Scott Snyder and
Gerd Knorr, who were the first to implement this interface for SCSI
and IDE-CD drivers and added many ideas for extension of the data
-structures relative to kernel~2.0. Further thanks to Heiko Ei{\ss}feldt,
-Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and Andrew
-Kroll, the \linux\ \cdrom\ device driver developers who were kind
+structures relative to kernel~2.0. Further thanks to Heiko Eißfeldt,
+Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard Mönkeberg and Andrew Kroll,
+the Linux CD-ROM device driver developers who were kind
enough to give suggestions and criticisms during the writing. Finally
of course, I want to thank Linus Torvalds for making this possible in
the first place.
-
-\vfill
-$ \version\ $
-\eject
-\end{document}
diff --git a/drivers/cdrom/cdrom.c b/drivers/cdrom/cdrom.c
index 933268b8d6a5..5d1e0a4a7d84 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.tex for usage information.
+ See Documentation/cdrom/cdrom-standard.txt 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
--
2.21.0
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 <[email protected]>
---
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
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 <[email protected]>
---
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 <[email protected]>, 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
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 <[email protected]>
---
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/locking/index.rst | 24 ++
...{lockdep-design.txt => lockdep-design.rst} | 51 ++--
.../locking/{lockstat.txt => lockstat.rst} | 221 ++++++++++--------
.../{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 +-
19 files changed, 428 insertions(+), 304 deletions(-)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
rename Documentation/locking/{lockstat.txt => lockstat.rst} (41%)
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 <[email protected]>
+
additions by Arjan van de Ven <[email protected]>
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.txt b/Documentation/locking/lockstat.rst
similarity index 41%
rename from Documentation/locking/lockstat.txt
rename to Documentation/locking/lockstat.rst
index fdbeb0c45ef3..536eab8dbd99 100644
--- a/Documentation/locking/lockstat.txt
+++ b/Documentation/locking/lockstat.rst
@@ -1,20 +1,25 @@
+===============
+Lock Statistics
+===============
-LOCK STATISTICS
-
-- WHAT
+What
+====
As the name suggests, it provides statistics on locks.
-- WHY
+
+Why
+===
Because things like lock contention can severely impact performance.
-- HOW
+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).
+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.
+hooks therein::
__acquire
|
@@ -36,24 +41,38 @@ hooks therein.
|
unlock
-lock, unlock - the regular lock functions
-__* - the hooks
-<> - states
+ 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
+ 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).
@@ -61,58 +80,60 @@ applicable).
It also tracks 4 contention points per class. A contention point is a call site
that had to wait on lock acquisition.
- - CONFIGURATION
+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
+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
@@ -133,40 +154,40 @@ 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:
+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
+ 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:
+View the top contending locks::
-# grep : /proc/lock_stat | head
+ # 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
@@ -178,6 +199,6 @@ View the top contending locks:
&(&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:
+Clear the statistics::
-# echo 0 > /proc/lock_stat
+ # 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 <[email protected]>
+
updated by Davidlohr Bueso <[email protected]>
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 <[email protected]>
+
Updated: Alex Shi <[email protected]> - 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 <[email protected]>
* 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
Instead of keeping the documentation inside s390dbf.rst,
move them to arch/s390/include/asm/debug.h, using standard
kernel-doc markups.
Keeping the documentation close to the code helps to keep it
updated. It also makes easier to document other stuff inside
debug.h, as all it needs is to add kernel-doc markups inside
it, as the file will be already be included at the produced
documentation.
-
Those were converted to kerneldoc using this script specially
designed to parse ths file, and manually editted:
<script>
use strict;
my $mode = "";
my $parameter = "";
my $ret = "";
my $descr = "";
sub add_var($)
{
my $ln = shift;
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
$ln =~ s/^(\S+)\s+/$1\t/;
print " * \@$ln\n";
}
sub add_return($)
{
my $ln = shift;
print " *\n * Return:\n" if ($mode ne "Return Value:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * - $ln\n";
}
sub add_description($)
{
my $ln = shift;
print " *\n * \n" if ($mode ne "Description:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * $ln\n";
}
sub flush_results()
{
print " */\n\n";
}
while (<>) {
if (m/^[\-]+$/) {
flush_results();
$mode = "";
$parameter = "";
$ret = "";
$descr = "";
next;
}
if (m/(Parameter:)(.*)/) {
print " *\n" if ($mode eq "func");
add_var($2);
$mode = $1;
next;
}
if (m/(Return Value:)(.*)/) {
add_return($2);
$mode = $1;
next;
}
if (m/(Description:)(.*)/) {
add_description($2);
$mode = $1;
next;
}
if ($mode eq "Parameter:") {
add_var($_);
next;
}
if ($mode eq "Return Value:") {
add_return($_);
next;
}
if ($mode eq "Description:") {
add_description($_);
next;
}
next if (m/^\s*$/);
if (m/^\S+.*\s\*?(\S+)\s*\(/) {
if ($mode eq "") {
print "/**\n * $1()\n";
} else {
print " * $1()\n";
}
$mode="func";
}
}
flush_results();
</script>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/s390/s390dbf.rst | 672 +--------------------------------
arch/s390/include/asm/debug.h | 231 ++++++++++++
2 files changed, 232 insertions(+), 671 deletions(-)
diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst
index ec2a1faa414b..d2595b548879 100644
--- a/Documentation/s390/s390dbf.rst
+++ b/Documentation/s390/s390dbf.rst
@@ -104,684 +104,14 @@ the "debug_stoppable" sysctl. If you set "debug_stoppable" to 0 the debug
feature cannot be stopped. If the debug feature is already stopped, it
will stay deactivated.
-----------------------------------------------------------------------------
-
Kernel Interfaces:
------------------
-::
-
- debug_info_t *debug_register(char *name, int pages, int nr_areas,
- int buf_size);
-
-Parameter:
- name:
- Name of debug log (e.g. used for debugfs entry)
- pages:
- Number of pages, which will be allocated per area
- nr_areas:
- Number of debug areas
- buf_size:
- Size of data area in each debug entry
-
-Return Value:
- Handle for generated debug area
-
- NULL if register failed
-
-Description: Allocates memory for a debug log
- Must not be called within an interrupt handler
-
-----------------------------------------------------------------------------
-
-::
-
- debug_info_t *debug_register_mode(char *name, int pages, int nr_areas,
- int buf_size, mode_t mode, uid_t uid,
- gid_t gid);
-
-Parameter:
- name:
- Name of debug log (e.g. used for debugfs entry)
- pages:
- Number of pages, which will be allocated per area
- nr_areas:
- Number of debug areas
- buf_size:
- Size of data area in each debug entry
- mode:
- File mode for debugfs files. E.g. S_IRWXUGO
- uid:
- User ID for debugfs files. Currently only 0 is
- supported.
- gid:
- Group ID for debugfs files. Currently only 0 is
- supported.
-
-Return Value:
- Handle for generated debug area
-
- NULL if register failed
-
-Description:
- Allocates memory for a debug log
- Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
- void debug_unregister (debug_info_t * id);
-
-Parameter:
- id:
- handle for debug log
-
-Return Value:
- none
-
-Description:
- frees memory for a debug log and removes all registered debug
- views.
-
- Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
- void debug_set_level (debug_info_t * id, int new_level);
-
-Parameter: id: handle for debug log
- new_level: new debug level
-
-Return Value:
- none
-
-Description:
- Sets new actual debug level if new_level is valid.
-
----------------------------------------------------------------------------
-
-::
-
- bool debug_level_enabled (debug_info_t * id, int level);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
-
-Return Value:
- True if level is less or equal to the current debug level.
-
-Description:
- Returns true if debug events for the specified level would be
- logged. Otherwise returns false.
-
----------------------------------------------------------------------------
-
-::
-
- void debug_stop_all(void);
-
-Parameter:
- none
-
-Return Value:
- none
-
-Description:
- stops the debug feature if stopping is allowed. Currently
- used in case of a kernel oops.
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_event (debug_info_t* id, int level, void* data,
- int length);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- pointer to data for debug entry
- length:
- length of data in bytes
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_int_event (debug_info_t * id, int level,
- unsigned int data);
- debug_entry_t* debug_long_event(debug_info_t * id, int level,
- unsigned long data);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- integer value for debug entry
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_text_event (debug_info_t * id, int level,
- const char* data);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- string for debug entry
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry in ascii format to active debug area
- (if level <= actual debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_sprintf_event (debug_info_t * id, int level,
- char* string,...);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- string:
- format string for debug entry
- ...:
- varargs used as in sprintf()
-
-Return Value: Address of written debug entry
-
-Description:
- writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level).
- floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_exception (debug_info_t* id, int level, void* data,
- int length);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- pointer to data for debug entry
- length:
- length of data in bytes
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_int_exception (debug_info_t * id, int level,
- unsigned int data);
- debug_entry_t* debug_long_exception(debug_info_t * id, int level,
- unsigned long data);
-
-Parameter: id: handle for debug log
- level: debug level
- data: integer value for debug entry
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_text_exception (debug_info_t * id, int level,
- const char* data);
-
-Parameter: id: handle for debug log
- level: debug level
- data: string for debug entry
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry in ascii format to active debug area
- (if level <= actual debug level) and switches to next debug
- area
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level,
- char* string,...);
-
-Parameter: id: handle for debug log
- level: debug level
- string: format string for debug entry
- ...: varargs used as in sprintf()
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level) and
- switches to next debug area.
- floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-::
-
- int debug_register_view (debug_info_t * id, struct debug_view *view);
-
-Parameter: id: handle for debug log
- view: pointer to debug view struct
-
-Return Value: 0 : ok
- < 0: Error
-
-Description: registers new debug view and creates debugfs dir entry
-
----------------------------------------------------------------------------
-
-::
-
- int debug_unregister_view (debug_info_t * id, struct debug_view *view);
-
-Parameter: id: handle for debug log
- view: pointer to debug view struct
-
-Return Value: 0 : ok
- < 0: Error
-
-Description: unregisters debug view and removes debugfs dir entry
-
-
+.. kernel-doc:: arch/s390/include/asm/debug.h
Predefined views:
-----------------
-extern struct debug_view debug_hex_ascii_view;
-
-extern struct debug_view debug_raw_view;
-
-extern struct debug_view debug_sprintf_view;
-
-Examples
---------
-
-::
-
- /*
- * hex_ascii- + raw-view Example
- */
-
- #include <linux/init.h>
- #include <asm/debug.h>
-
- static debug_info_t* debug_info;
-
- static int init(void)
- {
- /* register 4 debug areas with one page each and 4 byte data field */
-
- debug_info = debug_register ("test", 1, 4, 4 );
- debug_register_view(debug_info,&debug_hex_ascii_view);
- debug_register_view(debug_info,&debug_raw_view);
-
- debug_text_event(debug_info, 4 , "one ");
- debug_int_exception(debug_info, 4, 4711);
- debug_event(debug_info, 3, &debug_info, 4);
-
- return 0;
- }
-
- static void cleanup(void)
- {
- debug_unregister (debug_info);
- }
-
- module_init(init);
- module_exit(cleanup);
-
----------------------------------------------------------------------------
-
-::
-
- /*
- * sprintf-view Example
- */
-
- #include <linux/init.h>
- #include <asm/debug.h>
-
- static debug_info_t* debug_info;
-
- static int init(void)
- {
- /* register 4 debug areas with one page each and data field for */
- /* format string pointer + 2 varargs (= 3 * sizeof(long)) */
-
- debug_info = debug_register ("test", 1, 4, sizeof(long) * 3);
- debug_register_view(debug_info,&debug_sprintf_view);
-
- debug_sprintf_event(debug_info, 2 , "first event in %s:%i\n",__FILE__,__LINE__);
- debug_sprintf_exception(debug_info, 1, "pointer to debug info: %p\n",&debug_info);
-
- return 0;
- }
-
- static void cleanup(void)
- {
- debug_unregister (debug_info);
- }
-
- module_init(init);
- module_exit(cleanup);
-
-Debugfs Interface
------------------
-Views to the debug logs can be investigated through reading the corresponding
-debugfs-files:
-
-Example::
-
- > ls /sys/kernel/debug/s390dbf/dasd
- flush hex_ascii level pages raw
- > cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s
- 00 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | ....
- 00 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE
- 00 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | ....
- 00 00974733272:682281 1 * 02 0006ab08 41 4c 4c 43 | EXCP
- 01 00974733272:682284 2 - 02 0006ab16 45 43 4b 44 | ECKD
- 01 00974733272:682287 2 - 02 0006ab28 00 00 00 04 | ....
- 01 00974733272:682289 2 - 02 0006ab3e 00 00 00 20 | ...
- 01 00974733272:682297 2 - 02 0006ad7e 07 ea 4a 90 | ....
- 01 00974733272:684384 2 - 00 0006ade6 46 52 45 45 | FREE
- 01 00974733272:684388 2 - 00 0006adf6 07 ea 4a 90 | ....
-
-See section about predefined views for explanation of the above output!
-
-Changing the debug level
-------------------------
-
-Example::
-
-
- > cat /sys/kernel/debug/s390dbf/dasd/level
- 3
- > echo "5" > /sys/kernel/debug/s390dbf/dasd/level
- > cat /sys/kernel/debug/s390dbf/dasd/level
- 5
-
-Flushing debug areas
---------------------
-Debug areas can be flushed with piping the number of the desired
-area (0...n) to the debugfs file "flush". When using "-" all debug areas
-are flushed.
-
-Examples:
-
-1. Flush debug area 0::
-
- > echo "0" > /sys/kernel/debug/s390dbf/dasd/flush
-
-2. Flush all debug areas::
-
- > echo "-" > /sys/kernel/debug/s390dbf/dasd/flush
-
-Changing the size of debug areas
-------------------------------------
-It is possible the change the size of debug areas through piping
-the number of pages to the debugfs file "pages". The resize request will
-also flush the debug areas.
-
-Example:
-
-Define 4 pages for the debug areas of debug feature "dasd"::
-
- > echo "4" > /sys/kernel/debug/s390dbf/dasd/pages
-
-Stooping the debug feature
---------------------------
-Example:
-
-1. Check if stopping is allowed::
-
- > cat /proc/sys/s390dbf/debug_stoppable
-
-2. Stop debug feature::
-
- > echo 0 > /proc/sys/s390dbf/debug_active
-
-lcrash Interface
-----------------
-It is planned that the dump analysis tool lcrash gets an additional command
-'s390dbf' to display all the debug logs. With this tool it will be possible
-to investigate the debug logs on a live system and with a memory dump after
-a system crash.
-
-Investigating raw memory
-------------------------
-One last possibility to investigate the debug logs at a live
-system and after a system crash is to look at the raw memory
-under VM or at the Service Element.
-It is possible to find the anker of the debug-logs through
-the 'debug_area_first' symbol in the System map. Then one has
-to follow the correct pointers of the data-structures defined
-in debug.h and find the debug-areas in memory.
-Normally modules which use the debug feature will also have
-a global variable with the pointer to the debug-logs. Following
-this pointer it will also be possible to find the debug logs in
-memory.
-
-For this method it is recommended to use '16 * x + 4' byte (x = 0..n)
-for the length of the data field in debug_register() in
-order to see the debug entries well formatted.
-
-
-Predefined Views
-----------------
-
-There are three predefined views: hex_ascii, raw and sprintf.
-The hex_ascii view shows the data field in hex and ascii representation
-(e.g. '45 43 4b 44 | ECKD').
-The raw view returns a bytestream as the debug areas are stored in memory.
-
-The sprintf view formats the debug entries in the same way as the sprintf
-function would do. The sprintf event/exception functions write to the
-debug entry a pointer to the format string (size = sizeof(long))
-and for each vararg a long value. So e.g. for a debug entry with a format
-string plus two varargs one would need to allocate a (3 * sizeof(long))
-byte data area in the debug_register() function.
-
-IMPORTANT:
- Using "%s" in sprintf event functions is dangerous. You can only
- use "%s" in the sprintf event functions, if the memory for the passed string
- is available as long as the debug feature exists. The reason behind this is
- that due to performance considerations only a pointer to the string is stored
- in the debug feature. If you log a string that is freed afterwards, you will
- get an OOPS when inspecting the debug feature, because then the debug feature
- will access the already freed memory.
-
-NOTE:
- If using the sprintf view do NOT use other event/exception functions
- than the sprintf-event and -exception functions.
-
-The format of the hex_ascii and sprintf view is as follows:
-
-- Number of area
-- Timestamp (formatted as seconds and microseconds since 00:00:00 Coordinated
- Universal Time (UTC), January 1, 1970)
-- level of debug entry
-- Exception flag (* = Exception)
-- Cpu-Number of calling task
-- Return Address to caller
-- data field
-
-The format of the raw view is:
-
-- Header as described in debug.h
-- datafield
-
-A typical line of the hex_ascii view will look like the following (first line
-is only for explanation and will not be displayed when 'cating' the view):
-
-area time level exception cpu caller data (hex + ascii)
---------------------------------------------------------------------------
-00 00964419409:440690 1 - 00 88023fe
-
-
-Defining views
---------------
-
-Views are specified with the 'debug_view' structure. There are defined
-callback functions which are used for reading and writing the debugfs files::
-
- struct debug_view {
- char name[DEBUG_MAX_PROCF_LEN];
- debug_prolog_proc_t* prolog_proc;
- debug_header_proc_t* header_proc;
- debug_format_proc_t* format_proc;
- debug_input_proc_t* input_proc;
- void* private_data;
- };
-
-where::
-
- typedef int (debug_header_proc_t) (debug_info_t* id,
- struct debug_view* view,
- int area,
- debug_entry_t* entry,
- char* out_buf);
-
- typedef int (debug_format_proc_t) (debug_info_t* id,
- struct debug_view* view, char* out_buf,
- const char* in_buf);
- typedef int (debug_prolog_proc_t) (debug_info_t* id,
- struct debug_view* view,
- char* out_buf);
- typedef int (debug_input_proc_t) (debug_info_t* id,
- struct debug_view* view,
- struct file* file, const char* user_buf,
- size_t in_buf_size, loff_t* offset);
-
-
-The "private_data" member can be used as pointer to view specific data.
-It is not used by the debug feature itself.
-
-The output when reading a debugfs file is structured like this::
-
- "prolog_proc output"
-
- "header_proc output 1" "format_proc output 1"
- "header_proc output 2" "format_proc output 2"
- "header_proc output 3" "format_proc output 3"
- ...
-
-When a view is read from the debugfs, the Debug Feature calls the
-'prolog_proc' once for writing the prolog.
-Then 'header_proc' and 'format_proc' are called for each
-existing debug entry.
-
-The input_proc can be used to implement functionality when it is written to
-the view (e.g. like with 'echo "0" > /sys/kernel/debug/s390dbf/dasd/level).
-
-For header_proc there can be used the default function
-debug_dflt_header_fn() which is defined in debug.h.
-and which produces the same header output as the predefined views.
-E.g::
-
- 00 00964419409:440761 2 - 00 88023ec
-
-In order to see how to use the callback functions check the implementation
-of the default views!
-
-Example::
-
- #include <asm/debug.h>
-
- #define UNKNOWNSTR "data: %08x"
-
- const char* messages[] =
- {"This error...........\n",
- "That error...........\n",
- "Problem..............\n",
- "Something went wrong.\n",
- "Everything ok........\n",
- NULL
- };
-
- static int debug_test_format_fn(
- debug_info_t * id, struct debug_view *view,
- char *out_buf, const char *in_buf
- )
- {
- int i, rc = 0;
-
- if(id->buf_size >= 4) {
- int msg_nr = *((int*)in_buf);
- if(msg_nr < sizeof(messages)/sizeof(char*) - 1)
- rc += sprintf(out_buf, "%s", messages[msg_nr]);
- else
- rc += sprintf(out_buf, UNKNOWNSTR, msg_nr);
- }
- out:
- return rc;
- }
-
- struct debug_view debug_test_view = {
- "myview", /* name of view */
- NULL, /* no prolog */
- &debug_dflt_header_fn, /* default header for each entry */
- &debug_test_format_fn, /* our own format function */
- NULL, /* no input function */
- NULL /* no private data */
- };
-
-test:
-=====
-
::
debug_info_t *debug_info;
diff --git a/arch/s390/include/asm/debug.h b/arch/s390/include/asm/debug.h
index b94783f71322..b55486f70deb 100644
--- a/arch/s390/include/asm/debug.h
+++ b/arch/s390/include/asm/debug.h
@@ -95,25 +95,106 @@ debug_entry_t *debug_exception_common(debug_info_t *id, int level,
/* Debug Feature API: */
+/**
+ * debug_register() - allocates memory for a debug log.
+ *
+ * @name: Name of debug log (e.g. used for debugfs entry)
+ * @pages: Number of pages, which will be allocated per area
+ * @nr_areas: Number of debug areas
+ * @buf_size: Size of data area in each debug entry
+ *
+ * Return:
+ * - Handler for generated debug area
+ * - %NULL if register failed
+ *
+ * Must not be called within an interrupt handler.
+ */
debug_info_t *debug_register(const char *name, int pages, int nr_areas,
int buf_size);
+/**
+ * debug_register_mode() - allocates memory for a debug log.
+ *
+ * @name: Name of debug log (e.g. used for debugfs entry)
+ * @pages: Number of pages, which will be allocated per area
+ * @nr_areas: Number of debug areas
+ * @buf_size: Size of data area in each debug entry
+ * @mode: File mode for debugfs files. E.g. S_IRWXUGO
+ * @uid: User ID for debugfs files. Currently only 0 is supported.
+ * @gid: Group ID for debugfs files. Currently only 0 is supported.
+ *
+ * Return:
+ * - Handler for generated debug area
+ * - %NULL if register failed
+ *
+ * Must not be called within an interrupt handler
+ */
debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas,
int buf_size, umode_t mode, uid_t uid,
gid_t gid);
+/**
+ * debug_unregister() - frees memory for a debug log and removes all
+ * registered debug
+ * views.
+ *
+ * @id: handle for debug log
+ *
+ * Return:
+ * none
+ *
+ * Must not be called within an interrupt handler
+ */
void debug_unregister(debug_info_t *id);
+/**
+ * debug_set_level() - Sets new actual debug level if new_level is valid.
+ *
+ * @id: handle for debug log
+ * @new_level: new debug level
+ *
+ * Return:
+ * none
+ */
void debug_set_level(debug_info_t *id, int new_level);
void debug_set_critical(void);
+
+/**
+ * debug_stop_all() - stops the debug feature if stopping is allowed.
+ *
+ * Return:
+ * - none
+ */
void debug_stop_all(void);
+/**
+ * debug_level_enabled() - Returns true if debug events for the specified
+ * level would be logged. Otherwise returns false.
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ *
+ * Return:
+ * - %true if level is less or equal to the current debug level.
+ */
static inline bool debug_level_enabled(debug_info_t *id, int level)
{
return level <= id->level;
}
+/**
+ * debug_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @data: pointer to data for debug entry
+ * @length: length of data in bytes
+ *
+ * Return:
+ * - Address of written debug entry
+ */
static inline debug_entry_t *debug_event(debug_info_t *id, int level,
void *data, int length)
{
@@ -122,6 +203,18 @@ static inline debug_entry_t *debug_event(debug_info_t *id, int level,
return debug_event_common(id, level, data, length);
}
+/**
+ * debug_int_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
unsigned int tag)
{
@@ -132,6 +225,18 @@ static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
return debug_event_common(id, level, &t, sizeof(unsigned int));
}
+/**
+ * debug_long_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
unsigned long tag)
{
@@ -142,6 +247,18 @@ static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
return debug_event_common(id, level, &t, sizeof(unsigned long));
}
+/**
+ * debug_text_event() - writes debug entry in ascii format to active
+ * debug area (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @txt: string for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_text_event(debug_info_t *id, int level,
const char *txt)
{
@@ -158,6 +275,22 @@ extern debug_entry_t *
__debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
__attribute__ ((format(printf, 3, 4)));
+/**
+ * debug_sprintf_event() - writes debug entry with format string
+ * and varargs (longs) to active debug area
+ * (if level $<=$ actual debug level).
+ *
+ * @_id: handle for debug log
+ * @_level: debug level
+ * @_fmt: format string for debug entry
+ * @...: varargs used as in sprintf()
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ *
+ * floats and long long datatypes cannot be used as varargs.
+ */
#define debug_sprintf_event(_id, _level, _fmt, ...) \
({ \
debug_entry_t *__ret; \
@@ -172,6 +305,20 @@ __debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
__ret; \
})
+/**
+ * debug_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level) and switches
+ * to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @data: pointer to data for debug entry
+ * @length: length of data in bytes
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
void *data, int length)
{
@@ -180,6 +327,19 @@ static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
return debug_exception_common(id, level, data, length);
}
+/**
+ * debug_int_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ * and switches to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
unsigned int tag)
{
@@ -190,6 +350,19 @@ static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
return debug_exception_common(id, level, &t, sizeof(unsigned int));
}
+/**
+ * debug_long_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ * and switches to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
unsigned long tag)
{
@@ -200,6 +373,20 @@ static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
return debug_exception_common(id, level, &t, sizeof(unsigned long));
}
+/**
+ * debug_text_exception() - writes debug entry in ascii format to active
+ * debug area (if level <= actual debug level)
+ * and switches to next debug
+ * area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @txt: string for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_text_exception(debug_info_t *id, int level,
const char *txt)
{
@@ -216,6 +403,24 @@ extern debug_entry_t *
__debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
__attribute__ ((format(printf, 3, 4)));
+
+/**
+ * debug_sprintf_exception() - writes debug entry with format string and
+ * varargs (longs) to active debug area
+ * (if level $<=$ actual debug level)
+ * and switches to next debug area.
+ *
+ * @_id: handle for debug log
+ * @_level: debug level
+ * @_fmt: format string for debug entry
+ * @...: varargs used as in sprintf()
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ *
+ * floats and long long datatypes cannot be used as varargs.
+ */
#define debug_sprintf_exception(_id, _level, _fmt, ...) \
({ \
debug_entry_t *__ret; \
@@ -230,7 +435,33 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
__ret; \
})
+/**
+ * debug_register_view() - registers new debug view and creates debugfs
+ * dir entry
+ *
+ * @id: handle for debug log
+ * @view: pointer to debug view struct
+ *
+ * Return:
+ * - 0 : ok
+ * - < 0: Error
+ */
int debug_register_view(debug_info_t *id, struct debug_view *view);
+
+/**
+ * debug_unregister_view()
+ *
+ * @id: handle for debug log
+ * @view: pointer to debug view struct
+ *
+ * Return:
+ * - 0 : ok
+ * - < 0: Error
+ *
+ *
+ * unregisters debug view and removes debugfs dir entry
+ */
+
int debug_unregister_view(debug_info_t *id, struct debug_view *view);
/*
--
2.21.0
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 <[email protected]>
---
...{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 +++---
.../{dm-uevent.txt => dm-uevent.rst} | 143 ++++++-----
.../{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 +-
.../device-mapper/{linear.txt => linear.rst} | 100 ++++----
.../{log-writes.txt => log-writes.rst} | 91 +++----
...ersistent-data.txt => persistent-data.rst} | 4 +
.../{snapshot.txt => snapshot.rst} | 116 ++++-----
.../{statistics.txt => statistics.rst} | 62 ++---
.../{striped.txt => striped.rst} | 68 +++---
.../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 +-
.../filesystems/ubifs-authentication.md | 4 +-
drivers/md/Kconfig | 2 +-
drivers/md/dm-init.c | 2 +-
drivers/md/dm-raid.c | 2 +-
33 files changed, 1065 insertions(+), 737 deletions(-)
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%)
rename Documentation/device-mapper/{dm-uevent.txt => dm-uevent.rst} (31%)
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%)
rename Documentation/device-mapper/{linear.txt => linear.rst} (18%)
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%)
rename Documentation/device-mapper/{striped.txt => striped.rst} (32%)
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%)
diff --git a/Documentation/device-mapper/cache-policies.txt b/Documentation/device-mapper/cache-policies.rst
similarity index 94%
rename from Documentation/device-mapper/cache-policies.txt
rename to Documentation/device-mapper/cache-policies.rst
index 86786d87d9a8..b17fe352fc41 100644
--- a/Documentation/device-mapper/cache-policies.txt
+++ b/Documentation/device-mapper/cache-policies.rst
@@ -1,3 +1,4 @@
+=============================
Guidance for writing policies
=============================
@@ -30,7 +31,7 @@ multiqueue (mq)
This policy is now an alias for smq (see below).
-The following tunables are accepted, but have no effect:
+The following tunables are accepted, but have no effect::
'sequential_threshold <#nr_sequential_ios>'
'random_threshold <#nr_random_ios>'
@@ -56,7 +57,9 @@ mq policy's hints to be dropped. Also, performance of the cache may
degrade slightly until smq recalculates the origin device's hotspots
that should be cached.
-Memory usage:
+Memory usage
+^^^^^^^^^^^^
+
The mq policy used a lot of memory; 88 bytes per cache block on a 64
bit machine.
@@ -69,7 +72,9 @@ cache block).
All this means smq uses ~25bytes per cache block. Still a lot of
memory, but a substantial improvement nontheless.
-Level balancing:
+Level balancing
+^^^^^^^^^^^^^^^
+
mq placed entries in different levels of the multiqueue structures
based on their hit count (~ln(hit count)). This meant the bottom
levels generally had the most entries, and the top ones had very
@@ -94,7 +99,9 @@ is used to decide which blocks to promote. If the hotspot queue is
performing badly then it starts moving entries more quickly between
levels. This lets it adapt to new IO patterns very quickly.
-Performance:
+Performance
+^^^^^^^^^^^
+
Testing smq shows substantially better performance than mq.
cleaner
@@ -105,16 +112,19 @@ The cleaner writes back all dirty blocks in a cache to decommission it.
Examples
========
-The syntax for a table is:
+The syntax for a table is::
+
cache <metadata dev> <cache dev> <origin dev> <block size>
<#feature_args> [<feature arg>]*
<policy> <#policy_args> [<policy arg>]*
-The syntax to send a message using the dmsetup command is:
+The syntax to send a message using the dmsetup command is::
+
dmsetup message <mapped device> 0 sequential_threshold 1024
dmsetup message <mapped device> 0 random_threshold 8
-Using dmsetup:
+Using dmsetup::
+
dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \
/dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8"
creates a 128GB large mapped device named 'blah' with the
diff --git a/Documentation/device-mapper/cache.txt b/Documentation/device-mapper/cache.rst
similarity index 61%
rename from Documentation/device-mapper/cache.txt
rename to Documentation/device-mapper/cache.rst
index 8ae1cf8e94da..f15e5254d05b 100644
--- a/Documentation/device-mapper/cache.txt
+++ b/Documentation/device-mapper/cache.rst
@@ -1,3 +1,7 @@
+=====
+Cache
+=====
+
Introduction
============
@@ -24,10 +28,13 @@ scenarios (eg. a vm image server).
Glossary
========
- Migration - Movement of the primary copy of a logical block from one
+ Migration
+ Movement of the primary copy of a logical block from one
device to the other.
- Promotion - Migration from slow device to fast device.
- Demotion - Migration from fast device to slow device.
+ Promotion
+ Migration from slow device to fast device.
+ Demotion
+ Migration from fast device to slow device.
The origin device always contains a copy of the logical block, which
may be out of date or kept in sync with the copy on the cache device
@@ -169,45 +176,53 @@ Target interface
Constructor
-----------
- cache <metadata dev> <cache dev> <origin dev> <block size>
- <#feature args> [<feature arg>]*
- <policy> <#policy args> [policy args]*
+ ::
- metadata dev : fast device holding the persistent metadata
- cache dev : fast device holding cached data blocks
- origin dev : slow device holding original data blocks
- block size : cache unit size in sectors
+ cache <metadata dev> <cache dev> <origin dev> <block size>
+ <#feature args> [<feature arg>]*
+ <policy> <#policy args> [policy args]*
- #feature args : number of feature arguments passed
- feature args : writethrough or passthrough (The default is writeback.)
+ ================ =======================================================
+ metadata dev fast device holding the persistent metadata
+ cache dev fast device holding cached data blocks
+ origin dev slow device holding original data blocks
+ block size cache unit size in sectors
- policy : the replacement policy to use
- #policy args : an even number of arguments corresponding to
- key/value pairs passed to the policy
- policy args : key/value pairs passed to the policy
- E.g. 'sequential_threshold 1024'
- See cache-policies.txt for details.
+ #feature args number of feature arguments passed
+ feature args writethrough or passthrough (The default is writeback.)
+
+ policy the replacement policy to use
+ #policy args an even number of arguments corresponding to
+ key/value pairs passed to the policy
+ policy args key/value pairs passed to the policy
+ E.g. 'sequential_threshold 1024'
+ See cache-policies.txt for details.
+ ================ =======================================================
Optional feature arguments are:
- writethrough : write through caching that prohibits cache block
- content from being different from origin block content.
- Without this argument, the default behaviour is to write
- back cache block contents later for performance reasons,
- so they may differ from the corresponding origin blocks.
- passthrough : a degraded mode useful for various cache coherency
- situations (e.g., rolling back snapshots of
- underlying storage). Reads and writes always go to
- the origin. If a write goes to a cached origin
- block, then the cache block is invalidated.
- To enable passthrough mode the cache must be clean.
- metadata2 : use version 2 of the metadata. This stores the dirty bits
- in a separate btree, which improves speed of shutting
- down the cache.
+ ==================== ========================================================
+ writethrough write through caching that prohibits cache block
+ content from being different from origin block content.
+ Without this argument, the default behaviour is to write
+ back cache block contents later for performance reasons,
+ so they may differ from the corresponding origin blocks.
- no_discard_passdown : disable passing down discards from the cache
- to the origin's data device.
+ passthrough a degraded mode useful for various cache coherency
+ situations (e.g., rolling back snapshots of
+ underlying storage). Reads and writes always go to
+ the origin. If a write goes to a cached origin
+ block, then the cache block is invalidated.
+ To enable passthrough mode the cache must be clean.
+
+ metadata2 use version 2 of the metadata. This stores the dirty
+ bits in a separate btree, which improves speed of
+ shutting down the cache.
+
+ no_discard_passdown disable passing down discards from the cache
+ to the origin's data device.
+ ==================== ========================================================
A policy called 'default' is always registered. This is an alias for
the policy we currently think is giving best all round performance.
@@ -218,54 +233,61 @@ the characteristics of a specific policy, always request it by name.
Status
------
-<metadata block size> <#used metadata blocks>/<#total metadata blocks>
-<cache block size> <#used cache blocks>/<#total cache blocks>
-<#read hits> <#read misses> <#write hits> <#write misses>
-<#demotions> <#promotions> <#dirty> <#features> <features>*
-<#core args> <core args>* <policy name> <#policy args> <policy args>*
-<cache metadata mode>
+::
-metadata block size : Fixed block size for each metadata block in
- sectors
-#used metadata blocks : Number of metadata blocks used
-#total metadata blocks : Total number of metadata blocks
-cache block size : Configurable block size for the cache device
- in sectors
-#used cache blocks : Number of blocks resident in the cache
-#total cache blocks : Total number of cache blocks
-#read hits : Number of times a READ bio has been mapped
- to the cache
-#read misses : Number of times a READ bio has been mapped
- to the origin
-#write hits : Number of times a WRITE bio has been mapped
- to the cache
-#write misses : Number of times a WRITE bio has been
- mapped to the origin
-#demotions : Number of times a block has been removed
- from the cache
-#promotions : Number of times a block has been moved to
- the cache
-#dirty : Number of blocks in the cache that differ
- from the origin
-#feature args : Number of feature args to follow
-feature args : 'writethrough' (optional)
-#core args : Number of core arguments (must be even)
-core args : Key/value pairs for tuning the core
- e.g. migration_threshold
-policy name : Name of the policy
-#policy args : Number of policy arguments to follow (must be even)
-policy args : Key/value pairs e.g. sequential_threshold
-cache metadata mode : ro if read-only, rw if read-write
- In serious cases where even a read-only mode is deemed unsafe
- no further I/O will be permitted and the status will just
- contain the string 'Fail'. The userspace recovery tools
- should then be used.
-needs_check : 'needs_check' if set, '-' if not set
- A metadata operation has failed, resulting in the needs_check
- flag being set in the metadata's superblock. The metadata
- device must be deactivated and checked/repaired before the
- cache can be made fully operational again. '-' indicates
- needs_check is not set.
+ <metadata block size> <#used metadata blocks>/<#total metadata blocks>
+ <cache block size> <#used cache blocks>/<#total cache blocks>
+ <#read hits> <#read misses> <#write hits> <#write misses>
+ <#demotions> <#promotions> <#dirty> <#features> <features>*
+ <#core args> <core args>* <policy name> <#policy args> <policy args>*
+ <cache metadata mode>
+
+
+========================= =====================================================
+metadata block size Fixed block size for each metadata block in
+ sectors
+#used metadata blocks Number of metadata blocks used
+#total metadata blocks Total number of metadata blocks
+cache block size Configurable block size for the cache device
+ in sectors
+#used cache blocks Number of blocks resident in the cache
+#total cache blocks Total number of cache blocks
+#read hits Number of times a READ bio has been mapped
+ to the cache
+#read misses Number of times a READ bio has been mapped
+ to the origin
+#write hits Number of times a WRITE bio has been mapped
+ to the cache
+#write misses Number of times a WRITE bio has been
+ mapped to the origin
+#demotions Number of times a block has been removed
+ from the cache
+#promotions Number of times a block has been moved to
+ the cache
+#dirty Number of blocks in the cache that differ
+ from the origin
+#feature args Number of feature args to follow
+feature args 'writethrough' (optional)
+#core args Number of core arguments (must be even)
+core args Key/value pairs for tuning the core
+ e.g. migration_threshold
+policy name Name of the policy
+#policy args Number of policy arguments to follow (must be even)
+policy args Key/value pairs e.g. sequential_threshold
+cache metadata mode ro if read-only, rw if read-write
+
+ In serious cases where even a read-only mode is
+ deemed unsafe no further I/O will be permitted and
+ the status will just contain the string 'Fail'.
+ The userspace recovery tools should then be used.
+needs_check 'needs_check' if set, '-' if not set
+ A metadata operation has failed, resulting in the
+ needs_check flag being set in the metadata's
+ superblock. The metadata device must be
+ deactivated and checked/repaired before the
+ cache can be made fully operational again.
+ '-' indicates needs_check is not set.
+========================= =====================================================
Messages
--------
@@ -274,11 +296,12 @@ Policies will have different tunables, specific to each one, so we
need a generic way of getting and setting these. Device-mapper
messages are used. (A sysfs interface would also be possible.)
-The message format is:
+The message format is::
<key> <value>
-E.g.
+E.g.::
+
dmsetup message my_cache 0 sequential_threshold 1024
@@ -290,11 +313,12 @@ of values from 5 to 9. Each cblock must be expressed as a decimal
value, in the future a variant message that takes cblock ranges
expressed in hexadecimal may be needed to better support efficient
invalidation of larger caches. The cache must be in passthrough mode
-when invalidate_cblocks is used.
+when invalidate_cblocks is used::
invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]*
-E.g.
+E.g.::
+
dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789
Examples
@@ -304,8 +328,10 @@ The test suite can be found here:
https://github.com/jthornber/device-mapper-test-suite
-dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
- /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0'
-dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
- /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \
- mq 4 sequential_threshold 1024 random_threshold 8'
+::
+
+ dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
+ /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0'
+ dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
+ /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \
+ mq 4 sequential_threshold 1024 random_threshold 8'
diff --git a/Documentation/device-mapper/delay.txt b/Documentation/device-mapper/delay.rst
similarity index 53%
rename from Documentation/device-mapper/delay.txt
rename to Documentation/device-mapper/delay.rst
index 6426c45273cb..917ba8c33359 100644
--- a/Documentation/device-mapper/delay.txt
+++ b/Documentation/device-mapper/delay.rst
@@ -1,10 +1,12 @@
+========
dm-delay
========
Device-Mapper's "delay" target delays reads and/or writes
and maps them to different devices.
-Parameters:
+Parameters::
+
<device> <offset> <delay> [<write_device> <write_offset> <write_delay>
[<flush_device> <flush_offset> <flush_delay>]]
@@ -14,15 +16,16 @@ Delays are specified in milliseconds.
Example scripts
===============
-[[
-#!/bin/sh
-# Create device delaying rw operation for 500ms
-echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed
-]]
-
-[[
-#!/bin/sh
-# Create device delaying only write operation for 500ms and
-# splitting reads and writes to different devices $1 $2
-echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed
-]]
+
+::
+
+ #!/bin/sh
+ # Create device delaying rw operation for 500ms
+ echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed
+
+::
+
+ #!/bin/sh
+ # Create device delaying only write operation for 500ms and
+ # splitting reads and writes to different devices $1 $2
+ echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed
diff --git a/Documentation/device-mapper/dm-crypt.txt b/Documentation/device-mapper/dm-crypt.rst
similarity index 87%
rename from Documentation/device-mapper/dm-crypt.txt
rename to Documentation/device-mapper/dm-crypt.rst
index 3b3e1de21c9c..8f4a3f889d43 100644
--- a/Documentation/device-mapper/dm-crypt.txt
+++ b/Documentation/device-mapper/dm-crypt.rst
@@ -1,5 +1,6 @@
+========
dm-crypt
-=========
+========
Device-Mapper's "crypt" target provides transparent encryption of block devices
using the kernel crypto API.
@@ -7,15 +8,20 @@ using the kernel crypto API.
For a more detailed description of supported parameters see:
https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt
-Parameters: <cipher> <key> <iv_offset> <device path> \
+Parameters::
+
+ <cipher> <key> <iv_offset> <device path> \
<offset> [<#opt_params> <opt_params>]
<cipher>
Encryption cipher, encryption mode and Initial Vector (IV) generator.
- The cipher specifications format is:
+ The cipher specifications format is::
+
cipher[:keycount]-chainmode-ivmode[:ivopts]
- Examples:
+
+ Examples::
+
aes-cbc-essiv:sha256
aes-xts-plain64
serpent-xts-plain64
@@ -25,12 +31,17 @@ Parameters: <cipher> <key> <iv_offset> <device path> \
as for the first format type.
This format is mainly used for specification of authenticated modes.
- The crypto API cipher specifications format is:
+ The crypto API cipher specifications format is::
+
capi:cipher_api_spec-ivmode[:ivopts]
- Examples:
+
+ Examples::
+
capi:cbc(aes)-essiv:sha256
capi:xts(aes)-plain64
- Examples of authenticated modes:
+
+ Examples of authenticated modes::
+
capi:gcm(aes)-random
capi:authenc(hmac(sha256),xts(aes))-random
capi:rfc7539(chacha20,poly1305)-random
@@ -142,21 +153,21 @@ LUKS (Linux Unified Key Setup) is now the preferred way to set up disk
encryption with dm-crypt using the 'cryptsetup' utility, see
https://gitlab.com/cryptsetup/cryptsetup
-[[
-#!/bin/sh
-# Create a crypt device using dmsetup
-dmsetup create crypt1 --table "0 `blockdev --getsz $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0"
-]]
+::
-[[
-#!/bin/sh
-# Create a crypt device using dmsetup when encryption key is stored in keyring service
-dmsetup create crypt2 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 :32:logon:my_prefix:my_key 0 $1 0"
-]]
+ #!/bin/sh
+ # Create a crypt device using dmsetup
+ dmsetup create crypt1 --table "0 `blockdev --getsz $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0"
-[[
-#!/bin/sh
-# Create a crypt device using cryptsetup and LUKS header with default cipher
-cryptsetup luksFormat $1
-cryptsetup luksOpen $1 crypt1
-]]
+::
+
+ #!/bin/sh
+ # Create a crypt device using dmsetup when encryption key is stored in keyring service
+ dmsetup create crypt2 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 :32:logon:my_prefix:my_key 0 $1 0"
+
+::
+
+ #!/bin/sh
+ # Create a crypt device using cryptsetup and LUKS header with default cipher
+ cryptsetup luksFormat $1
+ cryptsetup luksOpen $1 crypt1
diff --git a/Documentation/device-mapper/dm-flakey.txt b/Documentation/device-mapper/dm-flakey.rst
similarity index 60%
rename from Documentation/device-mapper/dm-flakey.txt
rename to Documentation/device-mapper/dm-flakey.rst
index 9f0e247d0877..86138735879d 100644
--- a/Documentation/device-mapper/dm-flakey.txt
+++ b/Documentation/device-mapper/dm-flakey.rst
@@ -1,3 +1,4 @@
+=========
dm-flakey
=========
@@ -15,17 +16,26 @@ underlying devices.
Table parameters
----------------
+
+::
+
<dev path> <offset> <up interval> <down interval> \
[<num_features> [<feature arguments>]]
Mandatory parameters:
- <dev path>: Full pathname to the underlying block-device, or a
- "major:minor" device-number.
- <offset>: Starting sector within the device.
- <up interval>: Number of seconds device is available.
- <down interval>: Number of seconds device returns errors.
+
+ <dev path>:
+ Full pathname to the underlying block-device, or a
+ "major:minor" device-number.
+ <offset>:
+ Starting sector within the device.
+ <up interval>:
+ Number of seconds device is available.
+ <down interval>:
+ Number of seconds device returns errors.
Optional feature parameters:
+
If no feature parameters are present, during the periods of
unreliability, all I/O returns errors.
@@ -41,17 +51,24 @@ Optional feature parameters:
During <down interval>, replace <Nth_byte> of the data of
each matching bio with <value>.
- <Nth_byte>: The offset of the byte to replace.
- Counting starts at 1, to replace the first byte.
- <direction>: Either 'r' to corrupt reads or 'w' to corrupt writes.
- 'w' is incompatible with drop_writes.
- <value>: The value (from 0-255) to write.
- <flags>: Perform the replacement only if bio->bi_opf has all the
- selected flags set.
+ <Nth_byte>:
+ The offset of the byte to replace.
+ Counting starts at 1, to replace the first byte.
+ <direction>:
+ Either 'r' to corrupt reads or 'w' to corrupt writes.
+ 'w' is incompatible with drop_writes.
+ <value>:
+ The value (from 0-255) to write.
+ <flags>:
+ Perform the replacement only if bio->bi_opf has all the
+ selected flags set.
Examples:
+
+Replaces the 32nd byte of READ bios with the value 1::
+
corrupt_bio_byte 32 r 1 0
- - replaces the 32nd byte of READ bios with the value 1
+
+Replaces the 224th byte of REQ_META (=32) bios with the value 0::
corrupt_bio_byte 224 w 0 32
- - replaces the 224th byte of REQ_META (=32) bios with the value 0
diff --git a/Documentation/device-mapper/dm-init.txt b/Documentation/device-mapper/dm-init.rst
similarity index 69%
rename from Documentation/device-mapper/dm-init.txt
rename to Documentation/device-mapper/dm-init.rst
index 130b3c3679c5..e5242ff17e9b 100644
--- a/Documentation/device-mapper/dm-init.txt
+++ b/Documentation/device-mapper/dm-init.rst
@@ -1,5 +1,6 @@
+================================
Early creation of mapped devices
-====================================
+================================
It is possible to configure a device-mapper device to act as the root device for
your system in two ways.
@@ -12,15 +13,17 @@ The second is to create one or more device-mappers using the module parameter
The format is specified as a string of data separated by commas and optionally
semi-colons, where:
+
- a comma is used to separate fields like name, uuid, flags and table
(specifies one device)
- a semi-colon is used to separate devices.
-So the format will look like this:
+So the format will look like this::
dm-mod.create=<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,<minor>,<flags>,<table>[,<table>+]+]
-Where,
+Where::
+
<name> ::= The device name.
<uuid> ::= xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | ""
<minor> ::= The device minor number | ""
@@ -29,7 +32,7 @@ Where,
<target_type> ::= "verity" | "linear" | ... (see list below)
The dm line should be equivalent to the one used by the dmsetup tool with the
---concise argument.
+`--concise` argument.
Target types
============
@@ -38,32 +41,34 @@ Not all target types are available as there are serious risks in allowing
activation of certain DM targets without first using userspace tools to check
the validity of associated metadata.
- "cache": constrained, userspace should verify cache device
- "crypt": allowed
- "delay": allowed
- "era": constrained, userspace should verify metadata device
- "flakey": constrained, meant for test
- "linear": allowed
- "log-writes": constrained, userspace should verify metadata device
- "mirror": constrained, userspace should verify main/mirror device
- "raid": constrained, userspace should verify metadata device
- "snapshot": constrained, userspace should verify src/dst device
- "snapshot-origin": allowed
- "snapshot-merge": constrained, userspace should verify src/dst device
- "striped": allowed
- "switch": constrained, userspace should verify dev path
- "thin": constrained, requires dm target message from userspace
- "thin-pool": constrained, requires dm target message from userspace
- "verity": allowed
- "writecache": constrained, userspace should verify cache device
- "zero": constrained, not meant for rootfs
+======================= =======================================================
+`cache` constrained, userspace should verify cache device
+`crypt` allowed
+`delay` allowed
+`era` constrained, userspace should verify metadata device
+`flakey` constrained, meant for test
+`linear` allowed
+`log-writes` constrained, userspace should verify metadata device
+`mirror` constrained, userspace should verify main/mirror device
+`raid` constrained, userspace should verify metadata device
+`snapshot` constrained, userspace should verify src/dst device
+`snapshot-origin` allowed
+`snapshot-merge` constrained, userspace should verify src/dst device
+`striped` allowed
+`switch` constrained, userspace should verify dev path
+`thin` constrained, requires dm target message from userspace
+`thin-pool` constrained, requires dm target message from userspace
+`verity` allowed
+`writecache` constrained, userspace should verify cache device
+`zero` constrained, not meant for rootfs
+======================= =======================================================
If the target is not listed above, it is constrained by default (not tested).
Examples
========
An example of booting to a linear array made up of user-mode linux block
-devices:
+devices::
dm-mod.create="lroot,,,rw, 0 4096 linear 98:16 0, 4096 4096 linear 98:32 0" root=/dev/dm-0
@@ -71,8 +76,8 @@ This will boot to a rw dm-linear target of 8192 sectors split across two block
devices identified by their major:minor numbers. After boot, udev will rename
this target to /dev/mapper/lroot (depending on the rules). No uuid was assigned.
-An example of multiple device-mappers, with the dm-mod.create="..." contents is shown here
-split on multiple lines for readability:
+An example of multiple device-mappers, with the dm-mod.create="..." contents
+is shown here split on multiple lines for readability::
dm-linear,,1,rw,
0 32768 linear 8:1 0,
@@ -84,30 +89,36 @@ split on multiple lines for readability:
Other examples (per target):
-"crypt":
+"crypt"::
+
dm-crypt,,8,ro,
0 1048576 crypt aes-xts-plain64
babebabebabebabebabebabebabebabebabebabebabebabebabebabebabebabe 0
/dev/sda 0 1 allow_discards
-"delay":
+"delay"::
+
dm-delay,,4,ro,0 409600 delay /dev/sda1 0 500
-"linear":
+"linear"::
+
dm-linear,,,rw,
0 32768 linear /dev/sda1 0,
32768 1024000 linear /dev/sda2 0,
1056768 204800 linear /dev/sda3 0,
1261568 512000 linear /dev/sda4 0
-"snapshot-origin":
+"snapshot-origin"::
+
dm-snap-orig,,4,ro,0 409600 snapshot-origin 8:2
-"striped":
+"striped"::
+
dm-striped,,4,ro,0 1638400 striped 4 4096
/dev/sda1 0 /dev/sda2 0 /dev/sda3 0 /dev/sda4 0
-"verity":
+"verity"::
+
dm-verity,,4,ro,
0 1638400 verity 1 8:1 8:2 4096 4096 204800 1 sha256
fb1a5a0f00deb908d8b53cb270858975e76cf64105d412ce764225d53b8f3cfd
diff --git a/Documentation/device-mapper/dm-integrity.txt b/Documentation/device-mapper/dm-integrity.rst
similarity index 90%
rename from Documentation/device-mapper/dm-integrity.txt
rename to Documentation/device-mapper/dm-integrity.rst
index d63d78ffeb73..a30aa91b5fbe 100644
--- a/Documentation/device-mapper/dm-integrity.txt
+++ b/Documentation/device-mapper/dm-integrity.rst
@@ -1,3 +1,7 @@
+============
+dm-integrity
+============
+
The dm-integrity target emulates a block device that has additional
per-sector tags that can be used for storing integrity information.
@@ -35,15 +39,16 @@ zeroes. If the superblock is neither valid nor zeroed, the dm-integrity
target can't be loaded.
To use the target for the first time:
+
1. overwrite the superblock with zeroes
2. load the dm-integrity target with one-sector size, the kernel driver
- will format the device
+ will format the device
3. unload the dm-integrity target
4. read the "provided_data_sectors" value from the superblock
5. load the dm-integrity target with the the target size
- "provided_data_sectors"
+ "provided_data_sectors"
6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
- with the size "provided_data_sectors"
+ with the size "provided_data_sectors"
Target arguments:
@@ -51,17 +56,20 @@ Target arguments:
1. the underlying block device
2. the number of reserved sector at the beginning of the device - the
- dm-integrity won't read of write these sectors
+ dm-integrity won't read of write these sectors
3. the size of the integrity tag (if "-" is used, the size is taken from
- the internal-hash algorithm)
+ the internal-hash algorithm)
4. mode:
- D - direct writes (without journal) - in this mode, journaling is
+
+ D - direct writes (without journal)
+ in this mode, journaling is
not used and data sectors and integrity tags are written
separately. In case of crash, it is possible that the data
and integrity tag doesn't match.
- J - journaled writes - data and integrity tags are written to the
+ J - journaled writes
+ data and integrity tags are written to the
journal and atomicity is guaranteed. In case of crash,
either both data and tag or none of them are written. The
journaled mode degrades write throughput twice because the
@@ -178,9 +186,12 @@ and the reloaded target would be non-functional.
The layout of the formatted block device:
-* reserved sectors (they are not used by this target, they can be used for
- storing LUKS metadata or for other purpose), the size of the reserved
- area is specified in the target arguments
+
+* reserved sectors
+ (they are not used by this target, they can be used for
+ storing LUKS metadata or for other purpose), the size of the reserved
+ area is specified in the target arguments
+
* superblock (4kiB)
* magic string - identifies that the device was formatted
* version
@@ -192,40 +203,55 @@ The layout of the formatted block device:
metadata and padding). The user of this target should not send
bios that access data beyond the "provided data sectors" limit.
* flags
- SB_FLAG_HAVE_JOURNAL_MAC - a flag is set if journal_mac is used
- SB_FLAG_RECALCULATING - recalculating is in progress
- SB_FLAG_DIRTY_BITMAP - journal area contains the bitmap of dirty
- blocks
+ SB_FLAG_HAVE_JOURNAL_MAC
+ - a flag is set if journal_mac is used
+ SB_FLAG_RECALCULATING
+ - recalculating is in progress
+ SB_FLAG_DIRTY_BITMAP
+ - journal area contains the bitmap of dirty
+ blocks
* log2(sectors per block)
* a position where recalculating finished
* journal
The journal is divided into sections, each section contains:
+
* metadata area (4kiB), it contains journal entries
- every journal entry contains:
+
+ - every journal entry contains:
+
* logical sector (specifies where the data and tag should
be written)
* last 8 bytes of data
* integrity tag (the size is specified in the superblock)
- every metadata sector ends with
+
+ - every metadata sector ends with
+
* mac (8-bytes), all the macs in 8 metadata sectors form a
64-byte value. It is used to store hmac of sector
numbers in the journal section, to protect against a
possibility that the attacker tampers with sector
numbers in the journal.
* commit id
+
* data area (the size is variable; it depends on how many journal
entries fit into the metadata area)
- every sector in the data area contains:
+
+ - every sector in the data area contains:
+
* data (504 bytes of data, the last 8 bytes are stored in
the journal entry)
* commit id
+
To test if the whole journal section was written correctly, every
512-byte sector of the journal ends with 8-byte commit id. If the
commit id matches on all sectors in a journal section, then it is
assumed that the section was written correctly. If the commit id
doesn't match, the section was written partially and it should not
be replayed.
-* one or more runs of interleaved tags and data. Each run contains:
+
+* one or more runs of interleaved tags and data.
+ Each run contains:
+
* tag area - it contains integrity tags. There is one tag for each
sector in the data area
* data area - it contains data sectors. The number of data sectors
diff --git a/Documentation/device-mapper/dm-io.txt b/Documentation/device-mapper/dm-io.rst
similarity index 92%
rename from Documentation/device-mapper/dm-io.txt
rename to Documentation/device-mapper/dm-io.rst
index 3b5d9a52cdcf..d2492917a1f5 100644
--- a/Documentation/device-mapper/dm-io.txt
+++ b/Documentation/device-mapper/dm-io.rst
@@ -1,3 +1,4 @@
+=====
dm-io
=====
@@ -7,7 +8,7 @@ version.
The user must set up an io_region structure to describe the desired location
of the I/O. Each io_region indicates a block-device along with the starting
-sector and size of the region.
+sector and size of the region::
struct io_region {
struct block_device *bdev;
@@ -19,7 +20,7 @@ Dm-io can read from one io_region or write to one or more io_regions. Writes
to multiple regions are specified by an array of io_region structures.
The first I/O service type takes a list of memory pages as the data buffer for
-the I/O, along with an offset into the first page.
+the I/O, along with an offset into the first page::
struct page_list {
struct page_list *next;
@@ -35,7 +36,7 @@ the I/O, along with an offset into the first page.
The second I/O service type takes an array of bio vectors as the data buffer
for the I/O. This service can be handy if the caller has a pre-assembled bio,
-but wants to direct different portions of the bio to different devices.
+but wants to direct different portions of the bio to different devices::
int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where,
int rw, struct bio_vec *bvec,
@@ -47,7 +48,7 @@ but wants to direct different portions of the bio to different devices.
The third I/O service type takes a pointer to a vmalloc'd memory buffer as the
data buffer for the I/O. This service can be handy if the caller needs to do
I/O to a large region but doesn't want to allocate a large number of individual
-memory pages.
+memory pages::
int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw,
void *data, unsigned long *error_bits);
@@ -55,11 +56,11 @@ memory pages.
void *data, io_notify_fn fn, void *context);
Callers of the asynchronous I/O services must include the name of a completion
-callback routine and a pointer to some context data for the I/O.
+callback routine and a pointer to some context data for the I/O::
typedef void (*io_notify_fn)(unsigned long error, void *context);
-The "error" parameter in this callback, as well as the "*error" parameter in
+The "error" parameter in this callback, as well as the `*error` parameter in
all of the synchronous versions, is a bitset (instead of a simple error value).
In the case of an write-I/O to multiple regions, this bitset allows dm-io to
indicate success or failure on each individual region.
@@ -72,4 +73,3 @@ always available in order to avoid unnecessary waiting while performing I/O.
When the user is finished using the dm-io services, they should call
dm_io_put() and specify the same number of pages that were given on the
dm_io_get() call.
-
diff --git a/Documentation/device-mapper/dm-log.txt b/Documentation/device-mapper/dm-log.rst
similarity index 90%
rename from Documentation/device-mapper/dm-log.txt
rename to Documentation/device-mapper/dm-log.rst
index c155ac569c44..ba4fce39bc27 100644
--- a/Documentation/device-mapper/dm-log.txt
+++ b/Documentation/device-mapper/dm-log.rst
@@ -1,3 +1,4 @@
+=====================
Device-Mapper Logging
=====================
The device-mapper logging code is used by some of the device-mapper
@@ -16,11 +17,13 @@ dm_dirty_log_type in include/linux/dm-dirty-log.h). Various different
logging implementations are available and provide different
capabilities. The list includes:
+============== ==============================================================
Type Files
-==== =====
+============== ==============================================================
disk drivers/md/dm-log.c
core drivers/md/dm-log.c
userspace drivers/md/dm-log-userspace* include/linux/dm-log-userspace.h
+============== ==============================================================
The "disk" log type
-------------------
diff --git a/Documentation/device-mapper/dm-queue-length.txt b/Documentation/device-mapper/dm-queue-length.rst
similarity index 76%
rename from Documentation/device-mapper/dm-queue-length.txt
rename to Documentation/device-mapper/dm-queue-length.rst
index f4db2562175c..d8e381c1cb02 100644
--- a/Documentation/device-mapper/dm-queue-length.txt
+++ b/Documentation/device-mapper/dm-queue-length.rst
@@ -1,3 +1,4 @@
+===============
dm-queue-length
===============
@@ -6,12 +7,18 @@ which selects a path with the least number of in-flight I/Os.
The path selector name is 'queue-length'.
Table parameters for each path: [<repeat_count>]
+
+::
+
<repeat_count>: The number of I/Os to dispatch using the selected
path before switching to the next path.
If not given, internal default is used. To check
the default value, see the activated table.
Status for each path: <status> <fail-count> <in-flight>
+
+::
+
<status>: 'A' if the path is active, 'F' if the path is failed.
<fail-count>: The number of path failures.
<in-flight>: The number of in-flight I/Os on the path.
@@ -29,11 +36,13 @@ Examples
========
In case that 2 paths (sda and sdb) are used with repeat_count == 128.
-# echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \
- dmsetup create test
-#
-# dmsetup table
-test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128
-#
-# dmsetup status
-test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0
+::
+
+ # echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \
+ dmsetup create test
+ #
+ # dmsetup table
+ test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128
+ #
+ # dmsetup status
+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0
diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.rst
similarity index 71%
rename from Documentation/device-mapper/dm-raid.txt
rename to Documentation/device-mapper/dm-raid.rst
index 2355bef14653..2fe255b130fb 100644
--- a/Documentation/device-mapper/dm-raid.txt
+++ b/Documentation/device-mapper/dm-raid.rst
@@ -1,3 +1,4 @@
+=======
dm-raid
=======
@@ -8,49 +9,66 @@ interface.
Mapping Table Interface
-----------------------
-The target is named "raid" and it accepts the following parameters:
+The target is named "raid" and it accepts the following parameters::
<raid_type> <#raid_params> <raid_params> \
<#raid_devs> <metadata_dev0> <dev0> [.. <metadata_devN> <devN>]
<raid_type>:
+
+ ============= ===============================================================
raid0 RAID0 striping (no resilience)
raid1 RAID1 mirroring
raid4 RAID4 with dedicated last parity disk
raid5_n RAID5 with dedicated last parity disk supporting takeover
Same as raid4
- -Transitory layout
+
+ - Transitory layout
raid5_la RAID5 left asymmetric
+
- rotating parity 0 with data continuation
raid5_ra RAID5 right asymmetric
+
- rotating parity N with data continuation
raid5_ls RAID5 left symmetric
+
- rotating parity 0 with data restart
raid5_rs RAID5 right symmetric
+
- rotating parity N with data restart
raid6_zr RAID6 zero restart
+
- rotating parity zero (left-to-right) with data restart
raid6_nr RAID6 N restart
+
- rotating parity N (right-to-left) with data restart
raid6_nc RAID6 N continue
+
- rotating parity N (right-to-left) with data continuation
raid6_n_6 RAID6 with dedicate parity disks
+
- parity and Q-syndrome on the last 2 disks;
layout for takeover from/to raid4/raid5_n
raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk
+
- layout for takeover from raid5_la from/to raid6
raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk
+
- layout for takeover from raid5_ra from/to raid6
raid6_ls_6 Same as "raid5_ls" dedicated last Q-syndrome disk
+
- layout for takeover from raid5_ls from/to raid6
raid6_rs_6 Same as "raid5_rs" dedicated last Q-syndrome disk
+
- layout for takeover from raid5_rs from/to raid6
raid10 Various RAID10 inspired algorithms chosen by additional params
(see raid10_format and raid10_copies below)
+
- RAID10: Striped Mirrors (aka 'Striping on top of mirrors')
- RAID1E: Integrated Adjacent Stripe Mirroring
- RAID1E: Integrated Offset Stripe Mirroring
- - and other similar RAID10 variants
+ - and other similar RAID10 variants
+ ============= ===============================================================
Reference: Chapter 4 of
http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
@@ -58,33 +76,41 @@ The target is named "raid" and it accepts the following parameters:
<#raid_params>: The number of parameters that follow.
<raid_params> consists of
+
Mandatory parameters:
- <chunk_size>: Chunk size in sectors. This parameter is often known as
+ <chunk_size>:
+ Chunk size in sectors. This parameter is often known as
"stripe size". It is the only mandatory parameter and
is placed first.
followed by optional parameters (in any order):
- [sync|nosync] Force or prevent RAID initialization.
+ [sync|nosync]
+ Force or prevent RAID initialization.
- [rebuild <idx>] Rebuild drive number 'idx' (first drive is 0).
+ [rebuild <idx>]
+ Rebuild drive number 'idx' (first drive is 0).
[daemon_sleep <ms>]
Interval between runs of the bitmap daemon that
clear bits. A longer interval means less bitmap I/O but
resyncing after a failure is likely to take longer.
- [min_recovery_rate <kB/sec/disk>] Throttle RAID initialization
- [max_recovery_rate <kB/sec/disk>] Throttle RAID initialization
- [write_mostly <idx>] Mark drive index 'idx' write-mostly.
- [max_write_behind <sectors>] See '--write-behind=' (man mdadm)
- [stripe_cache <sectors>] Stripe cache size (RAID 4/5/6 only)
+ [min_recovery_rate <kB/sec/disk>]
+ Throttle RAID initialization
+ [max_recovery_rate <kB/sec/disk>]
+ Throttle RAID initialization
+ [write_mostly <idx>]
+ Mark drive index 'idx' write-mostly.
+ [max_write_behind <sectors>]
+ See '--write-behind=' (man mdadm)
+ [stripe_cache <sectors>]
+ Stripe cache size (RAID 4/5/6 only)
[region_size <sectors>]
The region_size multiplied by the number of regions is the
logical size of the array. The bitmap records the device
synchronisation state for each region.
- [raid10_copies <# copies>]
- [raid10_format <near|far|offset>]
+ [raid10_copies <# copies>], [raid10_format <near|far|offset>]
These two options are used to alter the default layout of
a RAID10 configuration. The number of copies is can be
specified, but the default is 2. There are also three
@@ -93,13 +119,17 @@ The target is named "raid" and it accepts the following parameters:
respect to mirroring. If these options are left unspecified,
or 'raid10_copies 2' and/or 'raid10_format near' are given,
then the layouts for 2, 3 and 4 devices are:
+
+ ======== ========== ==============
2 drives 3 drives 4 drives
- -------- ---------- --------------
+ ======== ========== ==============
A1 A1 A1 A1 A2 A1 A1 A2 A2
A2 A2 A2 A3 A3 A3 A3 A4 A4
A3 A3 A4 A4 A5 A5 A5 A6 A6
A4 A4 A5 A6 A6 A7 A7 A8 A8
.. .. .. .. .. .. .. .. ..
+ ======== ========== ==============
+
The 2-device layout is equivalent 2-way RAID1. The 4-device
layout is what a traditional RAID10 would look like. The
3-device layout is what might be called a 'RAID1E - Integrated
@@ -107,8 +137,10 @@ The target is named "raid" and it accepts the following parameters:
If 'raid10_copies 2' and 'raid10_format far', then the layouts
for 2, 3 and 4 devices are:
+
+ ======== ============ ===================
2 drives 3 drives 4 drives
- -------- -------------- --------------------
+ ======== ============ ===================
A1 A2 A1 A2 A3 A1 A2 A3 A4
A3 A4 A4 A5 A6 A5 A6 A7 A8
A5 A6 A7 A8 A9 A9 A10 A11 A12
@@ -117,11 +149,14 @@ The target is named "raid" and it accepts the following parameters:
A4 A3 A6 A4 A5 A6 A5 A8 A7
A6 A5 A9 A7 A8 A10 A9 A12 A11
.. .. .. .. .. .. .. .. ..
+ ======== ============ ===================
If 'raid10_copies 2' and 'raid10_format offset', then the
layouts for 2, 3 and 4 devices are:
+
+ ======== ========== ================
2 drives 3 drives 4 drives
- -------- ------------ -----------------
+ ======== ========== ================
A1 A2 A1 A2 A3 A1 A2 A3 A4
A2 A1 A3 A1 A2 A2 A1 A4 A3
A3 A4 A4 A5 A6 A5 A6 A7 A8
@@ -129,6 +164,8 @@ The target is named "raid" and it accepts the following parameters:
A5 A6 A7 A8 A9 A9 A10 A11 A12
A6 A5 A9 A7 A8 A10 A9 A12 A11
.. .. .. .. .. .. .. .. ..
+ ======== ========== ================
+
Here we see layouts closely akin to 'RAID1E - Integrated
Offset Stripe Mirroring'.
@@ -190,22 +227,25 @@ The target is named "raid" and it accepts the following parameters:
Example Tables
--------------
-# RAID4 - 4 data drives, 1 parity (no metadata devices)
-# No metadata devices specified to hold superblock/bitmap info
-# Chunk size of 1MiB
-# (Lines separated for easy reading)
-0 1960893648 raid \
- raid4 1 2048 \
- 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81
+::
-# RAID4 - 4 data drives, 1 parity (with metadata devices)
-# Chunk size of 1MiB, force RAID initialization,
-# min recovery rate at 20 kiB/sec/disk
+ # RAID4 - 4 data drives, 1 parity (no metadata devices)
+ # No metadata devices specified to hold superblock/bitmap info
+ # Chunk size of 1MiB
+ # (Lines separated for easy reading)
-0 1960893648 raid \
- raid4 4 2048 sync min_recovery_rate 20 \
- 5 8:17 8:18 8:33 8:34 8:49 8:50 8:65 8:66 8:81 8:82
+ 0 1960893648 raid \
+ raid4 1 2048 \
+ 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81
+
+ # RAID4 - 4 data drives, 1 parity (with metadata devices)
+ # Chunk size of 1MiB, force RAID initialization,
+ # min recovery rate at 20 kiB/sec/disk
+
+ 0 1960893648 raid \
+ raid4 4 2048 sync min_recovery_rate 20 \
+ 5 8:17 8:18 8:33 8:34 8:49 8:50 8:65 8:66 8:81 8:82
Status Output
@@ -219,41 +259,58 @@ Arguments that can be repeated are ordered by value.
'dmsetup status' yields information on the state and health of the array.
The output is as follows (normally a single line, but expanded here for
-clarity):
-1: <s> <l> raid \
-2: <raid_type> <#devices> <health_chars> \
-3: <sync_ratio> <sync_action> <mismatch_cnt>
+clarity)::
+
+ 1: <s> <l> raid \
+ 2: <raid_type> <#devices> <health_chars> \
+ 3: <sync_ratio> <sync_action> <mismatch_cnt>
Line 1 is the standard output produced by device-mapper.
-Line 2 & 3 are produced by the raid target and are best explained by example:
+
+Line 2 & 3 are produced by the raid target and are best explained by example::
+
0 1960893648 raid raid4 5 AAAAA 2/490221568 init 0
+
Here we can see the RAID type is raid4, there are 5 devices - all of
which are 'A'live, and the array is 2/490221568 complete with its initial
recovery. Here is a fuller description of the individual fields:
+
+ =============== =========================================================
<raid_type> Same as the <raid_type> used to create the array.
- <health_chars> One char for each device, indicating: 'A' = alive and
- in-sync, 'a' = alive but not in-sync, 'D' = dead/failed.
+ <health_chars> One char for each device, indicating:
+
+ - 'A' = alive and in-sync
+ - 'a' = alive but not in-sync
+ - 'D' = dead/failed.
<sync_ratio> The ratio indicating how much of the array has undergone
the process described by 'sync_action'. If the
'sync_action' is "check" or "repair", then the process
of "resync" or "recover" can be considered complete.
<sync_action> One of the following possible states:
- idle - No synchronization action is being performed.
- frozen - The current action has been halted.
- resync - Array is undergoing its initial synchronization
+
+ idle
+ - No synchronization action is being performed.
+ frozen
+ - The current action has been halted.
+ resync
+ - Array is undergoing its initial synchronization
or is resynchronizing after an unclean shutdown
(possibly aided by a bitmap).
- recover - A device in the array is being rebuilt or
+ recover
+ - A device in the array is being rebuilt or
replaced.
- check - A user-initiated full check of the array is
+ check
+ - A user-initiated full check of the array is
being performed. All blocks are read and
checked for consistency. The number of
discrepancies found are recorded in
<mismatch_cnt>. No changes are made to the
array by this action.
- repair - The same as "check", but discrepancies are
+ repair
+ - The same as "check", but discrepancies are
corrected.
- reshape - The array is undergoing a reshape.
+ reshape
+ - The array is undergoing a reshape.
<mismatch_cnt> The number of discrepancies found between mirror copies
in RAID1/10 or wrong parity values found in RAID4/5/6.
This value is valid only after a "check" of the array
@@ -261,10 +318,11 @@ recovery. Here is a fuller description of the individual fields:
<data_offset> The current data offset to the start of the user data on
each component device of a raid set (see the respective
raid parameter to support out-of-place reshaping).
- <journal_char> 'A' - active write-through journal device.
- 'a' - active write-back journal device.
- 'D' - dead journal device.
- '-' - no journal device.
+ <journal_char> - 'A' - active write-through journal device.
+ - 'a' - active write-back journal device.
+ - 'D' - dead journal device.
+ - '-' - no journal device.
+ =============== =========================================================
Message Interface
@@ -272,12 +330,15 @@ Message Interface
The dm-raid target will accept certain actions through the 'message' interface.
('man dmsetup' for more information on the message interface.) These actions
include:
- "idle" - Halt the current sync action.
- "frozen" - Freeze the current sync action.
- "resync" - Initiate/continue a resync.
- "recover"- Initiate/continue a recover process.
- "check" - Initiate a check (i.e. a "scrub") of the array.
- "repair" - Initiate a repair of the array.
+
+ ========= ================================================
+ "idle" Halt the current sync action.
+ "frozen" Freeze the current sync action.
+ "resync" Initiate/continue a resync.
+ "recover" Initiate/continue a recover process.
+ "check" Initiate a check (i.e. a "scrub") of the array.
+ "repair" Initiate a repair of the array.
+ ========= ================================================
Discard Support
@@ -307,48 +368,52 @@ increasingly whitelisted in the kernel and can thus be trusted.
For trusted devices, the following dm-raid module parameter can be set
to safely enable discard support for RAID 4/5/6:
+
'devices_handle_discards_safely'
Version History
---------------
-1.0.0 Initial version. Support for RAID 4/5/6
-1.1.0 Added support for RAID 1
-1.2.0 Handle creation of arrays that contain failed devices.
-1.3.0 Added support for RAID 10
-1.3.1 Allow device replacement/rebuild for RAID 10
-1.3.2 Fix/improve redundancy checking for RAID10
-1.4.0 Non-functional change. Removes arg from mapping function.
-1.4.1 RAID10 fix redundancy validation checks (commit 55ebbb5).
-1.4.2 Add RAID10 "far" and "offset" algorithm support.
-1.5.0 Add message interface to allow manipulation of the sync_action.
+
+::
+
+ 1.0.0 Initial version. Support for RAID 4/5/6
+ 1.1.0 Added support for RAID 1
+ 1.2.0 Handle creation of arrays that contain failed devices.
+ 1.3.0 Added support for RAID 10
+ 1.3.1 Allow device replacement/rebuild for RAID 10
+ 1.3.2 Fix/improve redundancy checking for RAID10
+ 1.4.0 Non-functional change. Removes arg from mapping function.
+ 1.4.1 RAID10 fix redundancy validation checks (commit 55ebbb5).
+ 1.4.2 Add RAID10 "far" and "offset" algorithm support.
+ 1.5.0 Add message interface to allow manipulation of the sync_action.
New status (STATUSTYPE_INFO) fields: sync_action and mismatch_cnt.
-1.5.1 Add ability to restore transiently failed devices on resume.
-1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check".
-1.6.0 Add discard support (and devices_handle_discard_safely module param).
-1.7.0 Add support for MD RAID0 mappings.
-1.8.0 Explicitly check for compatible flags in the superblock metadata
+ 1.5.1 Add ability to restore transiently failed devices on resume.
+ 1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check".
+ 1.6.0 Add discard support (and devices_handle_discard_safely module param).
+ 1.7.0 Add support for MD RAID0 mappings.
+ 1.8.0 Explicitly check for compatible flags in the superblock metadata
and reject to start the raid set if any are set by a newer
target version, thus avoiding data corruption on a raid set
with a reshape in progress.
-1.9.0 Add support for RAID level takeover/reshape/region size
+ 1.9.0 Add support for RAID level takeover/reshape/region size
and set size reduction.
-1.9.1 Fix activation of existing RAID 4/10 mapped devices
-1.9.2 Don't emit '- -' on the status table line in case the constructor
+ 1.9.1 Fix activation of existing RAID 4/10 mapped devices
+ 1.9.2 Don't emit '- -' on the status table line in case the constructor
fails reading a superblock. Correctly emit 'maj:min1 maj:min2' and
'D' on the status line. If '- -' is passed into the constructor, emit
'- -' on the table line and '-' as the status line health character.
-1.10.0 Add support for raid4/5/6 journal device
-1.10.1 Fix data corruption on reshape request
-1.11.0 Fix table line argument order
+ 1.10.0 Add support for raid4/5/6 journal device
+ 1.10.1 Fix data corruption on reshape request
+ 1.11.0 Fix table line argument order
(wrong raid10_copies/raid10_format sequence)
-1.11.1 Add raid4/5/6 journal write-back support via journal_mode option
-1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available
-1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A')
-1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an
+ 1.11.1 Add raid4/5/6 journal write-back support via journal_mode option
+ 1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available
+ 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A')
+ 1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an
state races.
-1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen
-1.14.0 Fix reshape race on small devices. Fix stripe adding reshape
+ 1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen
+ 1.14.0 Fix reshape race on small devices. Fix stripe adding reshape
deadlock/potential data corruption. Update superblock when
specific devices are requested via rebuild. Fix RAID leg
rebuild errors.
diff --git a/Documentation/device-mapper/dm-service-time.txt b/Documentation/device-mapper/dm-service-time.rst
similarity index 60%
rename from Documentation/device-mapper/dm-service-time.txt
rename to Documentation/device-mapper/dm-service-time.rst
index fb1d4a0cf122..facf277fc13c 100644
--- a/Documentation/device-mapper/dm-service-time.txt
+++ b/Documentation/device-mapper/dm-service-time.rst
@@ -1,3 +1,4 @@
+===============
dm-service-time
===============
@@ -12,25 +13,34 @@ in a path-group, and it can be specified as a table argument.
The path selector name is 'service-time'.
-Table parameters for each path: [<repeat_count> [<relative_throughput>]]
- <repeat_count>: The number of I/Os to dispatch using the selected
+Table parameters for each path:
+
+ [<repeat_count> [<relative_throughput>]]
+ <repeat_count>:
+ The number of I/Os to dispatch using the selected
path before switching to the next path.
If not given, internal default is used. To check
the default value, see the activated table.
- <relative_throughput>: The relative throughput value of the path
+ <relative_throughput>:
+ The relative throughput value of the path
among all paths in the path-group.
The valid range is 0-100.
If not given, minimum value '1' is used.
If '0' is given, the path isn't selected while
other paths having a positive value are available.
-Status for each path: <status> <fail-count> <in-flight-size> \
- <relative_throughput>
- <status>: 'A' if the path is active, 'F' if the path is failed.
- <fail-count>: The number of path failures.
- <in-flight-size>: The size of in-flight I/Os on the path.
- <relative_throughput>: The relative throughput value of the path
- among all paths in the path-group.
+Status for each path:
+
+ <status> <fail-count> <in-flight-size> <relative_throughput>
+ <status>:
+ 'A' if the path is active, 'F' if the path is failed.
+ <fail-count>:
+ The number of path failures.
+ <in-flight-size>:
+ The size of in-flight I/Os on the path.
+ <relative_throughput>:
+ The relative throughput value of the path
+ among all paths in the path-group.
Algorithm
@@ -39,7 +49,7 @@ Algorithm
dm-service-time adds the I/O size to 'in-flight-size' when the I/O is
dispatched and subtracts when completed.
Basically, dm-service-time selects a path having minimum service time
-which is calculated by:
+which is calculated by::
('in-flight-size' + 'size-of-incoming-io') / 'relative_throughput'
@@ -67,25 +77,25 @@ Examples
========
In case that 2 paths (sda and sdb) are used with repeat_count == 128
and sda has an average throughput 1GB/s and sdb has 4GB/s,
-'relative_throughput' value may be '1' for sda and '4' for sdb.
+'relative_throughput' value may be '1' for sda and '4' for sdb::
-# echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4" \
- dmsetup create test
-#
-# dmsetup table
-test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4
-#
-# dmsetup status
-test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 1 8:16 A 0 0 4
+ # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4" \
+ dmsetup create test
+ #
+ # dmsetup table
+ test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4
+ #
+ # dmsetup status
+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 1 8:16 A 0 0 4
-Or '2' for sda and '8' for sdb would be also true.
+Or '2' for sda and '8' for sdb would be also true::
-# echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8" \
- dmsetup create test
-#
-# dmsetup table
-test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8
-#
-# dmsetup status
-test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 2 8:16 A 0 0 8
+ # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8" \
+ dmsetup create test
+ #
+ # dmsetup table
+ test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8
+ #
+ # dmsetup status
+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 2 8:16 A 0 0 8
diff --git a/Documentation/device-mapper/dm-uevent.txt b/Documentation/device-mapper/dm-uevent.rst
similarity index 31%
rename from Documentation/device-mapper/dm-uevent.txt
rename to Documentation/device-mapper/dm-uevent.rst
index 07edbd85c714..4a8ee8d069c9 100644
--- a/Documentation/device-mapper/dm-uevent.txt
+++ b/Documentation/device-mapper/dm-uevent.rst
@@ -1,3 +1,7 @@
+====================
+device-mapper uevent
+====================
+
The device-mapper uevent code adds the capability to device-mapper to create
and send kobject uevents (uevents). Previously device-mapper events were only
available through the ioctl interface. The advantage of the uevents interface
@@ -6,92 +10,101 @@ the event avoiding the need to query the state of the device-mapper device after
the event is received.
There are two functions currently for device-mapper events. The first function
-listed creates the event and the second function sends the event(s).
+listed creates the event and the second function sends the event(s)::
-void dm_path_uevent(enum dm_uevent_type event_type, struct dm_target *ti,
- const char *path, unsigned nr_valid_paths)
+ void dm_path_uevent(enum dm_uevent_type event_type, struct dm_target *ti,
+ const char *path, unsigned nr_valid_paths)
-void dm_send_uevents(struct list_head *events, struct kobject *kobj)
+ void dm_send_uevents(struct list_head *events, struct kobject *kobj)
The variables added to the uevent environment are:
Variable Name: DM_TARGET
-Uevent Action(s): KOBJ_CHANGE
-Type: string
-Description:
-Value: Name of device-mapper target that generated the event.
+------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description:
+:Value: Name of device-mapper target that generated the event.
Variable Name: DM_ACTION
-Uevent Action(s): KOBJ_CHANGE
-Type: string
-Description:
-Value: Device-mapper specific action that caused the uevent action.
- PATH_FAILED - A path has failed.
+------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description:
+:Value: Device-mapper specific action that caused the uevent action.
+ PATH_FAILED - A path has failed;
PATH_REINSTATED - A path has been reinstated.
Variable Name: DM_SEQNUM
-Uevent Action(s): KOBJ_CHANGE
-Type: unsigned integer
-Description: A sequence number for this specific device-mapper device.
-Value: Valid unsigned integer range.
+------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: unsigned integer
+:Description: A sequence number for this specific device-mapper device.
+:Value: Valid unsigned integer range.
Variable Name: DM_PATH
-Uevent Action(s): KOBJ_CHANGE
-Type: string
-Description: Major and minor number of the path device pertaining to this
-event.
-Value: Path name in the form of "Major:Minor"
+----------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description: Major and minor number of the path device pertaining to this
+ event.
+:Value: Path name in the form of "Major:Minor"
Variable Name: DM_NR_VALID_PATHS
-Uevent Action(s): KOBJ_CHANGE
-Type: unsigned integer
-Description:
-Value: Valid unsigned integer range.
+--------------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: unsigned integer
+:Description:
+:Value: Valid unsigned integer range.
Variable Name: DM_NAME
-Uevent Action(s): KOBJ_CHANGE
-Type: string
-Description: Name of the device-mapper device.
-Value: Name
+----------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description: Name of the device-mapper device.
+:Value: Name
Variable Name: DM_UUID
-Uevent Action(s): KOBJ_CHANGE
-Type: string
-Description: UUID of the device-mapper device.
-Value: UUID. (Empty string if there isn't one.)
+----------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description: UUID of the device-mapper device.
+:Value: UUID. (Empty string if there isn't one.)
An example of the uevents generated as captured by udevmonitor is shown
-below.
+below
-1.) Path failure.
-UEVENT[1192521009.711215] change@/block/dm-3
-ACTION=change
-DEVPATH=/block/dm-3
-SUBSYSTEM=block
-DM_TARGET=multipath
-DM_ACTION=PATH_FAILED
-DM_SEQNUM=1
-DM_PATH=8:32
-DM_NR_VALID_PATHS=0
-DM_NAME=mpath2
-DM_UUID=mpath-35333333000002328
-MINOR=3
-MAJOR=253
-SEQNUM=1130
+1.) Path failure::
-2.) Path reinstate.
-UEVENT[1192521132.989927] change@/block/dm-3
-ACTION=change
-DEVPATH=/block/dm-3
-SUBSYSTEM=block
-DM_TARGET=multipath
-DM_ACTION=PATH_REINSTATED
-DM_SEQNUM=2
-DM_PATH=8:32
-DM_NR_VALID_PATHS=1
-DM_NAME=mpath2
-DM_UUID=mpath-35333333000002328
-MINOR=3
-MAJOR=253
-SEQNUM=1131
+ UEVENT[1192521009.711215] change@/block/dm-3
+ ACTION=change
+ DEVPATH=/block/dm-3
+ SUBSYSTEM=block
+ DM_TARGET=multipath
+ DM_ACTION=PATH_FAILED
+ DM_SEQNUM=1
+ DM_PATH=8:32
+ DM_NR_VALID_PATHS=0
+ DM_NAME=mpath2
+ DM_UUID=mpath-35333333000002328
+ MINOR=3
+ MAJOR=253
+ SEQNUM=1130
+
+2.) Path reinstate::
+
+ UEVENT[1192521132.989927] change@/block/dm-3
+ ACTION=change
+ DEVPATH=/block/dm-3
+ SUBSYSTEM=block
+ DM_TARGET=multipath
+ DM_ACTION=PATH_REINSTATED
+ DM_SEQNUM=2
+ DM_PATH=8:32
+ DM_NR_VALID_PATHS=1
+ DM_NAME=mpath2
+ DM_UUID=mpath-35333333000002328
+ MINOR=3
+ MAJOR=253
+ SEQNUM=1131
diff --git a/Documentation/device-mapper/dm-zoned.txt b/Documentation/device-mapper/dm-zoned.rst
similarity index 97%
rename from Documentation/device-mapper/dm-zoned.txt
rename to Documentation/device-mapper/dm-zoned.rst
index 736fcc78d193..07f56ebc1730 100644
--- a/Documentation/device-mapper/dm-zoned.txt
+++ b/Documentation/device-mapper/dm-zoned.rst
@@ -1,3 +1,4 @@
+========
dm-zoned
========
@@ -133,12 +134,13 @@ A zoned block device must first be formatted using the dmzadm tool. This
will analyze the device zone configuration, determine where to place the
metadata sets on the device and initialize the metadata sets.
-Ex:
+Ex::
-dmzadm --format /dev/sdxx
+ dmzadm --format /dev/sdxx
For a formatted device, the target can be created normally with the
dmsetup utility. The only parameter that dm-zoned requires is the
-underlying zoned block device name. Ex:
+underlying zoned block device name. Ex::
-echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | dmsetup create dmz-`basename ${dev}`
+ echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | \
+ dmsetup create dmz-`basename ${dev}`
diff --git a/Documentation/device-mapper/era.txt b/Documentation/device-mapper/era.rst
similarity index 70%
rename from Documentation/device-mapper/era.txt
rename to Documentation/device-mapper/era.rst
index 3c6d01be3560..90dd5c670b9f 100644
--- a/Documentation/device-mapper/era.txt
+++ b/Documentation/device-mapper/era.rst
@@ -1,3 +1,7 @@
+======
+dm-era
+======
+
Introduction
============
@@ -14,12 +18,14 @@ coherency after rolling back a vendor snapshot.
Constructor
===========
- era <metadata dev> <origin dev> <block size>
+era <metadata dev> <origin dev> <block size>
- metadata dev : fast device holding the persistent metadata
- origin dev : device holding data blocks that may change
- block size : block size of origin data device, granularity that is
- tracked by the target
+ ================ ======================================================
+ metadata dev fast device holding the persistent metadata
+ origin dev device holding data blocks that may change
+ block size block size of origin data device, granularity that is
+ tracked by the target
+ ================ ======================================================
Messages
========
@@ -49,14 +55,16 @@ Status
<metadata block size> <#used metadata blocks>/<#total metadata blocks>
<current era> <held metadata root | '-'>
-metadata block size : Fixed block size for each metadata block in
- sectors
-#used metadata blocks : Number of metadata blocks used
-#total metadata blocks : Total number of metadata blocks
-current era : The current era
-held metadata root : The location, in blocks, of the metadata root
- that has been 'held' for userspace read
- access. '-' indicates there is no held root
+========================= ==============================================
+metadata block size Fixed block size for each metadata block in
+ sectors
+#used metadata blocks Number of metadata blocks used
+#total metadata blocks Total number of metadata blocks
+current era The current era
+held metadata root The location, in blocks, of the metadata root
+ that has been 'held' for userspace read
+ access. '-' indicates there is no held root
+========================= ==============================================
Detailed use case
=================
@@ -88,7 +96,7 @@ Memory usage
The target uses a bitset to record writes in the current era. It also
has a spare bitset ready for switching over to a new era. Other than
-that it uses a few 4k blocks for updating metadata.
+that it uses a few 4k blocks for updating metadata::
(4 * nr_blocks) bytes + buffers
diff --git a/Documentation/device-mapper/index.rst b/Documentation/device-mapper/index.rst
new file mode 100644
index 000000000000..105e253bc231
--- /dev/null
+++ b/Documentation/device-mapper/index.rst
@@ -0,0 +1,44 @@
+:orphan:
+
+=============
+Device Mapper
+=============
+
+.. toctree::
+ :maxdepth: 1
+
+ cache-policies
+ cache
+ delay
+ dm-crypt
+ dm-flakey
+ dm-init
+ dm-integrity
+ dm-io
+ dm-log
+ dm-queue-length
+ dm-raid
+ dm-service-time
+ dm-uevent
+ dm-zoned
+ era
+ kcopyd
+ linear
+ log-writes
+ persistent-data
+ snapshot
+ statistics
+ striped
+ switch
+ thin-provisioning
+ unstriped
+ verity
+ writecache
+ zero
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/device-mapper/kcopyd.txt b/Documentation/device-mapper/kcopyd.rst
similarity index 93%
rename from Documentation/device-mapper/kcopyd.txt
rename to Documentation/device-mapper/kcopyd.rst
index 820382c4cecf..7651d395127f 100644
--- a/Documentation/device-mapper/kcopyd.txt
+++ b/Documentation/device-mapper/kcopyd.rst
@@ -1,3 +1,4 @@
+======
kcopyd
======
@@ -7,7 +8,7 @@ notification. It is used by dm-snapshot and dm-mirror.
Users of kcopyd must first create a client and indicate how many memory pages
to set aside for their copy jobs. This is done with a call to
-kcopyd_client_create().
+kcopyd_client_create()::
int kcopyd_client_create(unsigned int num_pages,
struct kcopyd_client **result);
@@ -16,7 +17,7 @@ To start a copy job, the user must set up io_region structures to describe
the source and destinations of the copy. Each io_region indicates a
block-device along with the starting sector and size of the region. The source
of the copy is given as one io_region structure, and the destinations of the
-copy are given as an array of io_region structures.
+copy are given as an array of io_region structures::
struct io_region {
struct block_device *bdev;
@@ -26,7 +27,7 @@ copy are given as an array of io_region structures.
To start the copy, the user calls kcopyd_copy(), passing in the client
pointer, pointers to the source and destination io_regions, the name of a
-completion callback routine, and a pointer to some context data for the copy.
+completion callback routine, and a pointer to some context data for the copy::
int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
unsigned int num_dests, struct io_region *dests,
@@ -41,7 +42,6 @@ write error occurred during the copy.
When a user is done with all their copy jobs, they should call
kcopyd_client_destroy() to delete the kcopyd client, which will release the
-associated memory pages.
+associated memory pages::
void kcopyd_client_destroy(struct kcopyd_client *kc);
-
diff --git a/Documentation/device-mapper/linear.txt b/Documentation/device-mapper/linear.rst
similarity index 18%
rename from Documentation/device-mapper/linear.txt
rename to Documentation/device-mapper/linear.rst
index 7cb98d89d3f8..9d17fc6e64a9 100644
--- a/Documentation/device-mapper/linear.txt
+++ b/Documentation/device-mapper/linear.rst
@@ -1,3 +1,4 @@
+=========
dm-linear
=========
@@ -6,56 +7,57 @@ device onto a linear range of another device. This is the basic building
block of logical volume managers.
Parameters: <dev path> <offset>
- <dev path>: Full pathname to the underlying block-device, or a
- "major:minor" device-number.
- <offset>: Starting sector within the device.
+ <dev path>:
+ Full pathname to the underlying block-device, or a
+ "major:minor" device-number.
+ <offset>:
+ Starting sector within the device.
Example scripts
===============
-[[
-#!/bin/sh
-# Create an identity mapping for a device
-echo "0 `blockdev --getsz $1` linear $1 0" | dmsetup create identity
-]]
-
-
-[[
-#!/bin/sh
-# Join 2 devices together
-size1=`blockdev --getsz $1`
-size2=`blockdev --getsz $2`
-echo "0 $size1 linear $1 0
-$size1 $size2 linear $2 0" | dmsetup create joined
-]]
-
-
-[[
-#!/usr/bin/perl -w
-# Split a device into 4M chunks and then join them together in reverse order.
-
-my $name = "reverse";
-my $extent_size = 4 * 1024 * 2;
-my $dev = $ARGV[0];
-my $table = "";
-my $count = 0;
-
-if (!defined($dev)) {
- die("Please specify a device.\n");
-}
-
-my $dev_size = `blockdev --getsz $dev`;
-my $extents = int($dev_size / $extent_size) -
- (($dev_size % $extent_size) ? 1 : 0);
-
-while ($extents > 0) {
- my $this_start = $count * $extent_size;
- $extents--;
- $count++;
- my $this_offset = $extents * $extent_size;
-
- $table .= "$this_start $extent_size linear $dev $this_offset\n";
-}
-
-`echo \"$table\" | dmsetup create $name`;
-]]
+
+::
+
+ #!/bin/sh
+ # Create an identity mapping for a device
+ echo "0 `blockdev --getsz $1` linear $1 0" | dmsetup create identity
+
+::
+
+ #!/bin/sh
+ # Join 2 devices together
+ size1=`blockdev --getsz $1`
+ size2=`blockdev --getsz $2`
+ echo "0 $size1 linear $1 0
+ $size1 $size2 linear $2 0" | dmsetup create joined
+
+::
+
+ #!/usr/bin/perl -w
+ # Split a device into 4M chunks and then join them together in reverse order.
+
+ my $name = "reverse";
+ my $extent_size = 4 * 1024 * 2;
+ my $dev = $ARGV[0];
+ my $table = "";
+ my $count = 0;
+
+ if (!defined($dev)) {
+ die("Please specify a device.\n");
+ }
+
+ my $dev_size = `blockdev --getsz $dev`;
+ my $extents = int($dev_size / $extent_size) -
+ (($dev_size % $extent_size) ? 1 : 0);
+
+ while ($extents > 0) {
+ my $this_start = $count * $extent_size;
+ $extents--;
+ $count++;
+ my $this_offset = $extents * $extent_size;
+
+ $table .= "$this_start $extent_size linear $dev $this_offset\n";
+ }
+
+ `echo \"$table\" | dmsetup create $name`;
diff --git a/Documentation/device-mapper/log-writes.txt b/Documentation/device-mapper/log-writes.rst
similarity index 61%
rename from Documentation/device-mapper/log-writes.txt
rename to Documentation/device-mapper/log-writes.rst
index b638d124be6a..23141f2ffb7c 100644
--- a/Documentation/device-mapper/log-writes.txt
+++ b/Documentation/device-mapper/log-writes.rst
@@ -1,3 +1,4 @@
+=============
dm-log-writes
=============
@@ -25,11 +26,11 @@ completed WRITEs, at the time the REQ_PREFLUSH is issued, are added in order to
simulate the worst case scenario with regard to power failures. Consider the
following example (W means write, C means complete):
-W1,W2,W3,C3,C2,Wflush,C1,Cflush
+ W1,W2,W3,C3,C2,Wflush,C1,Cflush
-The log would show the following
+The log would show the following:
-W3,W2,flush,W1....
+ W3,W2,flush,W1....
Again this is to simulate what is actually on disk, this allows us to detect
cases where a power failure at a particular point in time would create an
@@ -42,11 +43,11 @@ Any REQ_OP_DISCARD requests are treated like WRITE requests. Otherwise we would
have all the DISCARD requests, and then the WRITE requests and then the FLUSH
request. Consider the following example:
-WRITE block 1, DISCARD block 1, FLUSH
+ WRITE block 1, DISCARD block 1, FLUSH
-If we logged DISCARD when it completed, the replay would look like this
+If we logged DISCARD when it completed, the replay would look like this:
-DISCARD 1, WRITE 1, FLUSH
+ DISCARD 1, WRITE 1, FLUSH
which isn't quite what happened and wouldn't be caught during the log replay.
@@ -57,15 +58,19 @@ i) Constructor
log-writes <dev_path> <log_dev_path>
- dev_path : Device that all of the IO will go to normally.
- log_dev_path : Device where the log entries are written to.
+ ============= ==============================================
+ dev_path Device that all of the IO will go to normally.
+ log_dev_path Device where the log entries are written to.
+ ============= ==============================================
ii) Status
<#logged entries> <highest allocated sector>
- #logged entries : Number of logged entries
- highest allocated sector : Highest allocated sector
+ =========================== ========================
+ #logged entries Number of logged entries
+ highest allocated sector Highest allocated sector
+ =========================== ========================
iii) Messages
@@ -75,15 +80,15 @@ iii) Messages
For example say you want to fsck a file system after every
write, but first you need to replay up to the mkfs to make sure
we're fsck'ing something reasonable, you would do something like
- this:
+ this::
mkfs.btrfs -f /dev/mapper/log
dmsetup message log 0 mark mkfs
<run test>
- This would allow you to replay the log up to the mkfs mark and
- then replay from that point on doing the fsck check in the
- interval that you want.
+ This would allow you to replay the log up to the mkfs mark and
+ then replay from that point on doing the fsck check in the
+ interval that you want.
Every log has a mark at the end labeled "dm-log-writes-end".
@@ -97,42 +102,42 @@ Example usage
=============
Say you want to test fsync on your file system. You would do something like
-this:
+this::
-TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
-dmsetup create log --table "$TABLE"
-mkfs.btrfs -f /dev/mapper/log
-dmsetup message log 0 mark mkfs
+ TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
+ dmsetup create log --table "$TABLE"
+ mkfs.btrfs -f /dev/mapper/log
+ dmsetup message log 0 mark mkfs
-mount /dev/mapper/log /mnt/btrfs-test
-<some test that does fsync at the end>
-dmsetup message log 0 mark fsync
-md5sum /mnt/btrfs-test/foo
-umount /mnt/btrfs-test
+ mount /dev/mapper/log /mnt/btrfs-test
+ <some test that does fsync at the end>
+ dmsetup message log 0 mark fsync
+ md5sum /mnt/btrfs-test/foo
+ umount /mnt/btrfs-test
-dmsetup remove log
-replay-log --log /dev/sdc --replay /dev/sdb --end-mark fsync
-mount /dev/sdb /mnt/btrfs-test
-md5sum /mnt/btrfs-test/foo
-<verify md5sum's are correct>
+ dmsetup remove log
+ replay-log --log /dev/sdc --replay /dev/sdb --end-mark fsync
+ mount /dev/sdb /mnt/btrfs-test
+ md5sum /mnt/btrfs-test/foo
+ <verify md5sum's are correct>
-Another option is to do a complicated file system operation and verify the file
-system is consistent during the entire operation. You could do this with:
+ Another option is to do a complicated file system operation and verify the file
+ system is consistent during the entire operation. You could do this with:
-TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
-dmsetup create log --table "$TABLE"
-mkfs.btrfs -f /dev/mapper/log
-dmsetup message log 0 mark mkfs
+ TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
+ dmsetup create log --table "$TABLE"
+ mkfs.btrfs -f /dev/mapper/log
+ dmsetup message log 0 mark mkfs
-mount /dev/mapper/log /mnt/btrfs-test
-<fsstress to dirty the fs>
-btrfs filesystem balance /mnt/btrfs-test
-umount /mnt/btrfs-test
-dmsetup remove log
+ mount /dev/mapper/log /mnt/btrfs-test
+ <fsstress to dirty the fs>
+ btrfs filesystem balance /mnt/btrfs-test
+ umount /mnt/btrfs-test
+ dmsetup remove log
-replay-log --log /dev/sdc --replay /dev/sdb --end-mark mkfs
-btrfsck /dev/sdb
-replay-log --log /dev/sdc --replay /dev/sdb --start-mark mkfs \
+ replay-log --log /dev/sdc --replay /dev/sdb --end-mark mkfs
+ btrfsck /dev/sdb
+ replay-log --log /dev/sdc --replay /dev/sdb --start-mark mkfs \
--fsck "btrfsck /dev/sdb" --check fua
And that will replay the log until it sees a FUA request, run the fsck command
diff --git a/Documentation/device-mapper/persistent-data.txt b/Documentation/device-mapper/persistent-data.rst
similarity index 98%
rename from Documentation/device-mapper/persistent-data.txt
rename to Documentation/device-mapper/persistent-data.rst
index a333bcb3a6c2..2065c3c5a091 100644
--- a/Documentation/device-mapper/persistent-data.txt
+++ b/Documentation/device-mapper/persistent-data.rst
@@ -1,3 +1,7 @@
+===============
+Persistent data
+===============
+
Introduction
============
diff --git a/Documentation/device-mapper/snapshot.txt b/Documentation/device-mapper/snapshot.rst
similarity index 62%
rename from Documentation/device-mapper/snapshot.txt
rename to Documentation/device-mapper/snapshot.rst
index b8bbb516f989..4c53304e72f1 100644
--- a/Documentation/device-mapper/snapshot.txt
+++ b/Documentation/device-mapper/snapshot.rst
@@ -1,15 +1,16 @@
+==============================
Device-mapper snapshot support
==============================
Device-mapper allows you, without massive data copying:
-*) To create snapshots of any block device i.e. mountable, saved states of
-the block device which are also writable without interfering with the
-original content;
-*) To create device "forks", i.e. multiple different versions of the
-same data stream.
-*) To merge a snapshot of a block device back into the snapshot's origin
-device.
+- To create snapshots of any block device i.e. mountable, saved states of
+ the block device which are also writable without interfering with the
+ original content;
+- To create device "forks", i.e. multiple different versions of the
+ same data stream.
+- To merge a snapshot of a block device back into the snapshot's origin
+ device.
In the first two cases, dm copies only the chunks of data that get
changed and uses a separate copy-on-write (COW) block device for
@@ -22,7 +23,7 @@ the origin device.
There are three dm targets available:
snapshot, snapshot-origin, and snapshot-merge.
-*) snapshot-origin <origin>
+- snapshot-origin <origin>
which will normally have one or more snapshots based on it.
Reads will be mapped directly to the backing device. For each write, the
@@ -30,7 +31,7 @@ original data will be saved in the <COW device> of each snapshot to keep
its visible content unchanged, at least until the <COW device> fills up.
-*) snapshot <origin> <COW device> <persistent?> <chunksize>
+- snapshot <origin> <COW device> <persistent?> <chunksize>
A snapshot of the <origin> block device is created. Changed chunks of
<chunksize> sectors will be stored on the <COW device>. Writes will
@@ -83,25 +84,25 @@ When you create the first LVM2 snapshot of a volume, four dm devices are used:
source volume), whose table is replaced by a "snapshot-origin" mapping
from device #1.
-A fixed naming scheme is used, so with the following commands:
+A fixed naming scheme is used, so with the following commands::
-lvcreate -L 1G -n base volumeGroup
-lvcreate -L 100M --snapshot -n snap volumeGroup/base
+ lvcreate -L 1G -n base volumeGroup
+ lvcreate -L 100M --snapshot -n snap volumeGroup/base
-we'll have this situation (with volumes in above order):
+we'll have this situation (with volumes in above order)::
-# dmsetup table|grep volumeGroup
+ # dmsetup table|grep volumeGroup
-volumeGroup-base-real: 0 2097152 linear 8:19 384
-volumeGroup-snap-cow: 0 204800 linear 8:19 2097536
-volumeGroup-snap: 0 2097152 snapshot 254:11 254:12 P 16
-volumeGroup-base: 0 2097152 snapshot-origin 254:11
+ volumeGroup-base-real: 0 2097152 linear 8:19 384
+ volumeGroup-snap-cow: 0 204800 linear 8:19 2097536
+ volumeGroup-snap: 0 2097152 snapshot 254:11 254:12 P 16
+ volumeGroup-base: 0 2097152 snapshot-origin 254:11
-# ls -lL /dev/mapper/volumeGroup-*
-brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
-brw------- 1 root root 254, 12 29 ago 18:15 /dev/mapper/volumeGroup-snap-cow
-brw------- 1 root root 254, 13 29 ago 18:15 /dev/mapper/volumeGroup-snap
-brw------- 1 root root 254, 10 29 ago 18:14 /dev/mapper/volumeGroup-base
+ # ls -lL /dev/mapper/volumeGroup-*
+ brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
+ brw------- 1 root root 254, 12 29 ago 18:15 /dev/mapper/volumeGroup-snap-cow
+ brw------- 1 root root 254, 13 29 ago 18:15 /dev/mapper/volumeGroup-snap
+ brw------- 1 root root 254, 10 29 ago 18:14 /dev/mapper/volumeGroup-base
How snapshot-merge is used by LVM2
@@ -114,27 +115,28 @@ merging snapshot after it completes. The "snapshot" that hands over its
COW device to the "snapshot-merge" is deactivated (unless using lvchange
--refresh); but if it is left active it will simply return I/O errors.
-A snapshot will merge into its origin with the following command:
+A snapshot will merge into its origin with the following command::
-lvconvert --merge volumeGroup/snap
+ lvconvert --merge volumeGroup/snap
-we'll now have this situation:
+we'll now have this situation::
-# dmsetup table|grep volumeGroup
+ # dmsetup table|grep volumeGroup
-volumeGroup-base-real: 0 2097152 linear 8:19 384
-volumeGroup-base-cow: 0 204800 linear 8:19 2097536
-volumeGroup-base: 0 2097152 snapshot-merge 254:11 254:12 P 16
+ volumeGroup-base-real: 0 2097152 linear 8:19 384
+ volumeGroup-base-cow: 0 204800 linear 8:19 2097536
+ volumeGroup-base: 0 2097152 snapshot-merge 254:11 254:12 P 16
-# ls -lL /dev/mapper/volumeGroup-*
-brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
-brw------- 1 root root 254, 12 29 ago 18:16 /dev/mapper/volumeGroup-base-cow
-brw------- 1 root root 254, 10 29 ago 18:16 /dev/mapper/volumeGroup-base
+ # ls -lL /dev/mapper/volumeGroup-*
+ brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
+ brw------- 1 root root 254, 12 29 ago 18:16 /dev/mapper/volumeGroup-base-cow
+ brw------- 1 root root 254, 10 29 ago 18:16 /dev/mapper/volumeGroup-base
How to determine when a merging is complete
===========================================
The snapshot-merge and snapshot status lines end with:
+
<sectors_allocated>/<total_sectors> <metadata_sectors>
Both <sectors_allocated> and <total_sectors> include both data and metadata.
@@ -142,35 +144,37 @@ During merging, the number of sectors allocated gets smaller and
smaller. Merging has finished when the number of sectors holding data
is zero, in other words <sectors_allocated> == <metadata_sectors>.
-Here is a practical example (using a hybrid of lvm and dmsetup commands):
+Here is a practical example (using a hybrid of lvm and dmsetup commands)::
-# lvs
- LV VG Attr LSize Origin Snap% Move Log Copy% Convert
- base volumeGroup owi-a- 4.00g
- snap volumeGroup swi-a- 1.00g base 18.97
+ # lvs
+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
+ base volumeGroup owi-a- 4.00g
+ snap volumeGroup swi-a- 1.00g base 18.97
-# dmsetup status volumeGroup-snap
-0 8388608 snapshot 397896/2097152 1560
- ^^^^ metadata sectors
+ # dmsetup status volumeGroup-snap
+ 0 8388608 snapshot 397896/2097152 1560
+ ^^^^ metadata sectors
-# lvconvert --merge -b volumeGroup/snap
- Merging of volume snap started.
+ # lvconvert --merge -b volumeGroup/snap
+ Merging of volume snap started.
-# lvs volumeGroup/snap
- LV VG Attr LSize Origin Snap% Move Log Copy% Convert
- base volumeGroup Owi-a- 4.00g 17.23
+ # lvs volumeGroup/snap
+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
+ base volumeGroup Owi-a- 4.00g 17.23
-# dmsetup status volumeGroup-base
-0 8388608 snapshot-merge 281688/2097152 1104
+ # dmsetup status volumeGroup-base
+ 0 8388608 snapshot-merge 281688/2097152 1104
-# dmsetup status volumeGroup-base
-0 8388608 snapshot-merge 180480/2097152 712
+ # dmsetup status volumeGroup-base
+ 0 8388608 snapshot-merge 180480/2097152 712
-# dmsetup status volumeGroup-base
-0 8388608 snapshot-merge 16/2097152 16
+ # dmsetup status volumeGroup-base
+ 0 8388608 snapshot-merge 16/2097152 16
Merging has finished.
-# lvs
- LV VG Attr LSize Origin Snap% Move Log Copy% Convert
- base volumeGroup owi-a- 4.00g
+::
+
+ # lvs
+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
+ base volumeGroup owi-a- 4.00g
diff --git a/Documentation/device-mapper/statistics.txt b/Documentation/device-mapper/statistics.rst
similarity index 87%
rename from Documentation/device-mapper/statistics.txt
rename to Documentation/device-mapper/statistics.rst
index 170ac02a1f50..3d80a9f850cc 100644
--- a/Documentation/device-mapper/statistics.txt
+++ b/Documentation/device-mapper/statistics.rst
@@ -1,3 +1,4 @@
+=============
DM statistics
=============
@@ -11,7 +12,7 @@ Individual statistics will be collected for each step-sized area within
the range specified.
The I/O statistics counters for each step-sized area of a region are
-in the same format as /sys/block/*/stat or /proc/diskstats (see:
+in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
Documentation/iostats.txt). But two extra counters (12 and 13) are
provided: total time spent reading and writing. When the histogram
argument is used, the 14th parameter is reported that represents the
@@ -32,40 +33,45 @@ on each other's data.
The creation of DM statistics will allocate memory via kmalloc or
fallback to using vmalloc space. At most, 1/4 of the overall system
memory may be allocated by DM statistics. The admin can see how much
-memory is used by reading
-/sys/module/dm_mod/parameters/stats_current_allocated_bytes
+memory is used by reading:
+
+ /sys/module/dm_mod/parameters/stats_current_allocated_bytes
Messages
========
- @stats_create <range> <step>
- [<number_of_optional_arguments> <optional_arguments>...]
- [<program_id> [<aux_data>]]
-
+ @stats_create <range> <step> [<number_of_optional_arguments> <optional_arguments>...] [<program_id> [<aux_data>]]
Create a new region and return the region_id.
<range>
- "-" - whole device
- "<start_sector>+<length>" - a range of <length> 512-byte sectors
- starting with <start_sector>.
+ "-"
+ whole device
+ "<start_sector>+<length>"
+ a range of <length> 512-byte sectors
+ starting with <start_sector>.
<step>
- "<area_size>" - the range is subdivided into areas each containing
- <area_size> sectors.
- "/<number_of_areas>" - the range is subdivided into the specified
- number of areas.
+ "<area_size>"
+ the range is subdivided into areas each containing
+ <area_size> sectors.
+ "/<number_of_areas>"
+ the range is subdivided into the specified
+ number of areas.
<number_of_optional_arguments>
The number of optional arguments
<optional_arguments>
- The following optional arguments are supported
- precise_timestamps - use precise timer with nanosecond resolution
+ The following optional arguments are supported:
+
+ precise_timestamps
+ use precise timer with nanosecond resolution
instead of the "jiffies" variable. When this argument is
used, the resulting times are in nanoseconds instead of
milliseconds. Precise timestamps are a little bit slower
to obtain than jiffies-based timestamps.
- histogram:n1,n2,n3,n4,... - collect histogram of latencies. The
+ histogram:n1,n2,n3,n4,...
+ collect histogram of latencies. The
numbers n1, n2, etc are times that represent the boundaries
of the histogram. If precise_timestamps is not used, the
times are in milliseconds, otherwise they are in
@@ -96,21 +102,18 @@ Messages
@stats_list message, but it doesn't use this value for anything.
@stats_delete <region_id>
-
Delete the region with the specified id.
<region_id>
region_id returned from @stats_create
@stats_clear <region_id>
-
Clear all the counters except the in-flight i/o counters.
<region_id>
region_id returned from @stats_create
@stats_list [<program_id>]
-
List all regions registered with @stats_create.
<program_id>
@@ -127,7 +130,6 @@ Messages
if they were specified when creating the region.
@stats_print <region_id> [<starting_line> <number_of_lines>]
-
Print counters for each step-sized area of a region.
<region_id>
@@ -143,10 +145,11 @@ Messages
Output format for each step-sized area of a region:
- <start_sector>+<length> counters
+ <start_sector>+<length>
+ counters
The first 11 counters have the same meaning as
- /sys/block/*/stat or /proc/diskstats.
+ `/sys/block/*/stat or /proc/diskstats`.
Please refer to Documentation/iostats.txt for details.
@@ -163,11 +166,11 @@ Messages
11. the weighted number of milliseconds spent doing I/Os
Additional counters:
+
12. the total time spent reading in milliseconds
13. the total time spent writing in milliseconds
@stats_print_clear <region_id> [<starting_line> <number_of_lines>]
-
Atomically print and then clear all the counters except the
in-flight i/o counters. Useful when the client consuming the
statistics does not want to lose any statistics (those updated
@@ -185,7 +188,6 @@ Messages
If omitted, all lines are printed and then cleared.
@stats_set_aux <region_id> <aux_data>
-
Store auxiliary data aux_data for the specified region.
<region_id>
@@ -201,23 +203,23 @@ Examples
========
Subdivide the DM device 'vol' into 100 pieces and start collecting
-statistics on them:
+statistics on them::
dmsetup message vol 0 @stats_create - /100
Set the auxiliary data string to "foo bar baz" (the escape for each
-space must also be escaped, otherwise the shell will consume them):
+space must also be escaped, otherwise the shell will consume them)::
dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
-List the statistics:
+List the statistics::
dmsetup message vol 0 @stats_list
-Print the statistics:
+Print the statistics::
dmsetup message vol 0 @stats_print 0
-Delete the statistics:
+Delete the statistics::
dmsetup message vol 0 @stats_delete 0
diff --git a/Documentation/device-mapper/striped.txt b/Documentation/device-mapper/striped.rst
similarity index 32%
rename from Documentation/device-mapper/striped.txt
rename to Documentation/device-mapper/striped.rst
index 07ec492cceee..e9a8da192ae1 100644
--- a/Documentation/device-mapper/striped.txt
+++ b/Documentation/device-mapper/striped.rst
@@ -1,3 +1,4 @@
+=========
dm-stripe
=========
@@ -8,12 +9,16 @@ potentially provide improved I/O throughput by utilizing several physical
devices in parallel.
Parameters: <num devs> <chunk size> [<dev path> <offset>]+
- <num devs>: Number of underlying devices.
- <chunk size>: Size of each chunk of data. Must be at least as
- large as the system's PAGE_SIZE.
- <dev path>: Full pathname to the underlying block-device, or a
- "major:minor" device-number.
- <offset>: Starting sector within the device.
+ <num devs>:
+ Number of underlying devices.
+ <chunk size>:
+ Size of each chunk of data. Must be at least as
+ large as the system's PAGE_SIZE.
+ <dev path>:
+ Full pathname to the underlying block-device, or a
+ "major:minor" device-number.
+ <offset>:
+ Starting sector within the device.
One or more underlying devices can be specified. The striped device size must
be a multiple of the chunk size multiplied by the number of underlying devices.
@@ -22,36 +27,35 @@ be a multiple of the chunk size multiplied by the number of underlying devices.
Example scripts
===============
-[[
-#!/usr/bin/perl -w
-# Create a striped device across any number of underlying devices. The device
-# will be called "stripe_dev" and have a chunk-size of 128k.
+::
-my $chunk_size = 128 * 2;
-my $dev_name = "stripe_dev";
-my $num_devs = @ARGV;
-my @devs = @ARGV;
-my ($min_dev_size, $stripe_dev_size, $i);
+ #!/usr/bin/perl -w
+ # Create a striped device across any number of underlying devices. The device
+ # will be called "stripe_dev" and have a chunk-size of 128k.
-if (!$num_devs) {
- die("Specify at least one device\n");
-}
+ my $chunk_size = 128 * 2;
+ my $dev_name = "stripe_dev";
+ my $num_devs = @ARGV;
+ my @devs = @ARGV;
+ my ($min_dev_size, $stripe_dev_size, $i);
-$min_dev_size = `blockdev --getsz $devs[0]`;
-for ($i = 1; $i < $num_devs; $i++) {
- my $this_size = `blockdev --getsz $devs[$i]`;
- $min_dev_size = ($min_dev_size < $this_size) ?
- $min_dev_size : $this_size;
-}
+ if (!$num_devs) {
+ die("Specify at least one device\n");
+ }
-$stripe_dev_size = $min_dev_size * $num_devs;
-$stripe_dev_size -= $stripe_dev_size % ($chunk_size * $num_devs);
+ $min_dev_size = `blockdev --getsz $devs[0]`;
+ for ($i = 1; $i < $num_devs; $i++) {
+ my $this_size = `blockdev --getsz $devs[$i]`;
+ $min_dev_size = ($min_dev_size < $this_size) ?
+ $min_dev_size : $this_size;
+ }
-$table = "0 $stripe_dev_size striped $num_devs $chunk_size";
-for ($i = 0; $i < $num_devs; $i++) {
- $table .= " $devs[$i] 0";
-}
+ $stripe_dev_size = $min_dev_size * $num_devs;
+ $stripe_dev_size -= $stripe_dev_size % ($chunk_size * $num_devs);
-`echo $table | dmsetup create $dev_name`;
-]]
+ $table = "0 $stripe_dev_size striped $num_devs $chunk_size";
+ for ($i = 0; $i < $num_devs; $i++) {
+ $table .= " $devs[$i] 0";
+ }
+ `echo $table | dmsetup create $dev_name`;
diff --git a/Documentation/device-mapper/switch.txt b/Documentation/device-mapper/switch.rst
similarity index 84%
rename from Documentation/device-mapper/switch.txt
rename to Documentation/device-mapper/switch.rst
index 5bd4831db4a8..7dde06be1a4f 100644
--- a/Documentation/device-mapper/switch.txt
+++ b/Documentation/device-mapper/switch.rst
@@ -1,3 +1,4 @@
+=========
dm-switch
=========
@@ -67,27 +68,25 @@ b-tree can achieve.
Construction Parameters
=======================
- <num_paths> <region_size> <num_optional_args> [<optional_args>...]
- [<dev_path> <offset>]+
+ <num_paths> <region_size> <num_optional_args> [<optional_args>...] [<dev_path> <offset>]+
+ <num_paths>
+ The number of paths across which to distribute the I/O.
-<num_paths>
- The number of paths across which to distribute the I/O.
+ <region_size>
+ The number of 512-byte sectors in a region. Each region can be redirected
+ to any of the available paths.
-<region_size>
- The number of 512-byte sectors in a region. Each region can be redirected
- to any of the available paths.
+ <num_optional_args>
+ The number of optional arguments. Currently, no optional arguments
+ are supported and so this must be zero.
-<num_optional_args>
- The number of optional arguments. Currently, no optional arguments
- are supported and so this must be zero.
+ <dev_path>
+ The block device that represents a specific path to the device.
-<dev_path>
- The block device that represents a specific path to the device.
-
-<offset>
- The offset of the start of data on the specific <dev_path> (in units
- of 512-byte sectors). This number is added to the sector number when
- forwarding the request to the specific path. Typically it is zero.
+ <offset>
+ The offset of the start of data on the specific <dev_path> (in units
+ of 512-byte sectors). This number is added to the sector number when
+ forwarding the request to the specific path. Typically it is zero.
Messages
========
@@ -122,17 +121,21 @@ Example
Assume that you have volumes vg1/switch0 vg1/switch1 vg1/switch2 with
the same size.
-Create a switch device with 64kB region size:
+Create a switch device with 64kB region size::
+
dmsetup create switch --table "0 `blockdev --getsz /dev/vg1/switch0`
switch 3 128 0 /dev/vg1/switch0 0 /dev/vg1/switch1 0 /dev/vg1/switch2 0"
Set mappings for the first 7 entries to point to devices switch0, switch1,
-switch2, switch0, switch1, switch2, switch1:
+switch2, switch0, switch1, switch2, switch1::
+
dmsetup message switch 0 set_region_mappings 0:0 :1 :2 :0 :1 :2 :1
-Set repetitive mapping. This command:
+Set repetitive mapping. This command::
+
dmsetup message switch 0 set_region_mappings 1000:1 :2 R2,10
-is equivalent to:
+
+is equivalent to::
+
dmsetup message switch 0 set_region_mappings 1000:1 :2 :1 :2 :1 :2 :1 :2 \
:1 :2 :1 :2 :1 :2 :1 :2 :1 :2
-
diff --git a/Documentation/device-mapper/thin-provisioning.txt b/Documentation/device-mapper/thin-provisioning.rst
similarity index 92%
rename from Documentation/device-mapper/thin-provisioning.txt
rename to Documentation/device-mapper/thin-provisioning.rst
index 883e7ca5f745..bafebf79da4b 100644
--- a/Documentation/device-mapper/thin-provisioning.txt
+++ b/Documentation/device-mapper/thin-provisioning.rst
@@ -1,3 +1,7 @@
+=================
+Thin provisioning
+=================
+
Introduction
============
@@ -95,6 +99,8 @@ previously.)
Using an existing pool device
-----------------------------
+::
+
dmsetup create pool \
--table "0 20971520 thin-pool $metadata_dev $data_dev \
$data_block_size $low_water_mark"
@@ -154,7 +160,7 @@ Thin provisioning
i) Creating a new thinly-provisioned volume.
To create a new thinly- provisioned volume you must send a message to an
- active pool device, /dev/mapper/pool in this example.
+ active pool device, /dev/mapper/pool in this example::
dmsetup message /dev/mapper/pool 0 "create_thin 0"
@@ -164,7 +170,7 @@ i) Creating a new thinly-provisioned volume.
ii) Using a thinly-provisioned volume.
- Thinly-provisioned volumes are activated using the 'thin' target:
+ Thinly-provisioned volumes are activated using the 'thin' target::
dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"
@@ -181,6 +187,8 @@ i) Creating an internal snapshot.
must suspend it before creating the snapshot to avoid corruption.
This is NOT enforced at the moment, so please be careful!
+ ::
+
dmsetup suspend /dev/mapper/thin
dmsetup message /dev/mapper/pool 0 "create_snap 1 0"
dmsetup resume /dev/mapper/thin
@@ -198,14 +206,14 @@ ii) Using an internal snapshot.
activating or removing them both. (This differs from conventional
device-mapper snapshots.)
- Activate it exactly the same way as any other thinly-provisioned volume:
+ Activate it exactly the same way as any other thinly-provisioned volume::
dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"
External snapshots
------------------
-You can use an external _read only_ device as an origin for a
+You can use an external **read only** device as an origin for a
thinly-provisioned volume. Any read to an unprovisioned area of the
thin device will be passed through to the origin. Writes trigger
the allocation of new blocks as usual.
@@ -223,11 +231,13 @@ i) Creating a snapshot of an external device
This is the same as creating a thin device.
You don't mention the origin at this stage.
+ ::
+
dmsetup message /dev/mapper/pool 0 "create_thin 0"
ii) Using a snapshot of an external device.
- Append an extra parameter to the thin target specifying the origin:
+ Append an extra parameter to the thin target specifying the origin::
dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image"
@@ -240,6 +250,8 @@ Deactivation
All devices using a pool must be deactivated before the pool itself
can be.
+::
+
dmsetup remove thin
dmsetup remove snap
dmsetup remove pool
@@ -252,25 +264,32 @@ Reference
i) Constructor
- thin-pool <metadata dev> <data dev> <data block size (sectors)> \
- <low water mark (blocks)> [<number of feature args> [<arg>]*]
+ ::
+
+ thin-pool <metadata dev> <data dev> <data block size (sectors)> \
+ <low water mark (blocks)> [<number of feature args> [<arg>]*]
Optional feature arguments:
- skip_block_zeroing: Skip the zeroing of newly-provisioned blocks.
+ skip_block_zeroing:
+ Skip the zeroing of newly-provisioned blocks.
- ignore_discard: Disable discard support.
+ ignore_discard:
+ Disable discard support.
- no_discard_passdown: Don't pass discards down to the underlying
- data device, but just remove the mapping.
+ no_discard_passdown:
+ Don't pass discards down to the underlying
+ data device, but just remove the mapping.
- read_only: Don't allow any changes to be made to the pool
+ read_only:
+ Don't allow any changes to be made to the pool
metadata. This mode is only available after the
thin-pool has been created and first used in full
read/write mode. It cannot be specified on initial
thin-pool creation.
- error_if_no_space: Error IOs, instead of queueing, if no space.
+ error_if_no_space:
+ Error IOs, instead of queueing, if no space.
Data block size must be between 64KB (128 sectors) and 1GB
(2097152 sectors) inclusive.
@@ -278,10 +297,12 @@ i) Constructor
ii) Status
- <transaction id> <used metadata blocks>/<total metadata blocks>
- <used data blocks>/<total data blocks> <held metadata root>
- ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space
- needs_check|- metadata_low_watermark
+ ::
+
+ <transaction id> <used metadata blocks>/<total metadata blocks>
+ <used data blocks>/<total data blocks> <held metadata root>
+ ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space
+ needs_check|- metadata_low_watermark
transaction id:
A 64-bit number used by userspace to help synchronise with metadata
@@ -336,13 +357,11 @@ ii) Status
iii) Messages
create_thin <dev id>
-
Create a new thinly-provisioned device.
<dev id> is an arbitrary unique 24-bit identifier chosen by
the caller.
create_snap <dev id> <origin id>
-
Create a new snapshot of another thinly-provisioned device.
<dev id> is an arbitrary unique 24-bit identifier chosen by
the caller.
@@ -350,11 +369,9 @@ iii) Messages
of which the new device will be a snapshot.
delete <dev id>
-
Deletes a thin device. Irreversible.
set_transaction_id <current id> <new id>
-
Userland volume managers, such as LVM, need a way to
synchronise their external metadata with the internal metadata of the
pool target. The thin-pool target offers to store an
@@ -364,14 +381,12 @@ iii) Messages
compare-and-swap message.
reserve_metadata_snap
-
Reserve a copy of the data mapping btree for use by userland.
This allows userland to inspect the mappings as they were when
this message was executed. Use the pool's status command to
get the root block associated with the metadata snapshot.
release_metadata_snap
-
Release a previously reserved copy of the data mapping btree.
'thin' target
@@ -379,7 +394,9 @@ iii) Messages
i) Constructor
- thin <pool dev> <dev id> [<external origin dev>]
+ ::
+
+ thin <pool dev> <dev id> [<external origin dev>]
pool dev:
the thin-pool device, e.g. /dev/mapper/my_pool or 253:0
@@ -401,8 +418,7 @@ provisioned as and when needed.
ii) Status
- <nr mapped sectors> <highest mapped sector>
-
+ <nr mapped sectors> <highest mapped sector>
If the pool has encountered device errors and failed, the status
will just contain the string 'Fail'. The userspace recovery
tools should then be used.
diff --git a/Documentation/device-mapper/unstriped.txt b/Documentation/device-mapper/unstriped.rst
similarity index 60%
rename from Documentation/device-mapper/unstriped.txt
rename to Documentation/device-mapper/unstriped.rst
index 0b2a306c54ee..0a8d3eb3f072 100644
--- a/Documentation/device-mapper/unstriped.txt
+++ b/Documentation/device-mapper/unstriped.rst
@@ -1,3 +1,7 @@
+================================
+Device-mapper "unstriped" target
+================================
+
Introduction
============
@@ -34,46 +38,46 @@ striped target to combine the 4 devices into one. It then will use
the unstriped target ontop of the striped device to access the
individual backing loop devices. We write data to the newly exposed
unstriped devices and verify the data written matches the correct
-underlying device on the striped array.
-
-#!/bin/bash
-
-MEMBER_SIZE=$((128 * 1024 * 1024))
-NUM=4
-SEQ_END=$((${NUM}-1))
-CHUNK=256
-BS=4096
-
-RAID_SIZE=$((${MEMBER_SIZE}*${NUM}/512))
-DM_PARMS="0 ${RAID_SIZE} striped ${NUM} ${CHUNK}"
-COUNT=$((${MEMBER_SIZE} / ${BS}))
-
-for i in $(seq 0 ${SEQ_END}); do
- dd if=/dev/zero of=member-${i} bs=${MEMBER_SIZE} count=1 oflag=direct
- losetup /dev/loop${i} member-${i}
- DM_PARMS+=" /dev/loop${i} 0"
-done
-
-echo $DM_PARMS | dmsetup create raid0
-for i in $(seq 0 ${SEQ_END}); do
- echo "0 1 unstriped ${NUM} ${CHUNK} ${i} /dev/mapper/raid0 0" | dmsetup create set-${i}
-done;
-
-for i in $(seq 0 ${SEQ_END}); do
- dd if=/dev/urandom of=/dev/mapper/set-${i} bs=${BS} count=${COUNT} oflag=direct
- diff /dev/mapper/set-${i} member-${i}
-done;
-
-for i in $(seq 0 ${SEQ_END}); do
- dmsetup remove set-${i}
-done
-
-dmsetup remove raid0
-
-for i in $(seq 0 ${SEQ_END}); do
- losetup -d /dev/loop${i}
- rm -f member-${i}
-done
+underlying device on the striped array::
+
+ #!/bin/bash
+
+ MEMBER_SIZE=$((128 * 1024 * 1024))
+ NUM=4
+ SEQ_END=$((${NUM}-1))
+ CHUNK=256
+ BS=4096
+
+ RAID_SIZE=$((${MEMBER_SIZE}*${NUM}/512))
+ DM_PARMS="0 ${RAID_SIZE} striped ${NUM} ${CHUNK}"
+ COUNT=$((${MEMBER_SIZE} / ${BS}))
+
+ for i in $(seq 0 ${SEQ_END}); do
+ dd if=/dev/zero of=member-${i} bs=${MEMBER_SIZE} count=1 oflag=direct
+ losetup /dev/loop${i} member-${i}
+ DM_PARMS+=" /dev/loop${i} 0"
+ done
+
+ echo $DM_PARMS | dmsetup create raid0
+ for i in $(seq 0 ${SEQ_END}); do
+ echo "0 1 unstriped ${NUM} ${CHUNK} ${i} /dev/mapper/raid0 0" | dmsetup create set-${i}
+ done;
+
+ for i in $(seq 0 ${SEQ_END}); do
+ dd if=/dev/urandom of=/dev/mapper/set-${i} bs=${BS} count=${COUNT} oflag=direct
+ diff /dev/mapper/set-${i} member-${i}
+ done;
+
+ for i in $(seq 0 ${SEQ_END}); do
+ dmsetup remove set-${i}
+ done
+
+ dmsetup remove raid0
+
+ for i in $(seq 0 ${SEQ_END}); do
+ losetup -d /dev/loop${i}
+ rm -f member-${i}
+ done
Another example
---------------
@@ -81,7 +85,7 @@ Another example
Intel NVMe drives contain two cores on the physical device.
Each core of the drive has segregated access to its LBA range.
The current LBA model has a RAID 0 128k chunk on each core, resulting
-in a 256k stripe across the two cores:
+in a 256k stripe across the two cores::
Core 0: Core 1:
__________ __________
@@ -108,17 +112,24 @@ Example dmsetup usage
unstriped ontop of Intel NVMe device that has 2 cores
-----------------------------------------------------
-dmsetup create nvmset0 --table '0 512 unstriped 2 256 0 /dev/nvme0n1 0'
-dmsetup create nvmset1 --table '0 512 unstriped 2 256 1 /dev/nvme0n1 0'
+
+::
+
+ dmsetup create nvmset0 --table '0 512 unstriped 2 256 0 /dev/nvme0n1 0'
+ dmsetup create nvmset1 --table '0 512 unstriped 2 256 1 /dev/nvme0n1 0'
There will now be two devices that expose Intel NVMe core 0 and 1
-respectively:
-/dev/mapper/nvmset0
-/dev/mapper/nvmset1
+respectively::
+
+ /dev/mapper/nvmset0
+ /dev/mapper/nvmset1
unstriped ontop of striped with 4 drives using 128K chunk size
--------------------------------------------------------------
-dmsetup create raid_disk0 --table '0 512 unstriped 4 256 0 /dev/mapper/striped 0'
-dmsetup create raid_disk1 --table '0 512 unstriped 4 256 1 /dev/mapper/striped 0'
-dmsetup create raid_disk2 --table '0 512 unstriped 4 256 2 /dev/mapper/striped 0'
-dmsetup create raid_disk3 --table '0 512 unstriped 4 256 3 /dev/mapper/striped 0'
+
+::
+
+ dmsetup create raid_disk0 --table '0 512 unstriped 4 256 0 /dev/mapper/striped 0'
+ dmsetup create raid_disk1 --table '0 512 unstriped 4 256 1 /dev/mapper/striped 0'
+ dmsetup create raid_disk2 --table '0 512 unstriped 4 256 2 /dev/mapper/striped 0'
+ dmsetup create raid_disk3 --table '0 512 unstriped 4 256 3 /dev/mapper/striped 0'
diff --git a/Documentation/device-mapper/verity.txt b/Documentation/device-mapper/verity.rst
similarity index 98%
rename from Documentation/device-mapper/verity.txt
rename to Documentation/device-mapper/verity.rst
index b3d2e4a42255..a4d1c1476d72 100644
--- a/Documentation/device-mapper/verity.txt
+++ b/Documentation/device-mapper/verity.rst
@@ -1,5 +1,6 @@
+=========
dm-verity
-==========
+=========
Device-Mapper's "verity" target provides transparent integrity checking of
block devices using a cryptographic digest provided by the kernel crypto API.
@@ -7,6 +8,9 @@ This target is read-only.
Construction Parameters
=======================
+
+::
+
<version> <dev> <hash_dev>
<data_block_size> <hash_block_size>
<num_data_blocks> <hash_start_block>
@@ -160,7 +164,9 @@ calculating the parent node.
The tree looks something like:
-alg = sha256, num_blocks = 32768, block_size = 4096
+ alg = sha256, num_blocks = 32768, block_size = 4096
+
+::
[ root ]
/ . . . \
@@ -189,6 +195,7 @@ block boundary) are the hash blocks which are stored a depth at a time
The full specification of kernel parameters and on-disk metadata format
is available at the cryptsetup project's wiki page
+
https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity
Status
@@ -198,7 +205,8 @@ If any check failed, C (for Corruption) is returned.
Example
=======
-Set up a device:
+Set up a device::
+
# dmsetup create vroot --readonly --table \
"0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\
"4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
@@ -209,11 +217,13 @@ the hash tree or activate the kernel device. This is available from
the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/
(as a libcryptsetup extension).
-Create hash on the device:
+Create hash on the device::
+
# veritysetup format /dev/sda1 /dev/sda2
...
Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
-Activate the device:
+Activate the device::
+
# veritysetup create vroot /dev/sda1 /dev/sda2 \
4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
diff --git a/Documentation/device-mapper/writecache.txt b/Documentation/device-mapper/writecache.rst
similarity index 96%
rename from Documentation/device-mapper/writecache.txt
rename to Documentation/device-mapper/writecache.rst
index 01532b3008ae..d3d7690f5e8d 100644
--- a/Documentation/device-mapper/writecache.txt
+++ b/Documentation/device-mapper/writecache.rst
@@ -1,3 +1,7 @@
+=================
+Writecache target
+=================
+
The writecache target caches writes on persistent memory or on SSD. It
doesn't cache reads because reads are supposed to be cached in page cache
in normal RAM.
@@ -6,15 +10,18 @@ When the device is constructed, the first sector should be zeroed or the
first sector should contain valid superblock from previous invocation.
Constructor parameters:
+
1. type of the cache device - "p" or "s"
- p - persistent memory
- s - SSD
+
+ - p - persistent memory
+ - s - SSD
2. the underlying device that will be cached
3. the cache device
4. block size (4096 is recommended; the maximum block size is the page
size)
5. the number of optional parameters (the parameters with an argument
count as two)
+
start_sector n (default: 0)
offset from the start of cache device in 512-byte sectors
high_watermark n (default: 50)
@@ -43,6 +50,7 @@ Constructor parameters:
applicable only to persistent memory - don't use the FUA
flag when writing back data and send the FLUSH request
afterwards
+
- some underlying devices perform better with fua, some
with nofua. The user should test it
@@ -60,6 +68,7 @@ Messages:
flush the cache device on next suspend. Use this message
when you are going to remove the cache device. The proper
sequence for removing the cache device is:
+
1. send the "flush_on_suspend" message
2. load an inactive table with a linear target that maps
to the underlying device
diff --git a/Documentation/device-mapper/zero.txt b/Documentation/device-mapper/zero.rst
similarity index 83%
rename from Documentation/device-mapper/zero.txt
rename to Documentation/device-mapper/zero.rst
index 20fb38e7fa7e..11fb5cf4597c 100644
--- a/Documentation/device-mapper/zero.txt
+++ b/Documentation/device-mapper/zero.rst
@@ -1,3 +1,4 @@
+=======
dm-zero
=======
@@ -18,20 +19,19 @@ filesystem limitations.
To create a sparse device, start by creating a dm-zero device that's the
desired size of the sparse device. For this example, we'll assume a 10TB
-sparse device.
+sparse device::
-TEN_TERABYTES=`expr 10 \* 1024 \* 1024 \* 1024 \* 2` # 10 TB in sectors
-echo "0 $TEN_TERABYTES zero" | dmsetup create zero1
+ TEN_TERABYTES=`expr 10 \* 1024 \* 1024 \* 1024 \* 2` # 10 TB in sectors
+ echo "0 $TEN_TERABYTES zero" | dmsetup create zero1
Then create a snapshot of the zero device, using any available block-device as
the COW device. The size of the COW device will determine the amount of real
space available to the sparse device. For this example, we'll assume /dev/sdb1
-is an available 10GB partition.
+is an available 10GB partition::
-echo "0 $TEN_TERABYTES snapshot /dev/mapper/zero1 /dev/sdb1 p 128" | \
- dmsetup create sparse1
+ echo "0 $TEN_TERABYTES snapshot /dev/mapper/zero1 /dev/sdb1 p 128" | \
+ dmsetup create sparse1
This will create a 10TB sparse device called /dev/mapper/sparse1 that has
10GB of actual storage space available. If more than 10GB of data is written
to this device, it will start returning I/O errors.
-
diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.md
index 028b3e2e25f9..23e698167141 100644
--- a/Documentation/filesystems/ubifs-authentication.md
+++ b/Documentation/filesystems/ubifs-authentication.md
@@ -417,9 +417,9 @@ will then have to be provided beforehand in the normal way.
[DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/
-[DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.txt
+[DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst
-[DM-VERITY] https://www.kernel.org/doc/Documentation/device-mapper/verity.txt
+[DM-VERITY] https://www.kernel.org/doc/Documentation/device-mapper/verity.rst
[FSCRYPT-POLICY2] https://www.spinics.net/lists/linux-ext4/msg58710.html
diff --git a/drivers/md/Kconfig b/drivers/md/Kconfig
index 45254b3ef715..5ccac0b77f17 100644
--- a/drivers/md/Kconfig
+++ b/drivers/md/Kconfig
@@ -453,7 +453,7 @@ config DM_INIT
Enable "dm-mod.create=" parameter to create mapped devices at init time.
This option is useful to allow mounting rootfs without requiring an
initramfs.
- See Documentation/device-mapper/dm-init.txt for dm-mod.create="..."
+ See Documentation/device-mapper/dm-init.rst for dm-mod.create="..."
format.
If unsure, say N.
diff --git a/drivers/md/dm-init.c b/drivers/md/dm-init.c
index 352e803f566e..a58d0944f592 100644
--- a/drivers/md/dm-init.c
+++ b/drivers/md/dm-init.c
@@ -25,7 +25,7 @@ static char *create;
* Format: dm-mod.create=<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,<minor>,<flags>,<table>[,<table>+]+]
* Table format: <start_sector> <num_sectors> <target_type> <target_args>
*
- * See Documentation/device-mapper/dm-init.txt for dm-mod.create="..." format
+ * See Documentation/device-mapper/dm-init.rst for dm-mod.create="..." format
* details.
*/
diff --git a/drivers/md/dm-raid.c b/drivers/md/dm-raid.c
index 9fdef6897316..7a87a640f8ba 100644
--- a/drivers/md/dm-raid.c
+++ b/drivers/md/dm-raid.c
@@ -3558,7 +3558,7 @@ static void raid_status(struct dm_target *ti, status_type_t type,
* v1.5.0+:
*
* Sync action:
- * See Documentation/device-mapper/dm-raid.txt for
+ * See Documentation/device-mapper/dm-raid.rst for
* information on each of these states.
*/
DMEMIT(" %s", sync_action);
--
2.21.0
The CFQ scheduler was removed on this changeset:
commit f382fb0bcef4c37dc049e9f6963e3baf204d815c
Author: Jens Axboe <[email protected]>
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 <[email protected]>
Reviewed-by: Omar Sandoval <[email protected]>
Signed-off-by: Jens Axboe <[email protected]>
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 <[email protected]>
---
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
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 <[email protected]>
---
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 <[email protected]>
- Xiao Guangrong <[email protected]>
- Wu Hao <[email protected]>
+=================================================
+FPGA Device Feature List (DFL) Framework Overview
+=================================================
+
+Authors:
+
+- Enno Luebbers <[email protected]>
+- Xiao Guangrong <[email protected]>
+- Wu Hao <[email protected]>
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 9f83a79fdfdb..cc11aea722c8 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6270,7 +6270,7 @@ FPGA DFL DRIVERS
M: Wu Hao <[email protected]>
L: [email protected]
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
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 <[email protected]>
---
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
The first bit/value table inside the document is very
hard to read and won't fit ReST format. Also, some columns aren't
properly aligned.
Convert it to a nice ascii artwork table with makes it easier to
read as plain text and is compatible with ReST format parser
on Sphinx.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/s390/Debugging390.txt | 210 ++++++++++++++++------------
1 file changed, 120 insertions(+), 90 deletions(-)
diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt
index 5ae7f868a007..c35804c238ad 100644
--- a/Documentation/s390/Debugging390.txt
+++ b/Documentation/s390/Debugging390.txt
@@ -78,96 +78,126 @@ e.g. switching address translation off requires that you
have a logical=physical mapping for the address you are
currently running at.
- Bit Value
-s/390 z/Architecture
-0 0 Reserved ( must be 0 ) otherwise specification exception occurs.
-
-1 1 Program Event Recording 1 PER enabled,
- PER is used to facilitate debugging e.g. single stepping.
-
-2-4 2-4 Reserved ( must be 0 ).
-
-5 5 Dynamic address translation 1=DAT on.
-
-6 6 Input/Output interrupt Mask
-
-7 7 External interrupt Mask used primarily for interprocessor
- signalling and clock interrupts.
-
-8-11 8-11 PSW Key used for complex memory protection mechanism
- (not used under linux)
-
-12 12 1 on s/390 0 on z/Architecture
-
-13 13 Machine Check Mask 1=enable machine check interrupts
-
-14 14 Wait State. Set this to 1 to stop the processor except for
- interrupts and give time to other LPARS. Used in CPU idle in
- the kernel to increase overall usage of processor resources.
-
-15 15 Problem state ( if set to 1 certain instructions are disabled )
- all linux user programs run with this bit 1
- ( useful info for debugging under VM ).
-
-16-17 16-17 Address Space Control
-
- 00 Primary Space Mode:
- The register CR1 contains the primary address-space control ele-
- ment (PASCE), which points to the primary space region/segment
- table origin.
-
- 01 Access register mode
-
- 10 Secondary Space Mode:
- The register CR7 contains the secondary address-space control
- element (SASCE), which points to the secondary space region or
- segment table origin.
-
- 11 Home Space Mode:
- The register CR13 contains the home space address-space control
- element (HASCE), which points to the home space region/segment
- table origin.
-
- See "Address Spaces on Linux for s/390 & z/Architecture" below
- for more information about address space usage in Linux.
-
-18-19 18-19 Condition codes (CC)
-
-20 20 Fixed point overflow mask if 1=FPU exceptions for this event
- occur ( normally 0 )
-
-21 21 Decimal overflow mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-22 22 Exponent underflow mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-23 23 Significance Mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-24-31 24-30 Reserved Must be 0.
-
- 31 Extended Addressing Mode
- 32 Basic Addressing Mode
- Used to set addressing mode
- PSW 31 PSW 32
- 0 0 24 bit
- 0 1 31 bit
- 1 1 64 bit
-
-32 1=31 bit addressing mode 0=24 bit addressing mode (for backward
- compatibility), linux always runs with this bit set to 1
-
-33-64 Instruction address.
- 33-63 Reserved must be 0
- 64-127 Address
- In 24 bits mode bits 64-103=0 bits 104-127 Address
- In 31 bits mode bits 64-96=0 bits 97-127 Address
- Note: unlike 31 bit mode on s/390 bit 96 must be zero
- when loading the address with LPSWE otherwise a
- specification exception occurs, LPSW is fully backward
- compatible.
-
++-------------------------+-------------------------------------------------+
+| Bit | |
++--------+----------------+ Value |
+| s/390 | z/Architecture | |
++========+================+=================================================+
+| 0 | 0 | Reserved (must be 0) otherwise specification |
+| | | exception occurs. |
++--------+----------------+-------------------------------------------------+
+| 1 | 1 | Program Event Recording 1 PER enabled, |
+| | | PER is used to facilitate debugging e.g. |
+| | | single stepping. |
++--------+----------------+-------------------------------------------------+
+| 2-4 | 2-4 | Reserved (must be 0). |
++--------+----------------+-------------------------------------------------+
+| 5 | 5 | Dynamic address translation 1=DAT on. |
++--------+----------------+-------------------------------------------------+
+| 6 | 6 | Input/Output interrupt Mask |
++--------+----------------+-------------------------------------------------+
+| 7 | 7 | External interrupt Mask used primarily for |
+| | | interprocessor signalling and clock interrupts. |
++--------+----------------+-------------------------------------------------+
+| 8-11 | 8-11 | PSW Key used for complex memory protection |
+| | | mechanism (not used under linux) |
++--------+----------------+-------------------------------------------------+
+| 12 | 12 | 1 on s/390 0 on z/Architecture |
++--------+----------------+-------------------------------------------------+
+| 13 | 13 | Machine Check Mask 1=enable machine check |
+| | | interrupts |
++--------+----------------+-------------------------------------------------+
+| 14 | 14 | Wait State. Set this to 1 to stop the processor |
+| | | except for interrupts and give time to other |
+| | | LPARS. Used in CPU idle in the kernel to |
+| | | increase overall usage of processor resources. |
++--------+----------------+-------------------------------------------------+
+| 15 | 15 | Problem state (if set to 1 certain instructions |
+| | | are disabled). All linux user programs run with |
+| | | this bit 1 (useful info for debugging under VM).|
++--------+----------------+-------------------------------------------------+
+| 16-17 | 16-17 | Address Space Control |
+| | | |
+| | | 00 Primary Space Mode: |
+| | | |
+| | | The register CR1 contains the primary |
+| | | address-space control element (PASCE), which |
+| | | points to the primary space region/segment |
+| | | table origin. |
+| | | |
+| | | 01 Access register mode |
+| | | |
+| | | 10 Secondary Space Mode: |
+| | | |
+| | | The register CR7 contains the secondary |
+| | | address-space control element (SASCE), which |
+| | | points to the secondary space region or |
+| | | segment table origin. |
+| | | |
+| | | 11 Home Space Mode: |
+| | | |
+| | | The register CR13 contains the home space |
+| | | address-space control element (HASCE), which |
+| | | points to the home space region/segment |
+| | | table origin. |
+| | | |
+| | | See "Address Spaces on Linux for s/390 & |
+| | | z/Architecture" below for more information |
+| | | about address space usage in Linux. |
++--------+----------------+-------------------------------------------------+
+| 18-19 | 18-19 | Condition codes (CC) |
++--------+----------------+-------------------------------------------------+
+| 20 | 20 | Fixed point overflow mask if 1=FPU exceptions |
+| | | for this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 21 | 21 | Decimal overflow mask if 1=FPU exceptions for |
+| | | this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 22 | 22 | Exponent underflow mask if 1=FPU exceptions |
+| | | for this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 23 | 23 | Significance Mask if 1=FPU exceptions for this |
+| | | event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 24-31 | 24-30 | Reserved Must be 0. |
+| +----------------+-------------------------------------------------+
+| | 31 | Extended Addressing Mode |
+| +----------------+-------------------------------------------------+
+| | 32 | Basic Addressing Mode |
+| | | |
+| | | Used to set addressing mode |
+| | | |
+| | | +---------+----------+----------+ |
+| | | | PSW 31 | PSW 32 | | |
+| | | +---------+----------+----------+ |
+| | | | 0 | 0 | 24 bit | |
+| | | +---------+----------+----------+ |
+| | | | 0 | 1 | 31 bit | |
+| | | +---------+----------+----------+ |
+| | | | 1 | 1 | 64 bit | |
+| | | +---------+----------+----------+ |
++--------+----------------+-------------------------------------------------+
+| 32 | | 1=31 bit addressing mode 0=24 bit addressing |
+| | | mode (for backward compatibility), linux |
+| | | always runs with this bit set to 1 |
++--------+----------------+-------------------------------------------------+
+| 33-64 | | Instruction address. |
+| +----------------+-------------------------------------------------+
+| | 33-63 | Reserved must be 0 |
+| +----------------+-------------------------------------------------+
+| | 64-127 | Address |
+| | | |
+| | | - In 24 bits mode bits 64-103=0 bits 104-127 |
+| | | Address |
+| | | - In 31 bits mode bits 64-96=0 bits 97-127 |
+| | | Address |
+| | | |
+| | | Note: |
+| | | unlike 31 bit mode on s/390 bit 96 must be |
+| | | zero when loading the address with LPSWE |
+| | | otherwise a specification exception occurs, |
+| | | LPSW is fully backward compatible. |
++--------+----------------+-------------------------------------------------+
Prefix Page(s)
--------------
--
2.21.0
The InfiniBand docs are plain text with no markups.
So, all we needed to do were to add the title markups and
some markup sequences in order to properly parse tables,
lists and literal blocks.
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 <[email protected]>
---
.../{core_locking.txt => core_locking.rst} | 64 ++++++-----
Documentation/infiniband/index.rst | 23 ++++
.../infiniband/{ipoib.txt => ipoib.rst} | 24 ++--
.../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +++++++++---------
.../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
.../{tag_matching.txt => tag_matching.rst} | 5 +
.../infiniband/{user_mad.txt => user_mad.rst} | 33 ++++--
.../{user_verbs.txt => user_verbs.rst} | 12 +-
drivers/infiniband/core/user_mad.c | 2 +-
drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
10 files changed, 174 insertions(+), 103 deletions(-)
rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
create mode 100644 Documentation/infiniband/index.rst
rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
diff --git a/Documentation/infiniband/core_locking.txt b/Documentation/infiniband/core_locking.rst
similarity index 78%
rename from Documentation/infiniband/core_locking.txt
rename to Documentation/infiniband/core_locking.rst
index 4b1f36b6ada0..f34669beb4fe 100644
--- a/Documentation/infiniband/core_locking.txt
+++ b/Documentation/infiniband/core_locking.rst
@@ -1,4 +1,6 @@
-INFINIBAND MIDLAYER LOCKING
+===========================
+InfiniBand Midlayer Locking
+===========================
This guide is an attempt to make explicit the locking assumptions
made by the InfiniBand midlayer. It describes the requirements on
@@ -6,45 +8,47 @@ INFINIBAND MIDLAYER LOCKING
protocols that use the midlayer.
Sleeping and interrupt context
+==============================
With the following exceptions, a low-level driver implementation of
all of the methods in struct ib_device may sleep. The exceptions
are any methods from the list:
- create_ah
- modify_ah
- query_ah
- destroy_ah
- post_send
- post_recv
- poll_cq
- req_notify_cq
- map_phys_fmr
+ - create_ah
+ - modify_ah
+ - query_ah
+ - destroy_ah
+ - post_send
+ - post_recv
+ - poll_cq
+ - req_notify_cq
+ - map_phys_fmr
which may not sleep and must be callable from any context.
The corresponding functions exported to upper level protocol
consumers:
- ib_create_ah
- ib_modify_ah
- ib_query_ah
- ib_destroy_ah
- ib_post_send
- ib_post_recv
- ib_req_notify_cq
- ib_map_phys_fmr
+ - ib_create_ah
+ - ib_modify_ah
+ - ib_query_ah
+ - ib_destroy_ah
+ - ib_post_send
+ - ib_post_recv
+ - ib_req_notify_cq
+ - ib_map_phys_fmr
are therefore safe to call from any context.
In addition, the function
- ib_dispatch_event
+ - ib_dispatch_event
used by low-level drivers to dispatch asynchronous events through
the midlayer is also safe to call from any context.
Reentrancy
+----------
All of the methods in struct ib_device exported by a low-level
driver must be fully reentrant. The low-level driver is required to
@@ -62,6 +66,7 @@ Reentrancy
information between different calls of ib_poll_cq() is not defined.
Callbacks
+---------
A low-level driver must not perform a callback directly from the
same callchain as an ib_device method call. For example, it is not
@@ -74,18 +79,18 @@ Callbacks
completion event handlers for the same CQ are not called
simultaneously. The driver must guarantee that only one CQ event
handler for a given CQ is running at a time. In other words, the
- following situation is not allowed:
+ following situation is not allowed::
- CPU1 CPU2
+ CPU1 CPU2
- low-level driver ->
- consumer CQ event callback:
- /* ... */
- ib_req_notify_cq(cq, ...);
- low-level driver ->
- /* ... */ consumer CQ event callback:
- /* ... */
- return from CQ event handler
+ low-level driver ->
+ consumer CQ event callback:
+ /* ... */
+ ib_req_notify_cq(cq, ...);
+ low-level driver ->
+ /* ... */ consumer CQ event callback:
+ /* ... */
+ return from CQ event handler
The context in which completion event and asynchronous event
callbacks run is not defined. Depending on the low-level driver, it
@@ -93,6 +98,7 @@ Callbacks
Upper level protocol consumers may not sleep in a callback.
Hot-plug
+--------
A low-level driver announces that a device is ready for use by
consumers when it calls ib_register_device(), all initialization
diff --git a/Documentation/infiniband/index.rst b/Documentation/infiniband/index.rst
new file mode 100644
index 000000000000..22eea64de722
--- /dev/null
+++ b/Documentation/infiniband/index.rst
@@ -0,0 +1,23 @@
+:orphan:
+
+==========
+InfiniBand
+==========
+
+.. toctree::
+ :maxdepth: 1
+
+ core_locking
+ ipoib
+ opa_vnic
+ sysfs
+ tag_matching
+ user_mad
+ user_verbs
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/infiniband/ipoib.txt b/Documentation/infiniband/ipoib.rst
similarity index 90%
rename from Documentation/infiniband/ipoib.txt
rename to Documentation/infiniband/ipoib.rst
index 47c1dd9818f2..0dd36154c0c9 100644
--- a/Documentation/infiniband/ipoib.txt
+++ b/Documentation/infiniband/ipoib.rst
@@ -1,4 +1,6 @@
-IP OVER INFINIBAND
+==================
+IP over InfiniBand
+==================
The ib_ipoib driver is an implementation of the IP over InfiniBand
protocol as specified by RFC 4391 and 4392, issued by the IETF ipoib
@@ -8,16 +10,17 @@ IP OVER INFINIBAND
masqueraded to the kernel as ethernet interfaces).
Partitions and P_Keys
+=====================
When the IPoIB driver is loaded, it creates one interface for each
port using the P_Key at index 0. To create an interface with a
different P_Key, write the desired P_Key into the main interface's
- /sys/class/net/<intf name>/create_child file. For example:
+ /sys/class/net/<intf name>/create_child file. For example::
echo 0x8001 > /sys/class/net/ib0/create_child
This will create an interface named ib0.8001 with P_Key 0x8001. To
- remove a subinterface, use the "delete_child" file:
+ remove a subinterface, use the "delete_child" file::
echo 0x8001 > /sys/class/net/ib0/delete_child
@@ -28,6 +31,7 @@ Partitions and P_Keys
rtnl_link_ops, where children created using either way behave the same.
Datagram vs Connected modes
+===========================
The IPoIB driver supports two modes of operation: datagram and
connected. The mode is set and read through an interface's
@@ -51,6 +55,7 @@ Datagram vs Connected modes
networking stack to use the smaller UD MTU for these neighbours.
Stateless offloads
+==================
If the IB HW supports IPoIB stateless offloads, IPoIB advertises
TCP/IP checksum and/or Large Send (LSO) offloading capability to the
@@ -60,9 +65,10 @@ Stateless offloads
on/off using ethtool calls. Currently LRO is supported only for
checksum offload capable devices.
- Stateless offloads are supported only in datagram mode.
+ Stateless offloads are supported only in datagram mode.
Interrupt moderation
+====================
If the underlying IB device supports CQ event moderation, one can
use ethtool to set interrupt mitigation parameters and thus reduce
@@ -71,6 +77,7 @@ Interrupt moderation
moderation is supported.
Debugging Information
+=====================
By compiling the IPoIB driver with CONFIG_INFINIBAND_IPOIB_DEBUG set
to 'y', tracing messages are compiled into the driver. They are
@@ -79,7 +86,7 @@ Debugging Information
runtime through files in /sys/module/ib_ipoib/.
CONFIG_INFINIBAND_IPOIB_DEBUG also enables files in the debugfs
- virtual filesystem. By mounting this filesystem, for example with
+ virtual filesystem. By mounting this filesystem, for example with::
mount -t debugfs none /sys/kernel/debug
@@ -96,10 +103,13 @@ Debugging Information
performance, because it adds tests to the fast path.
References
+==========
Transmission of IP over InfiniBand (IPoIB) (RFC 4391)
- http://ietf.org/rfc/rfc4391.txt
+ http://ietf.org/rfc/rfc4391.txt
+
IP over InfiniBand (IPoIB) Architecture (RFC 4392)
- http://ietf.org/rfc/rfc4392.txt
+ http://ietf.org/rfc/rfc4392.txt
+
IP over InfiniBand: Connected Mode (RFC 4755)
http://ietf.org/rfc/rfc4755.txt
diff --git a/Documentation/infiniband/opa_vnic.txt b/Documentation/infiniband/opa_vnic.rst
similarity index 63%
rename from Documentation/infiniband/opa_vnic.txt
rename to Documentation/infiniband/opa_vnic.rst
index 282e17be798a..2f888d9ffec0 100644
--- a/Documentation/infiniband/opa_vnic.txt
+++ b/Documentation/infiniband/opa_vnic.rst
@@ -1,3 +1,7 @@
+=================================================================
+Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC)
+=================================================================
+
Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC) feature
supports Ethernet functionality over Omni-Path fabric by encapsulating
the Ethernet packets between HFI nodes.
@@ -17,70 +21,72 @@ an independent Ethernet network. The configuration is performed by an
Ethernet Manager (EM) which is part of the trusted Fabric Manager (FM)
application. HFI nodes can have multiple VNICs each connected to a
different virtual Ethernet switch. The below diagram presents a case
-of two virtual Ethernet switches with two HFI nodes.
+of two virtual Ethernet switches with two HFI nodes::
- +-------------------+
- | Subnet/ |
- | Ethernet |
- | Manager |
- +-------------------+
- / /
- / /
- / /
- / /
-+-----------------------------+ +------------------------------+
-| Virtual Ethernet Switch | | Virtual Ethernet Switch |
-| +---------+ +---------+ | | +---------+ +---------+ |
-| | VPORT | | VPORT | | | | VPORT | | VPORT | |
-+--+---------+----+---------+-+ +-+---------+----+---------+---+
- | \ / |
- | \ / |
- | \/ |
- | / \ |
- | / \ |
- +-----------+------------+ +-----------+------------+
- | VNIC | VNIC | | VNIC | VNIC |
- +-----------+------------+ +-----------+------------+
- | HFI | | HFI |
- +------------------------+ +------------------------+
+ +-------------------+
+ | Subnet/ |
+ | Ethernet |
+ | Manager |
+ +-------------------+
+ / /
+ / /
+ / /
+ / /
+ +-----------------------------+ +------------------------------+
+ | Virtual Ethernet Switch | | Virtual Ethernet Switch |
+ | +---------+ +---------+ | | +---------+ +---------+ |
+ | | VPORT | | VPORT | | | | VPORT | | VPORT | |
+ +--+---------+----+---------+-+ +-+---------+----+---------+---+
+ | \ / |
+ | \ / |
+ | \/ |
+ | / \ |
+ | / \ |
+ +-----------+------------+ +-----------+------------+
+ | VNIC | VNIC | | VNIC | VNIC |
+ +-----------+------------+ +-----------+------------+
+ | HFI | | HFI |
+ +------------------------+ +------------------------+
The Omni-Path encapsulated Ethernet packet format is as described below.
-Bits Field
-------------------------------------
+==================== ================================
+Bits Field
+==================== ================================
Quad Word 0:
-0-19 SLID (lower 20 bits)
-20-30 Length (in Quad Words)
-31 BECN bit
-32-51 DLID (lower 20 bits)
-52-56 SC (Service Class)
-57-59 RC (Routing Control)
-60 FECN bit
-61-62 L2 (=10, 16B format)
-63 LT (=1, Link Transfer Head Flit)
+0-19 SLID (lower 20 bits)
+20-30 Length (in Quad Words)
+31 BECN bit
+32-51 DLID (lower 20 bits)
+52-56 SC (Service Class)
+57-59 RC (Routing Control)
+60 FECN bit
+61-62 L2 (=10, 16B format)
+63 LT (=1, Link Transfer Head Flit)
Quad Word 1:
-0-7 L4 type (=0x78 ETHERNET)
-8-11 SLID[23:20]
-12-15 DLID[23:20]
-16-31 PKEY
-32-47 Entropy
-48-63 Reserved
+0-7 L4 type (=0x78 ETHERNET)
+8-11 SLID[23:20]
+12-15 DLID[23:20]
+16-31 PKEY
+32-47 Entropy
+48-63 Reserved
Quad Word 2:
-0-15 Reserved
-16-31 L4 header
-32-63 Ethernet Packet
+0-15 Reserved
+16-31 L4 header
+32-63 Ethernet Packet
Quad Words 3 to N-1:
-0-63 Ethernet packet (pad extended)
+0-63 Ethernet packet (pad extended)
Quad Word N (last):
-0-23 Ethernet packet (pad extended)
-24-55 ICRC
-56-61 Tail
-62-63 LT (=01, Link Transfer Tail Flit)
+0-23 Ethernet packet (pad extended)
+24-55 ICRC
+56-61 Tail
+62-63 LT (=01, Link Transfer Tail Flit)
+==================== ================================
Ethernet packet is padded on the transmit side to ensure that the VNIC OPA
packet is quad word aligned. The 'Tail' field contains the number of bytes
@@ -123,7 +129,7 @@ operation. It also handles the encapsulation of Ethernet packets with an
Omni-Path header in the transmit path. For each VNIC interface, the
information required for encapsulation is configured by the EM via VEMA MAD
interface. It also passes any control information to the HW dependent driver
-by invoking the RDMA netdev control operations.
+by invoking the RDMA netdev control operations::
+-------------------+ +----------------------+
| | | Linux |
diff --git a/Documentation/infiniband/sysfs.txt b/Documentation/infiniband/sysfs.rst
similarity index 69%
rename from Documentation/infiniband/sysfs.txt
rename to Documentation/infiniband/sysfs.rst
index 9fab5062f84b..f0abd6fa48f4 100644
--- a/Documentation/infiniband/sysfs.txt
+++ b/Documentation/infiniband/sysfs.rst
@@ -1,4 +1,6 @@
-SYSFS FILES
+===========
+Sysfs files
+===========
The sysfs interface has moved to
Documentation/ABI/stable/sysfs-class-infiniband.
diff --git a/Documentation/infiniband/tag_matching.txt b/Documentation/infiniband/tag_matching.rst
similarity index 98%
rename from Documentation/infiniband/tag_matching.txt
rename to Documentation/infiniband/tag_matching.rst
index d2a3bf819226..ef56ea585f92 100644
--- a/Documentation/infiniband/tag_matching.txt
+++ b/Documentation/infiniband/tag_matching.rst
@@ -1,12 +1,16 @@
+==================
Tag matching logic
+==================
The MPI standard defines a set of rules, known as tag-matching, for matching
source send operations to destination receives. The following parameters must
match the following source and destination parameters:
+
* Communicator
* User tag - wild card may be specified by the receiver
* Source rank – wild car may be specified by the receiver
* Destination rank – wild
+
The ordering rules require that when more than one pair of send and receive
message envelopes may match, the pair that includes the earliest posted-send
and the earliest posted-receive is the pair that must be used to satisfy the
@@ -35,6 +39,7 @@ the header to initiate an RDMA READ operation directly to the matching buffer.
A fin message needs to be received in order for the buffer to be reused.
Tag matching implementation
+===========================
There are two types of matching objects used, the posted receive list and the
unexpected message list. The application posts receive buffers through calls
diff --git a/Documentation/infiniband/user_mad.txt b/Documentation/infiniband/user_mad.rst
similarity index 90%
rename from Documentation/infiniband/user_mad.txt
rename to Documentation/infiniband/user_mad.rst
index 7aca13a54a3a..d88abfc0e370 100644
--- a/Documentation/infiniband/user_mad.txt
+++ b/Documentation/infiniband/user_mad.rst
@@ -1,6 +1,9 @@
-USERSPACE MAD ACCESS
+====================
+Userspace MAD access
+====================
Device files
+============
Each port of each InfiniBand device has a "umad" device and an
"issm" device attached. For example, a two-port HCA will have two
@@ -8,12 +11,13 @@ Device files
device of each type (for switch port 0).
Creating MAD agents
+===================
A MAD agent can be created by filling in a struct ib_user_mad_reg_req
and then calling the IB_USER_MAD_REGISTER_AGENT ioctl on a file
descriptor for the appropriate device file. If the registration
request succeeds, a 32-bit id will be returned in the structure.
- For example:
+ For example::
struct ib_user_mad_reg_req req = { /* ... */ };
ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req);
@@ -26,12 +30,14 @@ Creating MAD agents
ioctl. Also, all agents registered through a file descriptor will
be unregistered when the descriptor is closed.
- 2014 -- a new registration ioctl is now provided which allows additional
+ 2014
+ a new registration ioctl is now provided which allows additional
fields to be provided during registration.
Users of this registration call are implicitly setting the use of
pkey_index (see below).
Receiving MADs
+==============
MADs are received using read(). The receive side now supports
RMPP. The buffer passed to read() must be at least one
@@ -41,7 +47,8 @@ Receiving MADs
MAD (RMPP), the errno is set to ENOSPC and the length of the
buffer needed is set in mad.length.
- Example for normal MAD (non RMPP) reads:
+ Example for normal MAD (non RMPP) reads::
+
struct ib_user_mad *mad;
mad = malloc(sizeof *mad + 256);
ret = read(fd, mad, sizeof *mad + 256);
@@ -50,7 +57,8 @@ Receiving MADs
free(mad);
}
- Example for RMPP reads:
+ Example for RMPP reads::
+
struct ib_user_mad *mad;
mad = malloc(sizeof *mad + 256);
ret = read(fd, mad, sizeof *mad + 256);
@@ -76,11 +84,12 @@ Receiving MADs
poll()/select() may be used to wait until a MAD can be read.
Sending MADs
+============
MADs are sent using write(). The agent ID for sending should be
filled into the id field of the MAD, the destination LID should be
filled into the lid field, and so on. The send side does support
- RMPP so arbitrary length MAD can be sent. For example:
+ RMPP so arbitrary length MAD can be sent. For example::
struct ib_user_mad *mad;
@@ -97,6 +106,7 @@ Sending MADs
perror("write");
Transaction IDs
+===============
Users of the umad devices can use the lower 32 bits of the
transaction ID field (that is, the least significant half of the
@@ -105,6 +115,7 @@ Transaction IDs
the kernel and will be overwritten before a MAD is sent.
P_Key Index Handling
+====================
The old ib_umad interface did not allow setting the P_Key index for
MADs that are sent and did not provide a way for obtaining the P_Key
@@ -119,6 +130,7 @@ P_Key Index Handling
default, and the IB_USER_MAD_ENABLE_PKEY ioctl will be removed.
Setting IsSM Capability Bit
+===========================
To set the IsSM capability bit for a port, simply open the
corresponding issm device file. If the IsSM bit is already set,
@@ -129,25 +141,26 @@ Setting IsSM Capability Bit
the issm file.
/dev files
+==========
To create the appropriate character device files automatically with
- udev, a rule like
+ udev, a rule like::
KERNEL=="umad*", NAME="infiniband/%k"
KERNEL=="issm*", NAME="infiniband/%k"
- can be used. This will create device nodes named
+ can be used. This will create device nodes named::
/dev/infiniband/umad0
/dev/infiniband/issm0
for the first port, and so on. The InfiniBand device and port
- associated with these devices can be determined from the files
+ associated with these devices can be determined from the files::
/sys/class/infiniband_mad/umad0/ibdev
/sys/class/infiniband_mad/umad0/port
- and
+ and::
/sys/class/infiniband_mad/issm0/ibdev
/sys/class/infiniband_mad/issm0/port
diff --git a/Documentation/infiniband/user_verbs.txt b/Documentation/infiniband/user_verbs.rst
similarity index 93%
rename from Documentation/infiniband/user_verbs.txt
rename to Documentation/infiniband/user_verbs.rst
index 47ebf2f80b2b..8ddc4b1cfef2 100644
--- a/Documentation/infiniband/user_verbs.txt
+++ b/Documentation/infiniband/user_verbs.rst
@@ -1,4 +1,6 @@
-USERSPACE VERBS ACCESS
+======================
+Userspace verbs access
+======================
The ib_uverbs module, built by enabling CONFIG_INFINIBAND_USER_VERBS,
enables direct userspace access to IB hardware via "verbs," as
@@ -13,6 +15,7 @@ USERSPACE VERBS ACCESS
libmthca userspace driver be installed.
User-kernel communication
+=========================
Userspace communicates with the kernel for slow path, resource
management operations via the /dev/infiniband/uverbsN character
@@ -28,6 +31,7 @@ User-kernel communication
system call.
Resource management
+===================
Since creation and destruction of all IB resources is done by
commands passed through a file descriptor, the kernel can keep track
@@ -41,6 +45,7 @@ Resource management
prevent one process from touching another process's resources.
Memory pinning
+==============
Direct userspace I/O requires that memory regions that are potential
I/O targets be kept resident at the same physical address. The
@@ -54,13 +59,14 @@ Memory pinning
number of pages pinned by a process.
/dev files
+==========
To create the appropriate character device files automatically with
- udev, a rule like
+ udev, a rule like::
KERNEL=="uverbs*", NAME="infiniband/%k"
- can be used. This will create device nodes named
+ can be used. This will create device nodes named::
/dev/infiniband/uverbs0
diff --git a/drivers/infiniband/core/user_mad.c b/drivers/infiniband/core/user_mad.c
index 671f07ba1fad..5ecd370e018b 100644
--- a/drivers/infiniband/core/user_mad.c
+++ b/drivers/infiniband/core/user_mad.c
@@ -744,7 +744,7 @@ static int ib_umad_reg_agent(struct ib_umad_file *file, void __user *arg,
"process %s did not enable P_Key index support.\n",
current->comm);
dev_warn(&file->port->dev,
- " Documentation/infiniband/user_mad.txt has info on the new ABI.\n");
+ " Documentation/infiniband/user_mad.rst has info on the new ABI.\n");
}
}
diff --git a/drivers/infiniband/ulp/ipoib/Kconfig b/drivers/infiniband/ulp/ipoib/Kconfig
index 4760ce465d89..7af68604af77 100644
--- a/drivers/infiniband/ulp/ipoib/Kconfig
+++ b/drivers/infiniband/ulp/ipoib/Kconfig
@@ -7,7 +7,7 @@ config INFINIBAND_IPOIB
transports IP packets over InfiniBand so you can use your IB
device as a fancy NIC.
- See Documentation/infiniband/ipoib.txt for more information
+ See Documentation/infiniband/ipoib.rst for more information
config INFINIBAND_IPOIB_CM
bool "IP-over-InfiniBand Connected Mode support"
--
2.21.0
On Sat, Jun 08, 2019 at 11:27:09PM -0300, Mauro Carvalho Chehab wrote:
> 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 <[email protected]>
Acked-by: Dominik Brodowski <[email protected]>
Thanks,
Dominik
On Sun, Jun 9, 2019 at 4:27 AM Mauro Carvalho Chehab
<[email protected]> wrote:
> 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 <[email protected]>
> arch/m68k/q40/README | 2 +-
Acked-by: Geert Uytterhoeven <[email protected]>
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
Hi Mauro,
On Sun, Jun 9, 2019 at 4:29 AM Mauro Carvalho Chehab
<[email protected]> wrote:
> 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 <[email protected]>
Thanks!
> --- a/Documentation/fb/framebuffer.txt
> +++ b/Documentation/fb/framebuffer.rst
> @@ -1,5 +1,6 @@
> - The Frame Buffer Device
> - -----------------------
> +=======================
> +The Frame Buffer Device
> +=======================
>
> Maintained by Geert Uytterhoeven <[email protected]>
I'm happy to see this line dropped ;-)
> Last revised: May 10, 2001
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
On Sat, Jun 08, 2019 at 11:26:50PM -0300, Mauro Carvalho Chehab wrote:
> 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
>
> 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/
Will there be a web page (e.g. kernel.org), which contains always the
latest upstream version?
> docs: Debugging390.txt: convert table to ascii artwork
> docs: s390: convert docs to ReST and rename to *.rst
> s390: include/asm/debug.h add kerneldoc markups
I can pick these up for s390. Or do you want to send the whole series
in one go upstream?
Am 09.06.19 um 11:16 schrieb Heiko Carstens:
> Will there be a web page (e.g. kernel.org), which contains always the
> latest upstream version?
You are looking for the HTML docs on kernel.org?
https://www.kernel.org/doc/html/latest/
-- Markus --
On Sun, Jun 09, 2019 at 11:22:36AM +0200, Markus Heiser wrote:
>
> Am 09.06.19 um 11:16 schrieb Heiko Carstens:
> >Will there be a web page (e.g. kernel.org), which contains always the
> >latest upstream version?
>
> You are looking for the HTML docs on kernel.org?
>
> https://www.kernel.org/doc/html/latest/
Yes, thanks!
On 09/06/2019 04:27, Mauro Carvalho Chehab wrote:
> 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 <[email protected]>
Acked-by: Rodolfo Giometti <[email protected]>
--
GNU/Linux Solutions e-mail: [email protected]
Linux Device Driver [email protected]
Embedded Systems phone: +39 349 2432127
UNIX programming skype: rodolfo.giometti
Em Sun, 9 Jun 2019 11:16:43 +0200
Heiko Carstens <[email protected]> escreveu:
> On Sat, Jun 08, 2019 at 11:26:50PM -0300, Mauro Carvalho Chehab wrote:
> > 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
> >
> > 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/
>
> Will there be a web page (e.g. kernel.org), which contains always the
> latest upstream version?
Yes:
https://www.kernel.org/doc/html/latest/
I guess this one is based on Linus tree.
Jon also maintains a version at:
https://static.lwn.net/kerneldoc/
I guess that one is based on docs-next branch from the Docs tree.
Btw, if you want to build it for yourself, you could use:
make htmldocs
If your system doesn't have all dependencies, it will give the
hints about how to install them.
>
> > docs: Debugging390.txt: convert table to ascii artwork
> > docs: s390: convert docs to ReST and rename to *.rst
> > s390: include/asm/debug.h add kerneldoc markups
>
> I can pick these up for s390. Or do you want to send the whole series
> in one go upstream?
Yeah, feel free to pick them via the s390 tree.
Regards,
Mauro
Thanks,
Mauro
Thanks,
Mauro
On Sat, Jun 08, 2019 at 11:27:20PM -0300, Mauro Carvalho Chehab wrote:
> 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.
>
> Cc: Mauro Carvalho Chehab <[email protected]>, [email protected], Jonathan Corbet <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Guenter Roeck <[email protected]>
> ---
> .../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 ++-
> ...parameters.txt => watchdog-parameters.rst} | 672 +++++++++++++-----
> .../{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 +-
> 15 files changed, 767 insertions(+), 316 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%)
> rename Documentation/watchdog/{watchdog-parameters.txt => watchdog-parameters.rst} (42%)
> 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 <[email protected]>
> -=========================================================
>
> 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
> [email protected]. 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 <[email protected]>
> +Support for ISA Cards Revision A and C
> +=======================================
> +
> +Documentation and Driver by Ken Hollis <[email protected]>
>
> 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
> ([email protected])
> -
> 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 <[email protected]>
>
> @@ -10,7 +13,8 @@ driver which is (c) Copyright 2000 Jakob Oestergaard <[email protected]>
>
> 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 <[email protected]>
> @@ -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.txt b/Documentation/watchdog/watchdog-parameters.rst
> similarity index 42%
> rename from Documentation/watchdog/watchdog-parameters.txt
> rename to Documentation/watchdog/watchdog-parameters.rst
> index 0b88e333f9e1..b121caae7798 100644
> --- a/Documentation/watchdog/watchdog-parameters.txt
> +++ b/Documentation/watchdog/watchdog-parameters.rst
> @@ -1,410 +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
> + 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
> + 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
> + 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).
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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)
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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)
> + 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
> + 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')
> + 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
> + 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
> + 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
> + 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.
> + heartbeat:
> + Watchdog heartbeat in seconds.
> (2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> iTCO_vendor_support:
> -vendorsupport: iTCO vendor specific support mode, default=0 (none),
> + 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
> + 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
> + 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
> + 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
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> iop_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -action: after watchdog resets, generate:
> + 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
> + 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
> + nodelay:
> + Force selection of a timeout setting without initial delay
> (max6373/74 only, default=0)
> +
> -------------------------------------------------
> +
> mixcomwd:
> -nowayout: Watchdog cannot be stopped once started
> + 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
> + 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
> + 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
> + 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
> + 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.
> + heartbeat:
> + Watchdog heartbeats in seconds.
> (default = 15)
> -nowayout: Watchdog cannot be stopped once started
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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)
> + 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
> + 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)
> + 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
> + 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)
> + 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)
> + margin:
> + Watchdog margin in seconds (default 60s)
> +
> -------------------------------------------------
> +
> sb_wdog:
> -timeout: Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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,
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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)
> + 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
> + 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
> + 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.
> + soft_margin:
> + Watchdog soft_margin in seconds.
> (0 < soft_margin < 65536, default=60)
> -nowayout: Watchdog cannot be stopped once started
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> -soft_noboot: Softdog action, set to 1 to ignore reboots, 0 to reboot
> + 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
> + 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
> + 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
> + 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
> + 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
> + 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.
> + timeout:
> + Watchdog timeout in power of two seconds.
> (1 <= timeout <= 128, default=64)
> -nowayout: Watchdog cannot be stopped once started
> + 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
> + 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
> + 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
> + 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
> + 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)
> + 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
> + 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
> + nowayout:
> + Watchdog cannot be stopped once started
> (default=kernel config parameter)
> +
> -------------------------------------------------
> +
> wm8350_wdt:
> -nowayout: Watchdog cannot be stopped once started
> + 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
> --------------------------------------------------
> + 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 <[email protected]>
> @@ -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 <[email protected]>
> +Alan Cox <[email protected]>
>
> - 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 08efe50266b5..a9abccb2644b 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7027,7 +7027,7 @@ F: drivers/media/usb/hdpvr/
> HEWLETT PACKARD ENTERPRISE ILO NMI WATCHDOG DRIVER
> M: Jerry Hoemann <[email protected]>
> 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
On Sun, Jun 9, 2019 at 4:30 AM Mauro Carvalho Chehab
<[email protected]> wrote:
>
> 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 <[email protected]>
I have said "no" to this already twice.
How many times do I still need to repeat that?
There already is some cpufreq documentation under admin-guide in the
.rst format and the rest is obsolete. It is going to be replaced with
something new and more up to date.
The API docs need to go under driver-api and conversions like this
don't help. Indeed, they are counter-prodictive in my view.
DIsappointed,
Rafael
Em Sun, 9 Jun 2019 23:38:32 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:
> On Sun, Jun 9, 2019 at 4:30 AM Mauro Carvalho Chehab
> <[email protected]> wrote:
> >
> > 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 <[email protected]>
>
> I have said "no" to this already twice.
I'm really sorry, I forgot to drop it. It is gone now from:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v4.1&ofs=50
Thanks,
Mauro
On Sun, Jun 09, 2019 at 09:29:40AM -0300, Mauro Carvalho Chehab wrote:
> Em Sun, 9 Jun 2019 11:16:43 +0200
> > Will there be a web page (e.g. kernel.org), which contains always the
> > latest upstream version?
>
> Yes:
>
> https://www.kernel.org/doc/html/latest/
>
> I guess this one is based on Linus tree.
>
> Jon also maintains a version at:
>
> https://static.lwn.net/kerneldoc/
>
> I guess that one is based on docs-next branch from the Docs tree.
>
> Btw, if you want to build it for yourself, you could use:
>
> make htmldocs
Thanks a lot!
> > I can pick these up for s390. Or do you want to send the whole series
> > in one go upstream?
>
> Yeah, feel free to pick them via the s390 tree.
Ok, applied! :)
In data Sunday, June 9, 2019 4:26:59 AM CEST, Mauro Carvalho Chehab ha
scritto:
> 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 <[email protected]>
> ---
> ...ault-injection.txt => fault-injection.rst} | 265 +++++++++---------
> Documentation/fault-injection/index.rst | 20 ++
> ...r-inject.txt => notifier-error-inject.rst} | 18 +-
> ...injection.txt => nvme-fault-injection.rst} | 174 ++++++------
> ...rovoke-crashes.txt => provoke-crashes.rst} | 40 ++-
> Documentation/process/4.Coding.rst | 2 +-
> .../translations/it_IT/process/4.Coding.rst | 2 +-
Limited to translations/it_IT
Acked-by: Federico Vaga <[email protected]>
> .../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 +-
> 12 files changed, 290 insertions(+), 241 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%) rename
> Documentation/fault-injection/{nvme-fault-injection.txt =>
> nvme-fault-injection.rst} (19%) rename
> Documentation/fault-injection/{provoke-crashes.txt => provoke-crashes.rst}
> (45%)
>
On Sat, Jun 08, 2019 at 11:27:03PM -0300, Mauro Carvalho Chehab wrote:
> The InfiniBand docs are plain text with no markups.
> So, all we needed to do were to add the title markups and
> some markup sequences in order to properly parse tables,
> lists and literal blocks.
>
> 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 <[email protected]>
> ---
> .../{core_locking.txt => core_locking.rst} | 64 ++++++-----
> Documentation/infiniband/index.rst | 23 ++++
> .../infiniband/{ipoib.txt => ipoib.rst} | 24 ++--
> .../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +++++++++---------
> .../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
> .../{tag_matching.txt => tag_matching.rst} | 5 +
> .../infiniband/{user_mad.txt => user_mad.rst} | 33 ++++--
> .../{user_verbs.txt => user_verbs.rst} | 12 +-
> drivers/infiniband/core/user_mad.c | 2 +-
> drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
> 10 files changed, 174 insertions(+), 103 deletions(-)
> rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
> create mode 100644 Documentation/infiniband/index.rst
> rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
> rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
> rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
> rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
> rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
> rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
Looks OK to me, do you want to run these patches through the docs tree
or through RDMA?
Given that we've generally pushed doc updates through rdma, I think
I'd prefer the latter? Jonathan?
Thanks,
Jason
On Mon, 10 Jun 2019 14:27:12 -0300
Jason Gunthorpe <[email protected]> wrote:
> Looks OK to me, do you want to run these patches through the docs tree
> or through RDMA?
>
> Given that we've generally pushed doc updates through rdma, I think
> I'd prefer the latter? Jonathan?
Whichever works best for you is fine with me; go ahead and take them.
jon
In data Sunday, June 9, 2019 4:27:06 AM CEST, Mauro Carvalho Chehab ha
scritto:
> 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 <[email protected]>
> ---
> Documentation/kernel-hacking/locking.rst | 2 +-
> Documentation/locking/index.rst | 24 ++
> ...{lockdep-design.txt => lockdep-design.rst} | 51 ++--
> .../locking/{lockstat.txt => lockstat.rst} | 221 ++++++++++--------
> .../{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 +-
Limited to translations/it_IT
Acked-by: Federico Vaga <[email protected]>
> 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 +-
> 19 files changed, 428 insertions(+), 304 deletions(-)
> create mode 100644 Documentation/locking/index.rst
> rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst}
> (93%) rename Documentation/locking/{lockstat.txt => lockstat.rst} (41%)
> 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%)
>
On Sat, Jun 08, 2019 at 11:27:23PM -0300, Mauro Carvalho Chehab wrote:
> 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.
Yes, but there's a bit a twist: This is definitely end-user documentation,
so maybe should be in admin-guide?
Atm all we have in Documentation/gpu/ is internals for drivers + some
beginnings of uapi documentation for userspace developers.
Jon, what's your recommendation here for subsystem specific
end-user/adming docs?
Thanks, Daniel
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> 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
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
Em Tue, 11 Jun 2019 10:37:31 +0200
Daniel Vetter <[email protected]> escreveu:
> On Sat, Jun 08, 2019 at 11:27:23PM -0300, Mauro Carvalho Chehab wrote:
> > 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.
>
> Yes, but there's a bit a twist: This is definitely end-user documentation,
> so maybe should be in admin-guide?
>
> Atm all we have in Documentation/gpu/ is internals for drivers + some
> beginnings of uapi documentation for userspace developers.
On media, we have several different types of documents:
- uAPI - consumed by both userspace and kernelspace developers;
- kAPI - consumed by Kernel hackers;
- driver-specific information. Those are usually messy, as some contain
specific internal details, while others are pure end-user documentation.
there are several cross-references between uAPI and kAPI parts.
I've seem similar patterns on several other driver subsystems.
I agree with Jon's principle that the best is to focus the book per
audience. Yet, trying to rearrange the documentation means a lot of work,
specially on those cases where a single file contain different types of
documentation, like on media driver docs.
> Jon, what's your recommendation here for subsystem specific
> end-user/adming docs?
Jon, please correct me if I' wrong, bu I guess the plan is to place them
somewhere under Documentation/admin-guide/.
If so, perhaps creating a Documentation/admin-guide/drm dir there and
place docs like EDID/HOWTO.txt, svga.txt, etc would work.
Btw, that's one of the reasons[1] why I opted to keep the files where they
are: properly organizing the converted documents call for such kind
of discussions. On my experience, discussing names and directory locations
can generate warm discussions and take a lot of time to reach consensus.
[1] The other one is to avoid/simplify merge conflicts.
>
> Thanks, Daniel
>
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > 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
> >
>
Thanks,
Mauro
On Tue, Jun 11, 2019 at 06:02:15AM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 11 Jun 2019 10:37:31 +0200
> Daniel Vetter <[email protected]> escreveu:
>
> > On Sat, Jun 08, 2019 at 11:27:23PM -0300, Mauro Carvalho Chehab wrote:
> > > 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.
> >
> > Yes, but there's a bit a twist: This is definitely end-user documentation,
> > so maybe should be in admin-guide?
> >
> > Atm all we have in Documentation/gpu/ is internals for drivers + some
> > beginnings of uapi documentation for userspace developers.
>
> On media, we have several different types of documents:
>
> - uAPI - consumed by both userspace and kernelspace developers;
> - kAPI - consumed by Kernel hackers;
> - driver-specific information. Those are usually messy, as some contain
> specific internal details, while others are pure end-user documentation.
>
> there are several cross-references between uAPI and kAPI parts.
>
> I've seem similar patterns on several other driver subsystems.
>
> I agree with Jon's principle that the best is to focus the book per
> audience. Yet, trying to rearrange the documentation means a lot of work,
> specially on those cases where a single file contain different types of
> documentation, like on media driver docs.
Yeah atm we're doing a bad job of keeping the kapi and uapi parts
separate. But the plan at least is to move all the gpu related uapi stuff
into Documentation/gpu/drm-uapi.rst. Not sure there's value in moving that
out of the gpu folder ...
> > Jon, what's your recommendation here for subsystem specific
> > end-user/adming docs?
>
> Jon, please correct me if I' wrong, bu I guess the plan is to place them
> somewhere under Documentation/admin-guide/.
>
> If so, perhaps creating a Documentation/admin-guide/drm dir there and
> place docs like EDID/HOWTO.txt, svga.txt, etc would work.
>
> Btw, that's one of the reasons[1] why I opted to keep the files where they
> are: properly organizing the converted documents call for such kind
> of discussions. On my experience, discussing names and directory locations
> can generate warm discussions and take a lot of time to reach consensus.
>
> [1] The other one is to avoid/simplify merge conflicts.
Oh definitely not asking for moving them at the same time, just wondering
how this should be solved properly.
-Daniel
>
> >
> > Thanks, Daniel
> >
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > > ---
> > > 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
> > >
> >
>
>
>
> Thanks,
> Mauro
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
On Tue, 11 Jun 2019 06:02:15 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> Jon, please correct me if I' wrong, bu I guess the plan is to place them
> somewhere under Documentation/admin-guide/.
That makes sense to me.
> If so, perhaps creating a Documentation/admin-guide/drm dir there and
> place docs like EDID/HOWTO.txt, svga.txt, etc would work.
Maybe "graphics" or "display" rather than "drm", which may not entirely
applicable to all of those docs or as familiar to all admins?
> Btw, that's one of the reasons[1] why I opted to keep the files where they
> are: properly organizing the converted documents call for such kind
> of discussions. On my experience, discussing names and directory locations
> can generate warm discussions and take a lot of time to reach consensus.
Moving docs is a pain; my life would certainly be easier if I were happy
to just let everything lie where it fell :) But it's far from the hardest
problem we solve in kernel development, I assume we can figure it out.
Thanks,
jon
On Sat, Jun 08, 2019 at 11:26:55PM -0300, Mauro Carvalho Chehab 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 <[email protected]>
Acked-by: Tejun Heo <[email protected]>
Please feel free to route with the rest of the series. If you want
the patch to be routed through the cgroup tree, please let me know.
Thanks.
--
tejun
On Sat, Jun 8, 2019 at 10:27 PM Mauro Carvalho Chehab
<[email protected]> wrote:
>
> 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 <[email protected]>
> ---
> .../{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%)
I'm fairly confident I've already acked this at least once, but here
it is again:
Acked-by: Paul Moore <[email protected]>
> 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, [email protected]
>
> 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, [email protected]
>
> 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, [email protected]
>
> 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
>
--
paul moore
http://www.paul-moore.com
Em Tue, 11 Jun 2019 09:37:01 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Tue, 11 Jun 2019 06:02:15 -0300
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > Jon, please correct me if I' wrong, bu I guess the plan is to place them
> > somewhere under Documentation/admin-guide/.
>
> That makes sense to me.
>
> > If so, perhaps creating a Documentation/admin-guide/drm dir there and
> > place docs like EDID/HOWTO.txt, svga.txt, etc would work.
>
> Maybe "graphics" or "display" rather than "drm", which may not entirely
> applicable to all of those docs or as familiar to all admins?
It is up to Daniel/David to decide. Personally, I agree with you that
either "graphics" or "display" would be better at the admin guide.
>
> > Btw, that's one of the reasons[1] why I opted to keep the files where they
> > are: properly organizing the converted documents call for such kind
> > of discussions. On my experience, discussing names and directory locations
> > can generate warm discussions and take a lot of time to reach consensus.
>
> Moving docs is a pain; my life would certainly be easier if I were happy
> to just let everything lie where it fell :) But it's far from the hardest
> problem we solve in kernel development, I assume we can figure it out.
Yeah, it is doable. I'm happy to write the rename patches and even try
to split some documents at the places I'm more familiar with, but, IMHO,
we should do some discussions before some of such renames.
For example, Daniel said that:
> > > Yeah atm we're doing a bad job of keeping the kapi and uapi parts
> > > separate. But the plan at least is to move all the gpu related uapi stuff
> > > into Documentation/gpu/drm-uapi.rst. Not sure there's value in moving that
> > > out of the gpu folder ...
From the conversions I've made so far, almost all driver subsystems
put everything under Documentation/<subsystem: kAPI, uAPI, admin info,
driver-specific technical info.
It should be doable to place kAPI and uAPI on different books, but there
will be lots of cross-reference links between them, on properly-written
docs.
However, other admin-guide stuff under drivers are usually in the middle
of the documents. For example, on media, we have some at the uAPI guide,
like the Device Naming item:
https://linuxtv.org/downloads/v4l-dvb-apis-new/uapi/v4l/open.html#device-naming
But splitting it from uAPI guide is not an easy task.
At the driver's specific documentation is even messier.
Ok, splitting is doable, but require lots of dedication, and I'm not
convinced if it would make much difference in practice.
Thanks,
Mauro
On Wed, Jun 12, 2019 at 7:40 PM Mauro Carvalho Chehab
<[email protected]> wrote:
>
> Em Tue, 11 Jun 2019 09:37:01 -0600
> Jonathan Corbet <[email protected]> escreveu:
>
> > On Tue, 11 Jun 2019 06:02:15 -0300
> > Mauro Carvalho Chehab <[email protected]> wrote:
> >
> > > Jon, please correct me if I' wrong, bu I guess the plan is to place them
> > > somewhere under Documentation/admin-guide/.
> >
> > That makes sense to me.
> >
> > > If so, perhaps creating a Documentation/admin-guide/drm dir there and
> > > place docs like EDID/HOWTO.txt, svga.txt, etc would work.
> >
> > Maybe "graphics" or "display" rather than "drm", which may not entirely
> > applicable to all of those docs or as familiar to all admins?
>
> It is up to Daniel/David to decide. Personally, I agree with you that
> either "graphics" or "display" would be better at the admin guide.
We use Documentation/gpu already for the developer guide, I think
going with "gpu" on the admin guide for consistency would be good. I
do personally think that splitting out the admin guide makes sense, we
could also put some recommendations about access rights for drm device
nodes and stuff like that in there.
> > > Btw, that's one of the reasons[1] why I opted to keep the files where they
> > > are: properly organizing the converted documents call for such kind
> > > of discussions. On my experience, discussing names and directory locations
> > > can generate warm discussions and take a lot of time to reach consensus.
> >
> > Moving docs is a pain; my life would certainly be easier if I were happy
> > to just let everything lie where it fell :) But it's far from the hardest
> > problem we solve in kernel development, I assume we can figure it out.
>
> Yeah, it is doable. I'm happy to write the rename patches and even try
> to split some documents at the places I'm more familiar with, but, IMHO,
> we should do some discussions before some of such renames.
>
> For example, Daniel said that:
>
> > > > Yeah atm we're doing a bad job of keeping the kapi and uapi parts
> > > > separate. But the plan at least is to move all the gpu related uapi stuff
> > > > into Documentation/gpu/drm-uapi.rst. Not sure there's value in moving that
> > > > out of the gpu folder ...
>
> From the conversions I've made so far, almost all driver subsystems
> put everything under Documentation/<subsystem: kAPI, uAPI, admin info,
> driver-specific technical info.
>
> It should be doable to place kAPI and uAPI on different books, but there
> will be lots of cross-reference links between them, on properly-written
> docs.
I'm not sure it makes sense to split out the kapi and uapi sides of
the docs complete. For the admin guide I think one overall book
covering all subsystems is good. But someone creating a drm/kms
compositor is not going to be interested much into some special
options for networking protocol I think. For those I think focusing
more on the specific subsystem makes more sense (and easier to share
common concepts/diagrams between uapi and kapi of a given subsystem).
I do think for a given subsystem the uapi side should be clearly split
out (otherwise it's impossible to find for non-kernel people). And
currently drm falls short really badly on this. So maybe a good
argument for a uapi kernel directory would be to force that, but not
sure that's good enough of a reason.
-Daniel
> However, other admin-guide stuff under drivers are usually in the middle
> of the documents. For example, on media, we have some at the uAPI guide,
> like the Device Naming item:
>
> https://linuxtv.org/downloads/v4l-dvb-apis-new/uapi/v4l/open.html#device-naming
>
> But splitting it from uAPI guide is not an easy task.
>
> At the driver's specific documentation is even messier.
>
> Ok, splitting is doable, but require lots of dedication, and I'm not
> convinced if it would make much difference in practice.
>
> Thanks,
> Mauro
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
On Sat, Jun 08, 2019 at 11:27:03PM -0300, Mauro Carvalho Chehab wrote:
> The InfiniBand docs are plain text with no markups.
> So, all we needed to do were to add the title markups and
> some markup sequences in order to properly parse tables,
> lists and literal blocks.
>
> 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 <[email protected]>
> ---
> .../{core_locking.txt => core_locking.rst} | 64 ++++++-----
> Documentation/infiniband/index.rst | 23 ++++
> .../infiniband/{ipoib.txt => ipoib.rst} | 24 ++--
> .../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +++++++++---------
> .../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
> .../{tag_matching.txt => tag_matching.rst} | 5 +
> .../infiniband/{user_mad.txt => user_mad.rst} | 33 ++++--
> .../{user_verbs.txt => user_verbs.rst} | 12 +-
> drivers/infiniband/core/user_mad.c | 2 +-
> drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
> 10 files changed, 174 insertions(+), 103 deletions(-)
> rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
> create mode 100644 Documentation/infiniband/index.rst
> rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
> rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
> rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
> rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
> rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
> rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
Applied to for-next, thanks
Jason