This is mostly a rebase of the /33 series v3 I sent, on the top of the latest
linux-next (next-20190612).
Changes from v3:
- dropped cpufreq conversion - documents are too outdated;
- infiniband patch is not here anymore - as it should be merged via RDMA;
- s390 patches were already merged;
- Dropped Geert as Maintainer from fb/framebuffer.rst, as per his request;
- Did a minor editorial change at popwerpc/cxl.rst per Andrew Donellan
request;
- Added acks/reviews;
- trivial rebase fixups.
Jon,
the first version of this series was sent back on April, 15. So, I
suspect it should be fine to merge those patches via docs tree.
I should be sending soon the next part of this conversion series.
-
This is the first part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, this series is based on today's docs-next
+ linux-next, at tag next-20190607.
I have right now about 85 patches with this undergoing work. That's
because I opted to do ~1 patch per converted directory.
That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts. Those patches should probably be good to be merged
either by subsystem maintainers or via the docs tree.
I opted to mark new files not included yet to the main index.rst (directly or
indirectly ) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement.
Both this series and the next parts are on my devel git tree,
at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v4.2
The final output in html (after all patches I currently have, including
the upcoming series) can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
Mauro Carvalho Chehab (28):
docs: aoe: convert docs to ReST and rename to *.rst
docs: arm64: convert docs to ReST and rename to .rst
docs: cdrom-standard.tex: convert from LaTeX to ReST
docs: cdrom: convert docs to ReST and rename to *.rst
docs: cgroup-v1: convert docs to ReST and rename to *.rst
docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
docs: convert docs to ReST and rename to *.rst
docs: fault-injection: convert docs to ReST and rename to *.rst
docs: fb: convert docs to ReST and rename to *.rst
docs: fpga: convert docs to ReST and rename to *.rst
docs: ide: convert docs to ReST and rename to *.rst
docs: kbuild: convert docs to ReST and rename to *.rst
docs: kdump: convert docs to ReST and rename to *.rst
docs: locking: convert docs to ReST and rename to *.rst
docs: mic: convert docs to ReST and rename to *.rst
docs: netlabel: convert docs to ReST and rename to *.rst
docs: pcmcia: convert docs to ReST and rename to *.rst
docs: convert docs to ReST and rename to *.rst
docs: powerpc: convert docs to ReST and rename to *.rst
docs: pps.txt: convert to ReST and rename to pps.rst
docs: ptp.txt: convert to ReST and move to driver-api
docs: riscv: convert docs to ReST and rename to *.rst
docs: target: convert docs to ReST and rename to *.rst
docs: timers: convert docs to ReST and rename to *.rst
docs: watchdog: convert docs to ReST and rename to *.rst
docs: xilinx: convert eemi.txt to eemi.rst
docs: scheduler: convert docs to ReST and rename to *.rst
docs: EDID/HOWTO.txt: convert it and rename to howto.rst
.../ABI/testing/sysfs-class-powercap | 2 +-
Documentation/ABI/testing/sysfs-kernel-uids | 2 +-
Documentation/EDID/{HOWTO.txt => howto.rst} | 31 +-
Documentation/PCI/pci-error-recovery.rst | 23 +-
Documentation/admin-guide/README.rst | 2 +-
Documentation/admin-guide/bug-hunting.rst | 2 +-
Documentation/admin-guide/hw-vuln/l1tf.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 24 +-
.../admin-guide/mm/numa_memory_policy.rst | 2 +-
Documentation/aoe/{aoe.txt => aoe.rst} | 63 +-
Documentation/aoe/examples.rst | 23 +
Documentation/aoe/index.rst | 19 +
Documentation/aoe/{todo.txt => todo.rst} | 3 +
Documentation/aoe/udev.txt | 2 +-
...object_usage.txt => acpi_object_usage.rst} | 288 +++--
.../arm64/{arm-acpi.txt => arm-acpi.rst} | 155 +--
.../arm64/{booting.txt => booting.rst} | 91 +-
...egisters.txt => cpu-feature-registers.rst} | 204 ++--
.../arm64/{elf_hwcaps.txt => elf_hwcaps.rst} | 56 +-
.../{hugetlbpage.txt => hugetlbpage.rst} | 7 +-
Documentation/arm64/index.rst | 28 +
...structions.txt => legacy_instructions.rst} | 43 +-
Documentation/arm64/memory.rst | 98 ++
Documentation/arm64/memory.txt | 97 --
...ication.txt => pointer-authentication.rst} | 2 +
...{silicon-errata.txt => silicon-errata.rst} | 65 +-
Documentation/arm64/{sve.txt => sve.rst} | 12 +-
...agged-pointers.txt => tagged-pointers.rst} | 6 +-
Documentation/block/bfq-iosched.txt | 2 +-
Documentation/cdrom/Makefile | 21 -
Documentation/cdrom/cdrom-standard.rst | 1063 +++++++++++++++++
Documentation/cdrom/cdrom-standard.tex | 1026 ----------------
Documentation/cdrom/{ide-cd => ide-cd.rst} | 196 +--
Documentation/cdrom/index.rst | 19 +
...{packet-writing.txt => packet-writing.rst} | 27 +-
...io-controller.txt => blkio-controller.rst} | 103 +-
.../cgroup-v1/{cgroups.txt => cgroups.rst} | 184 +--
.../cgroup-v1/{cpuacct.txt => cpuacct.rst} | 15 +-
.../cgroup-v1/{cpusets.txt => cpusets.rst} | 205 ++--
.../cgroup-v1/{devices.txt => devices.rst} | 40 +-
...er-subsystem.txt => freezer-subsystem.rst} | 14 +-
.../cgroup-v1/{hugetlb.txt => hugetlb.rst} | 39 +-
Documentation/cgroup-v1/index.rst | 30 +
.../{memcg_test.txt => memcg_test.rst} | 263 ++--
.../cgroup-v1/{memory.txt => memory.rst} | 449 ++++---
.../cgroup-v1/{net_cls.txt => net_cls.rst} | 37 +-
.../cgroup-v1/{net_prio.txt => net_prio.rst} | 24 +-
.../cgroup-v1/{pids.txt => pids.rst} | 78 +-
.../cgroup-v1/{rdma.txt => rdma.rst} | 66 +-
Documentation/cpu-freq/core.txt | 2 +-
...{cache-policies.txt => cache-policies.rst} | 24 +-
.../device-mapper/{cache.txt => cache.rst} | 206 ++--
.../device-mapper/{delay.txt => delay.rst} | 29 +-
.../{dm-crypt.txt => dm-crypt.rst} | 57 +-
.../{dm-flakey.txt => dm-flakey.rst} | 45 +-
.../{dm-init.txt => dm-init.rst} | 75 +-
.../{dm-integrity.txt => dm-integrity.rst} | 62 +-
.../device-mapper/{dm-io.txt => dm-io.rst} | 14 +-
.../device-mapper/{dm-log.txt => dm-log.rst} | 5 +-
...m-queue-length.txt => dm-queue-length.rst} | 25 +-
.../{dm-raid.txt => dm-raid.rst} | 225 ++--
...m-service-time.txt => dm-service-time.rst} | 68 +-
Documentation/device-mapper/dm-uevent.rst | 110 ++
Documentation/device-mapper/dm-uevent.txt | 97 --
.../{dm-zoned.txt => dm-zoned.rst} | 10 +-
.../device-mapper/{era.txt => era.rst} | 36 +-
Documentation/device-mapper/index.rst | 44 +
.../device-mapper/{kcopyd.txt => kcopyd.rst} | 10 +-
Documentation/device-mapper/linear.rst | 63 +
Documentation/device-mapper/linear.txt | 61 -
.../{log-writes.txt => log-writes.rst} | 91 +-
...ersistent-data.txt => persistent-data.rst} | 4 +
.../{snapshot.txt => snapshot.rst} | 116 +-
.../{statistics.txt => statistics.rst} | 62 +-
Documentation/device-mapper/striped.rst | 61 +
Documentation/device-mapper/striped.txt | 57 -
.../device-mapper/{switch.txt => switch.rst} | 47 +-
...provisioning.txt => thin-provisioning.rst} | 68 +-
.../{unstriped.txt => unstriped.rst} | 111 +-
.../device-mapper/{verity.txt => verity.rst} | 20 +-
.../{writecache.txt => writecache.rst} | 13 +-
.../device-mapper/{zero.txt => zero.rst} | 14 +-
Documentation/driver-api/pm/devices.rst | 6 +-
.../{pps/pps.txt => driver-api/pps.rst} | 67 +-
.../{ptp/ptp.txt => driver-api/ptp.rst} | 26 +-
.../driver-api/usb/power-management.rst | 2 +-
...ault-injection.txt => fault-injection.rst} | 265 ++--
Documentation/fault-injection/index.rst | 20 +
...r-inject.txt => notifier-error-inject.rst} | 18 +-
.../fault-injection/nvme-fault-injection.rst | 120 ++
.../fault-injection/nvme-fault-injection.txt | 116 --
.../fault-injection/provoke-crashes.rst | 48 +
.../fault-injection/provoke-crashes.txt | 38 -
Documentation/fb/{api.txt => api.rst} | 29 +-
Documentation/fb/{arkfb.txt => arkfb.rst} | 8 +-
.../fb/{aty128fb.txt => aty128fb.rst} | 35 +-
.../fb/{cirrusfb.txt => cirrusfb.rst} | 47 +-
.../fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} | 57 +-
.../fb/{deferred_io.txt => deferred_io.rst} | 28 +-
Documentation/fb/{efifb.txt => efifb.rst} | 18 +-
.../fb/{ep93xx-fb.txt => ep93xx-fb.rst} | 27 +-
Documentation/fb/{fbcon.txt => fbcon.rst} | 177 +--
.../fb/{framebuffer.txt => framebuffer.rst} | 80 +-
Documentation/fb/{gxfb.txt => gxfb.rst} | 24 +-
Documentation/fb/index.rst | 50 +
.../fb/{intel810.txt => intel810.rst} | 79 +-
Documentation/fb/{intelfb.txt => intelfb.rst} | 62 +-
.../fb/{internals.txt => internals.rst} | 24 +-
Documentation/fb/{lxfb.txt => lxfb.rst} | 25 +-
Documentation/fb/matroxfb.rst | 443 +++++++
Documentation/fb/matroxfb.txt | 413 -------
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/pvr2fb.rst | 66 +
Documentation/fb/pvr2fb.txt | 65 -
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
Documentation/fb/sh7760fb.rst | 130 ++
Documentation/fb/sh7760fb.txt | 131 --
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/sstfb.rst | 207 ++++
Documentation/fb/sstfb.txt | 174 ---
Documentation/fb/{tgafb.txt => tgafb.rst} | 30 +-
.../fb/{tridentfb.txt => tridentfb.rst} | 36 +-
Documentation/fb/{udlfb.txt => udlfb.rst} | 55 +-
Documentation/fb/{uvesafb.txt => uvesafb.rst} | 128 +-
Documentation/fb/{vesafb.txt => vesafb.rst} | 121 +-
Documentation/fb/viafb.rst | 297 +++++
Documentation/fb/viafb.txt | 252 ----
.../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +-
Documentation/filesystems/tmpfs.txt | 2 +-
.../filesystems/ubifs-authentication.md | 4 +-
Documentation/fpga/{dfl.txt => dfl.rst} | 58 +-
Documentation/fpga/index.rst | 17 +
Documentation/ide/changelogs.rst | 17 +
.../ide/{ide-tape.txt => ide-tape.rst} | 23 +-
Documentation/ide/{ide.txt => ide.rst} | 147 +--
Documentation/ide/index.rst | 21 +
...arm-plug-howto.txt => warm-plug-howto.rst} | 10 +-
...eaders_install.txt => headers_install.rst} | 5 +-
Documentation/kbuild/index.rst | 27 +
Documentation/kbuild/issues.rst | 11 +
.../kbuild/{kbuild.txt => kbuild.rst} | 119 +-
...nfig-language.txt => kconfig-language.rst} | 232 ++--
...anguage.txt => kconfig-macro-language.rst} | 37 +-
.../kbuild/{kconfig.txt => kconfig.rst} | 136 ++-
.../kbuild/{makefiles.txt => makefiles.rst} | 530 +++++---
.../kbuild/{modules.txt => modules.rst} | 168 +--
Documentation/kdump/index.rst | 21 +
Documentation/kdump/{kdump.txt => kdump.rst} | 131 +-
.../kdump/{vmcoreinfo.txt => vmcoreinfo.rst} | 59 +-
Documentation/kernel-hacking/hacking.rst | 4 +-
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/kernel-per-CPU-kthreads.txt | 2 +-
Documentation/locking/index.rst | 24 +
...{lockdep-design.txt => lockdep-design.rst} | 51 +-
Documentation/locking/lockstat.rst | 204 ++++
Documentation/locking/lockstat.txt | 183 ---
.../{locktorture.txt => locktorture.rst} | 105 +-
.../{mutex-design.txt => mutex-design.rst} | 26 +-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++-
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +-
.../locking/{spinlocks.txt => spinlocks.rst} | 32 +-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +-
Documentation/mic/index.rst | 18 +
.../{mic_overview.txt => mic_overview.rst} | 6 +-
.../{scif_overview.txt => scif_overview.rst} | 58 +-
.../{cipso_ipv4.txt => cipso_ipv4.rst} | 19 +-
Documentation/netlabel/draft_ietf.rst | 5 +
Documentation/netlabel/index.rst | 21 +
.../{introduction.txt => introduction.rst} | 16 +-
.../{lsm_interface.txt => lsm_interface.rst} | 16 +-
Documentation/networking/timestamping.txt | 2 +-
.../{devicetable.txt => devicetable.rst} | 4 +
...{driver-changes.txt => driver-changes.rst} | 35 +-
.../pcmcia/{driver.txt => driver.rst} | 18 +-
Documentation/pcmcia/index.rst | 20 +
.../pcmcia/{locking.txt => locking.rst} | 39 +-
Documentation/pi-futex.txt | 2 +-
.../power/{apm-acpi.txt => apm-acpi.rst} | 10 +-
...m-debugging.txt => basic-pm-debugging.rst} | 79 +-
...harger-manager.txt => charger-manager.rst} | 101 +-
...rivers-testing.txt => drivers-testing.rst} | 15 +-
.../{energy-model.txt => energy-model.rst} | 101 +-
...ing-of-tasks.txt => freezing-of-tasks.rst} | 91 +-
Documentation/power/index.rst | 46 +
.../power/{interface.txt => interface.rst} | 24 +-
Documentation/power/{opp.txt => opp.rst} | 175 +--
Documentation/power/{pci.txt => pci.rst} | 87 +-
...qos_interface.txt => pm_qos_interface.rst} | 127 +-
Documentation/power/power_supply_class.rst | 282 +++++
Documentation/power/power_supply_class.txt | 231 ----
Documentation/power/powercap/powercap.rst | 257 ++++
Documentation/power/powercap/powercap.txt | 236 ----
.../regulator/{consumer.txt => consumer.rst} | 141 ++-
.../regulator/{design.txt => design.rst} | 9 +-
.../regulator/{machine.txt => machine.rst} | 47 +-
.../regulator/{overview.txt => overview.rst} | 57 +-
Documentation/power/regulator/regulator.rst | 32 +
Documentation/power/regulator/regulator.txt | 30 -
.../power/{runtime_pm.txt => runtime_pm.rst} | 234 ++--
Documentation/power/{s2ram.txt => s2ram.rst} | 20 +-
...hotplug.txt => suspend-and-cpuhotplug.rst} | 42 +-
...errupts.txt => suspend-and-interrupts.rst} | 2 +
...ap-files.txt => swsusp-and-swap-files.rst} | 17 +-
...{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} | 120 +-
Documentation/power/swsusp.rst | 501 ++++++++
Documentation/power/swsusp.txt | 446 -------
.../power/{tricks.txt => tricks.rst} | 6 +-
...serland-swsusp.txt => userland-swsusp.rst} | 55 +-
Documentation/power/{video.txt => video.rst} | 156 ++-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 119 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
Documentation/powerpc/ptrace.rst | 156 +++
Documentation/powerpc/ptrace.txt | 151 ---
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/process/4.Coding.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
Documentation/process/submit-checklist.rst | 2 +-
Documentation/process/submitting-drivers.rst | 2 +-
Documentation/riscv/index.rst | 17 +
Documentation/riscv/{pmu.txt => pmu.rst} | 98 +-
.../{completion.txt => completion.rst} | 38 +-
Documentation/scheduler/index.rst | 29 +
.../{sched-arch.txt => sched-arch.rst} | 18 +-
.../{sched-bwc.txt => sched-bwc.rst} | 30 +-
...{sched-deadline.txt => sched-deadline.rst} | 297 ++---
...ed-design-CFS.txt => sched-design-CFS.rst} | 17 +-
.../{sched-domains.txt => sched-domains.rst} | 8 +-
.../{sched-energy.txt => sched-energy.rst} | 53 +-
...-nice-design.txt => sched-nice-design.rst} | 6 +-
...{sched-rt-group.txt => sched-rt-group.rst} | 30 +-
.../{sched-stats.txt => sched-stats.rst} | 35 +-
Documentation/scheduler/text_files.rst | 5 +
Documentation/target/index.rst | 19 +
Documentation/target/scripts.rst | 11 +
Documentation/target/tcm_mod_builder.rst | 149 +++
Documentation/target/tcm_mod_builder.txt | 145 ---
.../{tcmu-design.txt => tcmu-design.rst} | 268 +++--
.../timers/{highres.txt => highres.rst} | 13 +-
Documentation/timers/{hpet.txt => hpet.rst} | 4 +-
.../timers/{hrtimers.txt => hrtimers.rst} | 6 +-
Documentation/timers/index.rst | 22 +
Documentation/timers/{NO_HZ.txt => no_hz.rst} | 40 +-
.../{timekeeping.txt => timekeeping.rst} | 3 +-
.../{timers-howto.txt => timers-howto.rst} | 15 +-
Documentation/trace/coresight-cpu-debug.txt | 2 +-
.../it_IT/kernel-hacking/hacking.rst | 4 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../it_IT/process/coding-style.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../translations/zh_CN/arm64/booting.txt | 4 +-
.../zh_CN/arm64/legacy_instructions.txt | 4 +-
.../translations/zh_CN/arm64/memory.txt | 4 +-
.../zh_CN/arm64/silicon-errata.txt | 4 +-
.../zh_CN/arm64/tagged-pointers.txt | 4 +-
.../translations/zh_CN/oops-tracing.txt | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
.../zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
.../zh_CN/process/submitting-drivers.rst | 2 +-
Documentation/virtual/kvm/api.txt | 2 +-
Documentation/vm/numa.rst | 6 +-
Documentation/vm/page_migration.rst | 2 +-
Documentation/vm/unevictable-lru.rst | 2 +-
....txt => convert_drivers_to_kernel_api.rst} | 109 +-
.../watchdog/{hpwdt.txt => hpwdt.rst} | 27 +-
Documentation/watchdog/index.rst | 25 +
.../watchdog/{mlx-wdt.txt => mlx-wdt.rst} | 24 +-
.../{pcwd-watchdog.txt => pcwd-watchdog.rst} | 13 +-
.../{watchdog-api.txt => watchdog-api.rst} | 76 +-
...kernel-api.txt => watchdog-kernel-api.rst} | 91 +-
.../watchdog/watchdog-parameters.rst | 736 ++++++++++++
.../watchdog/watchdog-parameters.txt | 410 -------
.../{watchdog-pm.txt => watchdog-pm.rst} | 3 +
Documentation/watchdog/{wdt.txt => wdt.rst} | 31 +-
.../x86/x86_64/fake-numa-for-cpusets.rst | 4 +-
Documentation/xilinx/{eemi.txt => eemi.rst} | 8 +-
Documentation/xilinx/index.rst | 17 +
Kconfig | 2 +-
MAINTAINERS | 34 +-
arch/arc/plat-eznps/Kconfig | 2 +-
arch/arm/Kconfig | 2 +-
arch/arm64/Kconfig | 2 +-
arch/arm64/include/asm/efi.h | 2 +-
arch/arm64/include/asm/image.h | 2 +-
arch/arm64/include/uapi/asm/sigcontext.h | 2 +-
arch/arm64/kernel/kexec_image.c | 2 +-
arch/c6x/Kconfig | 2 +-
arch/m68k/q40/README | 2 +-
arch/microblaze/Kconfig.debug | 2 +-
arch/microblaze/Kconfig.platform | 2 +-
arch/nds32/Kconfig | 2 +-
arch/openrisc/Kconfig | 2 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
arch/powerpc/sysdev/Kconfig | 2 +-
arch/riscv/Kconfig | 2 +-
arch/sh/Kconfig | 2 +-
arch/x86/Kconfig | 6 +-
block/Kconfig | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/block/Kconfig | 2 +-
drivers/cdrom/cdrom.c | 2 +-
drivers/firmware/Kconfig | 2 +-
drivers/gpu/drm/Kconfig | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 2 +-
drivers/ide/Kconfig | 20 +-
drivers/ide/ide-cd.c | 2 +-
drivers/md/Kconfig | 2 +-
drivers/md/dm-init.c | 2 +-
drivers/md/dm-raid.c | 2 +-
drivers/media/usb/dvb-usb-v2/anysee.c | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
drivers/mtd/devices/Kconfig | 2 +-
drivers/net/ethernet/smsc/Kconfig | 6 +-
drivers/net/wireless/intel/iwlegacy/Kconfig | 4 +-
drivers/net/wireless/intel/iwlwifi/Kconfig | 2 +-
drivers/opp/Kconfig | 2 +-
drivers/parport/Kconfig | 2 +-
drivers/pcmcia/ds.c | 2 +-
drivers/power/supply/power_supply_core.c | 2 +-
drivers/regulator/core.c | 2 +-
drivers/scsi/Kconfig | 4 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/staging/sm750fb/Kconfig | 2 +-
drivers/tty/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
drivers/usb/misc/Kconfig | 4 +-
drivers/video/fbdev/Kconfig | 38 +-
drivers/video/fbdev/matrox/matroxfb_base.c | 2 +-
drivers/video/fbdev/pxafb.c | 2 +-
drivers/video/fbdev/sh7760fb.c | 2 +-
drivers/watchdog/Kconfig | 6 +-
drivers/watchdog/smsc37b787_wdt.c | 2 +-
include/linux/cgroup-defs.h | 2 +-
include/linux/fault-inject.h | 2 +-
include/linux/interrupt.h | 2 +-
include/linux/iopoll.h | 4 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/pci.h | 2 +-
include/linux/pm.h | 2 +-
include/linux/regmap.h | 4 +-
include/linux/rwsem.h | 2 +-
include/pcmcia/ds.h | 2 +-
include/pcmcia/ss.h | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
include/uapi/linux/bpf.h | 2 +-
init/Kconfig | 8 +-
kernel/cgroup/cpuset.c | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
kernel/power/Kconfig | 6 +-
kernel/sched/deadline.c | 2 +-
lib/Kconfig.debug | 6 +-
net/bridge/netfilter/Kconfig | 2 +-
net/ipv4/netfilter/Kconfig | 2 +-
net/ipv6/netfilter/Kconfig | 2 +-
net/netfilter/Kconfig | 16 +-
net/tipc/Kconfig | 2 +-
net/wireless/Kconfig | 2 +-
scripts/Kbuild.include | 4 +-
scripts/Makefile.host | 2 +-
scripts/checkpatch.pl | 8 +-
scripts/documentation-file-ref-check | 2 +-
scripts/kconfig/symbol.c | 2 +-
.../tests/err_recursive_dep/expected_stderr | 14 +-
security/device_cgroup.c | 2 +-
sound/oss/dmasound/Kconfig | 6 +-
sound/soc/sof/ops.h | 2 +-
tools/include/uapi/linux/bpf.h | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
392 files changed, 12880 insertions(+), 9641 deletions(-)
rename Documentation/EDID/{HOWTO.txt => howto.rst} (83%)
rename Documentation/aoe/{aoe.txt => aoe.rst} (79%)
create mode 100644 Documentation/aoe/examples.rst
create mode 100644 Documentation/aoe/index.rst
rename Documentation/aoe/{todo.txt => todo.rst} (98%)
rename Documentation/arm64/{acpi_object_usage.txt => acpi_object_usage.rst} (84%)
rename Documentation/arm64/{arm-acpi.txt => arm-acpi.rst} (86%)
rename Documentation/arm64/{booting.txt => booting.rst} (86%)
rename Documentation/arm64/{cpu-feature-registers.txt => cpu-feature-registers.rst} (65%)
rename Documentation/arm64/{elf_hwcaps.txt => elf_hwcaps.rst} (92%)
rename Documentation/arm64/{hugetlbpage.txt => hugetlbpage.rst} (86%)
create mode 100644 Documentation/arm64/index.rst
rename Documentation/arm64/{legacy_instructions.txt => legacy_instructions.rst} (73%)
create mode 100644 Documentation/arm64/memory.rst
delete mode 100644 Documentation/arm64/memory.txt
rename Documentation/arm64/{pointer-authentication.txt => pointer-authentication.rst} (99%)
rename Documentation/arm64/{silicon-errata.txt => silicon-errata.rst} (55%)
rename Documentation/arm64/{sve.txt => sve.rst} (98%)
rename Documentation/arm64/{tagged-pointers.txt => tagged-pointers.rst} (94%)
delete mode 100644 Documentation/cdrom/Makefile
create mode 100644 Documentation/cdrom/cdrom-standard.rst
delete mode 100644 Documentation/cdrom/cdrom-standard.tex
rename Documentation/cdrom/{ide-cd => ide-cd.rst} (82%)
create mode 100644 Documentation/cdrom/index.rst
rename Documentation/cdrom/{packet-writing.txt => packet-writing.rst} (91%)
rename Documentation/cgroup-v1/{blkio-controller.txt => blkio-controller.rst} (89%)
rename Documentation/cgroup-v1/{cgroups.txt => cgroups.rst} (88%)
rename Documentation/cgroup-v1/{cpuacct.txt => cpuacct.rst} (90%)
rename Documentation/cgroup-v1/{cpusets.txt => cpusets.rst} (90%)
rename Documentation/cgroup-v1/{devices.txt => devices.rst} (88%)
rename Documentation/cgroup-v1/{freezer-subsystem.txt => freezer-subsystem.rst} (95%)
rename Documentation/cgroup-v1/{hugetlb.txt => hugetlb.rst} (70%)
create mode 100644 Documentation/cgroup-v1/index.rst
rename Documentation/cgroup-v1/{memcg_test.txt => memcg_test.rst} (62%)
rename Documentation/cgroup-v1/{memory.txt => memory.rst} (71%)
rename Documentation/cgroup-v1/{net_cls.txt => net_cls.rst} (50%)
rename Documentation/cgroup-v1/{net_prio.txt => net_prio.rst} (71%)
rename Documentation/cgroup-v1/{pids.txt => pids.rst} (62%)
rename Documentation/cgroup-v1/{rdma.txt => rdma.rst} (79%)
rename Documentation/device-mapper/{cache-policies.txt => cache-policies.rst} (94%)
rename Documentation/device-mapper/{cache.txt => cache.rst} (61%)
rename Documentation/device-mapper/{delay.txt => delay.rst} (53%)
rename Documentation/device-mapper/{dm-crypt.txt => dm-crypt.rst} (87%)
rename Documentation/device-mapper/{dm-flakey.txt => dm-flakey.rst} (60%)
rename Documentation/device-mapper/{dm-init.txt => dm-init.rst} (69%)
rename Documentation/device-mapper/{dm-integrity.txt => dm-integrity.rst} (90%)
rename Documentation/device-mapper/{dm-io.txt => dm-io.rst} (92%)
rename Documentation/device-mapper/{dm-log.txt => dm-log.rst} (90%)
rename Documentation/device-mapper/{dm-queue-length.txt => dm-queue-length.rst} (76%)
rename Documentation/device-mapper/{dm-raid.txt => dm-raid.rst} (71%)
rename Documentation/device-mapper/{dm-service-time.txt => dm-service-time.rst} (60%)
create mode 100644 Documentation/device-mapper/dm-uevent.rst
delete mode 100644 Documentation/device-mapper/dm-uevent.txt
rename Documentation/device-mapper/{dm-zoned.txt => dm-zoned.rst} (97%)
rename Documentation/device-mapper/{era.txt => era.rst} (70%)
create mode 100644 Documentation/device-mapper/index.rst
rename Documentation/device-mapper/{kcopyd.txt => kcopyd.rst} (93%)
create mode 100644 Documentation/device-mapper/linear.rst
delete mode 100644 Documentation/device-mapper/linear.txt
rename Documentation/device-mapper/{log-writes.txt => log-writes.rst} (61%)
rename Documentation/device-mapper/{persistent-data.txt => persistent-data.rst} (98%)
rename Documentation/device-mapper/{snapshot.txt => snapshot.rst} (62%)
rename Documentation/device-mapper/{statistics.txt => statistics.rst} (87%)
create mode 100644 Documentation/device-mapper/striped.rst
delete mode 100644 Documentation/device-mapper/striped.txt
rename Documentation/device-mapper/{switch.txt => switch.rst} (84%)
rename Documentation/device-mapper/{thin-provisioning.txt => thin-provisioning.rst} (92%)
rename Documentation/device-mapper/{unstriped.txt => unstriped.rst} (60%)
rename Documentation/device-mapper/{verity.txt => verity.rst} (98%)
rename Documentation/device-mapper/{writecache.txt => writecache.rst} (96%)
rename Documentation/device-mapper/{zero.txt => zero.rst} (83%)
rename Documentation/{pps/pps.txt => driver-api/pps.rst} (89%)
rename Documentation/{ptp/ptp.txt => driver-api/ptp.rst} (88%)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
create mode 100644 Documentation/fault-injection/nvme-fault-injection.rst
delete mode 100644 Documentation/fault-injection/nvme-fault-injection.txt
create mode 100644 Documentation/fault-injection/provoke-crashes.rst
delete mode 100644 Documentation/fault-injection/provoke-crashes.txt
rename Documentation/fb/{api.txt => api.rst} (97%)
rename Documentation/fb/{arkfb.txt => arkfb.rst} (92%)
rename Documentation/fb/{aty128fb.txt => aty128fb.rst} (61%)
rename Documentation/fb/{cirrusfb.txt => cirrusfb.rst} (75%)
rename Documentation/fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} (50%)
rename Documentation/fb/{deferred_io.txt => deferred_io.rst} (86%)
rename Documentation/fb/{efifb.txt => efifb.rst} (75%)
rename Documentation/fb/{ep93xx-fb.txt => ep93xx-fb.rst} (85%)
rename Documentation/fb/{fbcon.txt => fbcon.rst} (69%)
rename Documentation/fb/{framebuffer.txt => framebuffer.rst} (92%)
rename Documentation/fb/{gxfb.txt => gxfb.rst} (60%)
create mode 100644 Documentation/fb/index.rst
rename Documentation/fb/{intel810.txt => intel810.rst} (83%)
rename Documentation/fb/{intelfb.txt => intelfb.rst} (73%)
rename Documentation/fb/{internals.txt => internals.rst} (82%)
rename Documentation/fb/{lxfb.txt => lxfb.rst} (60%)
create mode 100644 Documentation/fb/matroxfb.rst
delete mode 100644 Documentation/fb/matroxfb.txt
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
create mode 100644 Documentation/fb/pvr2fb.rst
delete mode 100644 Documentation/fb/pvr2fb.txt
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
create mode 100644 Documentation/fb/sh7760fb.rst
delete mode 100644 Documentation/fb/sh7760fb.txt
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
create mode 100644 Documentation/fb/sstfb.rst
delete mode 100644 Documentation/fb/sstfb.txt
rename Documentation/fb/{tgafb.txt => tgafb.rst} (71%)
rename Documentation/fb/{tridentfb.txt => tridentfb.rst} (70%)
rename Documentation/fb/{udlfb.txt => udlfb.rst} (77%)
rename Documentation/fb/{uvesafb.txt => uvesafb.rst} (52%)
rename Documentation/fb/{vesafb.txt => vesafb.rst} (57%)
create mode 100644 Documentation/fb/viafb.rst
delete mode 100644 Documentation/fb/viafb.txt
rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%)
rename Documentation/fpga/{dfl.txt => dfl.rst} (89%)
create mode 100644 Documentation/fpga/index.rst
create mode 100644 Documentation/ide/changelogs.rst
rename Documentation/ide/{ide-tape.txt => ide-tape.rst} (83%)
rename Documentation/ide/{ide.txt => ide.rst} (72%)
create mode 100644 Documentation/ide/index.rst
rename Documentation/ide/{warm-plug-howto.txt => warm-plug-howto.rst} (61%)
rename Documentation/kbuild/{headers_install.txt => headers_install.rst} (96%)
create mode 100644 Documentation/kbuild/index.rst
create mode 100644 Documentation/kbuild/issues.rst
rename Documentation/kbuild/{kbuild.txt => kbuild.rst} (72%)
rename Documentation/kbuild/{kconfig-language.txt => kconfig-language.rst} (85%)
rename Documentation/kbuild/{kconfig-macro-language.txt => kconfig-macro-language.rst} (94%)
rename Documentation/kbuild/{kconfig.txt => kconfig.rst} (80%)
rename Documentation/kbuild/{makefiles.txt => makefiles.rst} (83%)
rename Documentation/kbuild/{modules.txt => modules.rst} (84%)
create mode 100644 Documentation/kdump/index.rst
rename Documentation/kdump/{kdump.txt => kdump.rst} (91%)
rename Documentation/kdump/{vmcoreinfo.txt => vmcoreinfo.rst} (95%)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
create mode 100644 Documentation/locking/lockstat.rst
delete mode 100644 Documentation/locking/lockstat.txt
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
create mode 100644 Documentation/mic/index.rst
rename Documentation/mic/{mic_overview.txt => mic_overview.rst} (96%)
rename Documentation/mic/{scif_overview.txt => scif_overview.rst} (76%)
rename Documentation/netlabel/{cipso_ipv4.txt => cipso_ipv4.rst} (87%)
create mode 100644 Documentation/netlabel/draft_ietf.rst
create mode 100644 Documentation/netlabel/index.rst
rename Documentation/netlabel/{introduction.txt => introduction.rst} (91%)
rename Documentation/netlabel/{lsm_interface.txt => lsm_interface.rst} (88%)
rename Documentation/pcmcia/{devicetable.txt => devicetable.rst} (97%)
rename Documentation/pcmcia/{driver-changes.txt => driver-changes.rst} (90%)
rename Documentation/pcmcia/{driver.txt => driver.rst} (66%)
create mode 100644 Documentation/pcmcia/index.rst
rename Documentation/pcmcia/{locking.txt => locking.rst} (81%)
rename Documentation/power/{apm-acpi.txt => apm-acpi.rst} (87%)
rename Documentation/power/{basic-pm-debugging.txt => basic-pm-debugging.rst} (87%)
rename Documentation/power/{charger-manager.txt => charger-manager.rst} (78%)
rename Documentation/power/{drivers-testing.txt => drivers-testing.rst} (86%)
rename Documentation/power/{energy-model.txt => energy-model.rst} (74%)
rename Documentation/power/{freezing-of-tasks.txt => freezing-of-tasks.rst} (75%)
create mode 100644 Documentation/power/index.rst
rename Documentation/power/{interface.txt => interface.rst} (84%)
rename Documentation/power/{opp.txt => opp.rst} (78%)
rename Documentation/power/{pci.txt => pci.rst} (97%)
rename Documentation/power/{pm_qos_interface.txt => pm_qos_interface.rst} (62%)
create mode 100644 Documentation/power/power_supply_class.rst
delete mode 100644 Documentation/power/power_supply_class.txt
create mode 100644 Documentation/power/powercap/powercap.rst
delete mode 100644 Documentation/power/powercap/powercap.txt
rename Documentation/power/regulator/{consumer.txt => consumer.rst} (61%)
rename Documentation/power/regulator/{design.txt => design.rst} (86%)
rename Documentation/power/regulator/{machine.txt => machine.rst} (75%)
rename Documentation/power/regulator/{overview.txt => overview.rst} (79%)
create mode 100644 Documentation/power/regulator/regulator.rst
delete mode 100644 Documentation/power/regulator/regulator.txt
rename Documentation/power/{runtime_pm.txt => runtime_pm.rst} (89%)
rename Documentation/power/{s2ram.txt => s2ram.rst} (92%)
rename Documentation/power/{suspend-and-cpuhotplug.txt => suspend-and-cpuhotplug.rst} (90%)
rename Documentation/power/{suspend-and-interrupts.txt => suspend-and-interrupts.rst} (98%)
rename Documentation/power/{swsusp-and-swap-files.txt => swsusp-and-swap-files.rst} (83%)
rename Documentation/power/{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} (67%)
create mode 100644 Documentation/power/swsusp.rst
delete mode 100644 Documentation/power/swsusp.txt
rename Documentation/power/{tricks.txt => tricks.rst} (93%)
rename Documentation/power/{userland-swsusp.txt => userland-swsusp.rst} (85%)
rename Documentation/power/{video.txt => video.rst} (56%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
create mode 100644 Documentation/powerpc/ptrace.rst
delete mode 100644 Documentation/powerpc/ptrace.txt
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
create mode 100644 Documentation/riscv/index.rst
rename Documentation/riscv/{pmu.txt => pmu.rst} (77%)
rename Documentation/scheduler/{completion.txt => completion.rst} (94%)
create mode 100644 Documentation/scheduler/index.rst
rename Documentation/scheduler/{sched-arch.txt => sched-arch.rst} (81%)
rename Documentation/scheduler/{sched-bwc.txt => sched-bwc.rst} (90%)
rename Documentation/scheduler/{sched-deadline.txt => sched-deadline.rst} (88%)
rename Documentation/scheduler/{sched-design-CFS.txt => sched-design-CFS.rst} (97%)
rename Documentation/scheduler/{sched-domains.txt => sched-domains.rst} (97%)
rename Documentation/scheduler/{sched-energy.txt => sched-energy.rst} (96%)
rename Documentation/scheduler/{sched-nice-design.txt => sched-nice-design.rst} (98%)
rename Documentation/scheduler/{sched-rt-group.txt => sched-rt-group.rst} (95%)
rename Documentation/scheduler/{sched-stats.txt => sched-stats.rst} (91%)
create mode 100644 Documentation/scheduler/text_files.rst
create mode 100644 Documentation/target/index.rst
create mode 100644 Documentation/target/scripts.rst
create mode 100644 Documentation/target/tcm_mod_builder.rst
delete mode 100644 Documentation/target/tcm_mod_builder.txt
rename Documentation/target/{tcmu-design.txt => tcmu-design.rst} (69%)
rename Documentation/timers/{highres.txt => highres.rst} (98%)
rename Documentation/timers/{hpet.txt => hpet.rst} (91%)
rename Documentation/timers/{hrtimers.txt => hrtimers.rst} (98%)
create mode 100644 Documentation/timers/index.rst
rename Documentation/timers/{NO_HZ.txt => no_hz.rst} (93%)
rename Documentation/timers/{timekeeping.txt => timekeeping.rst} (98%)
rename Documentation/timers/{timers-howto.txt => timers-howto.rst} (93%)
rename Documentation/watchdog/{convert_drivers_to_kernel_api.txt => convert_drivers_to_kernel_api.rst} (75%)
rename Documentation/watchdog/{hpwdt.txt => hpwdt.rst} (78%)
create mode 100644 Documentation/watchdog/index.rst
rename Documentation/watchdog/{mlx-wdt.txt => mlx-wdt.rst} (78%)
rename Documentation/watchdog/{pcwd-watchdog.txt => pcwd-watchdog.rst} (89%)
rename Documentation/watchdog/{watchdog-api.txt => watchdog-api.rst} (80%)
rename Documentation/watchdog/{watchdog-kernel-api.txt => watchdog-kernel-api.rst} (90%)
create mode 100644 Documentation/watchdog/watchdog-parameters.rst
delete mode 100644 Documentation/watchdog/watchdog-parameters.txt
rename Documentation/watchdog/{watchdog-pm.txt => watchdog-pm.rst} (92%)
rename Documentation/watchdog/{wdt.txt => wdt.rst} (68%)
rename Documentation/xilinx/{eemi.txt => eemi.rst} (92%)
create mode 100644 Documentation/xilinx/index.rst
--
2.21.0
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
Convert kdump documentation to ReST and add it to the
user faced manual, as the documents are mainly focused on
sysadmins that would be enabling kdump.
Note: the vmcoreinfo.rst has one very long title on one of its
sub-sections:
PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision|PG_head_mask|PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
I opted to break this one, into two entries with the same content,
in order to make it easier to display after being parsed in html and PDF.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/bug-hunting.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 6 +-
Documentation/kdump/index.rst | 21 +++
Documentation/kdump/{kdump.txt => kdump.rst} | 131 +++++++++++-------
.../kdump/{vmcoreinfo.txt => vmcoreinfo.rst} | 59 ++++----
.../powerpc/firmware-assisted-dump.txt | 2 +-
.../translations/zh_CN/oops-tracing.txt | 2 +-
Documentation/watchdog/hpwdt.txt | 2 +-
arch/arm/Kconfig | 2 +-
arch/arm64/Kconfig | 2 +-
arch/sh/Kconfig | 2 +-
arch/x86/Kconfig | 4 +-
12 files changed, 137 insertions(+), 98 deletions(-)
create mode 100644 Documentation/kdump/index.rst
rename Documentation/kdump/{kdump.txt => kdump.rst} (91%)
rename Documentation/kdump/{vmcoreinfo.txt => vmcoreinfo.rst} (95%)
diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
index f278b289e260..b761aa2a51d2 100644
--- a/Documentation/admin-guide/bug-hunting.rst
+++ b/Documentation/admin-guide/bug-hunting.rst
@@ -90,7 +90,7 @@ the disk is not available then you have three options:
run a null modem to a second machine and capture the output there
using your favourite communication program. Minicom works well.
-(3) Use Kdump (see Documentation/kdump/kdump.txt),
+(3) Use Kdump (see Documentation/kdump/kdump.rst),
extract the kernel ring buffer from old memory with using dmesg
gdbmacro in Documentation/kdump/gdbmacros.txt.
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index affed5d447de..c31373f39240 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -708,14 +708,14 @@
[KNL, x86_64] select a region under 4G first, and
fall back to reserve region above 4G when '@offset'
hasn't been specified.
- See Documentation/kdump/kdump.txt for further details.
+ See Documentation/kdump/kdump.rst for further details.
crashkernel=range1:size1[,range2:size2,...][@offset]
[KNL] Same as above, but depends on the memory
in the running system. The syntax of range is
start-[end] where start and end are both
a memory unit (amount[KMG]). See also
- Documentation/kdump/kdump.txt for an example.
+ Documentation/kdump/kdump.rst for an example.
crashkernel=size[KMG],high
[KNL, x86_64] range could be above 4G. Allow kernel
@@ -1207,7 +1207,7 @@
Specifies physical address of start of kernel core
image elf header and optionally the size. Generally
kexec loader will pass this option to capture kernel.
- See Documentation/kdump/kdump.txt for details.
+ See Documentation/kdump/kdump.rst for details.
enable_mtrr_cleanup [X86]
The kernel tries to adjust MTRR layout from continuous
diff --git a/Documentation/kdump/index.rst b/Documentation/kdump/index.rst
new file mode 100644
index 000000000000..2b17fcf6867a
--- /dev/null
+++ b/Documentation/kdump/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+================================================================
+Documentation for Kdump - The kexec-based Crash Dumping Solution
+================================================================
+
+This document includes overview, setup and installation, and analysis
+information.
+
+.. toctree::
+ :maxdepth: 1
+
+ kdump
+ vmcoreinfo
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.rst
similarity index 91%
rename from Documentation/kdump/kdump.txt
rename to Documentation/kdump/kdump.rst
index 3162eeb8c262..ac7e131d2935 100644
--- a/Documentation/kdump/kdump.txt
+++ b/Documentation/kdump/kdump.rst
@@ -71,9 +71,8 @@ This is a symlink to the latest version.
The latest kexec-tools git tree is available at:
-git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
-and
-http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
There is also a gitweb interface available at
http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
@@ -81,25 +80,25 @@ http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
More information about kexec-tools can be found at
http://horms.net/projects/kexec/
-3) Unpack the tarball with the tar command, as follows:
+3) Unpack the tarball with the tar command, as follows::
- tar xvpzf kexec-tools.tar.gz
+ tar xvpzf kexec-tools.tar.gz
-4) Change to the kexec-tools directory, as follows:
+4) Change to the kexec-tools directory, as follows::
- cd kexec-tools-VERSION
+ cd kexec-tools-VERSION
-5) Configure the package, as follows:
+5) Configure the package, as follows::
- ./configure
+ ./configure
-6) Compile the package, as follows:
+6) Compile the package, as follows::
- make
+ make
-7) Install the package, as follows:
+7) Install the package, as follows::
- make install
+ make install
Build the system and dump-capture kernels
@@ -126,25 +125,25 @@ dump-capture kernels for enabling kdump support.
System kernel config options
----------------------------
-1) Enable "kexec system call" in "Processor type and features."
+1) Enable "kexec system call" in "Processor type and features."::
- CONFIG_KEXEC=y
+ CONFIG_KEXEC=y
2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
- filesystems." This is usually enabled by default.
+ filesystems." This is usually enabled by default::
- CONFIG_SYSFS=y
+ CONFIG_SYSFS=y
Note that "sysfs file system support" might not appear in the "Pseudo
filesystems" menu if "Configure standard kernel features (for small
systems)" is not enabled in "General Setup." In this case, check the
- .config file itself to ensure that sysfs is turned on, as follows:
+ .config file itself to ensure that sysfs is turned on, as follows::
- grep 'CONFIG_SYSFS' .config
+ grep 'CONFIG_SYSFS' .config
-3) Enable "Compile the kernel with debug info" in "Kernel hacking."
+3) Enable "Compile the kernel with debug info" in "Kernel hacking."::
- CONFIG_DEBUG_INFO=Y
+ CONFIG_DEBUG_INFO=Y
This causes the kernel to be built with debug symbols. The dump
analysis tools require a vmlinux with debug symbols in order to read
@@ -154,29 +153,32 @@ Dump-capture kernel config options (Arch Independent)
-----------------------------------------------------
1) Enable "kernel crash dumps" support under "Processor type and
- features":
+ features"::
- CONFIG_CRASH_DUMP=y
+ CONFIG_CRASH_DUMP=y
-2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems".
+2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems"::
+
+ CONFIG_PROC_VMCORE=y
- CONFIG_PROC_VMCORE=y
(CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.)
Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
--------------------------------------------------------------------
1) On i386, enable high memory support under "Processor type and
- features":
+ features"::
- CONFIG_HIGHMEM64G=y
- or
- CONFIG_HIGHMEM4G
+ CONFIG_HIGHMEM64G=y
+
+ or::
+
+ CONFIG_HIGHMEM4G
2) On i386 and x86_64, disable symmetric multi-processing support
- under "Processor type and features":
+ under "Processor type and features"::
- CONFIG_SMP=n
+ CONFIG_SMP=n
(If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line
when loading the dump-capture kernel, see section "Load the Dump-capture
@@ -184,9 +186,9 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
3) If one wants to build and use a relocatable kernel,
Enable "Build a relocatable kernel" support under "Processor type and
- features"
+ features"::
- CONFIG_RELOCATABLE=y
+ CONFIG_RELOCATABLE=y
4) Use a suitable value for "Physical address where the kernel is
loaded" (under "Processor type and features"). This only appears when
@@ -211,13 +213,13 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
Dump-capture kernel config options (Arch Dependent, ppc64)
----------------------------------------------------------
-1) Enable "Build a kdump crash kernel" support under "Kernel" options:
+1) Enable "Build a kdump crash kernel" support under "Kernel" options::
- CONFIG_CRASH_DUMP=y
+ CONFIG_CRASH_DUMP=y
-2) Enable "Build a relocatable kernel" support
+2) Enable "Build a relocatable kernel" support::
- CONFIG_RELOCATABLE=y
+ CONFIG_RELOCATABLE=y
Make and install the kernel and its modules.
@@ -231,11 +233,13 @@ Dump-capture kernel config options (Arch Dependent, ia64)
The crashkernel region can be automatically placed by the system
kernel at run time. This is done by specifying the base address as 0,
- or omitting it all together.
+ or omitting it all together::
- crashkernel=256M@0
- or
- crashkernel=256M
+ crashkernel=256M@0
+
+ or::
+
+ crashkernel=256M
If the start address is specified, note that the start address of the
kernel will be aligned to 64Mb, so if the start address is not then
@@ -245,9 +249,9 @@ Dump-capture kernel config options (Arch Dependent, arm)
----------------------------------------------------------
- To use a relocatable kernel,
- Enable "AUTO_ZRELADDR" support under "Boot" options:
+ Enable "AUTO_ZRELADDR" support under "Boot" options::
- AUTO_ZRELADDR=y
+ AUTO_ZRELADDR=y
Dump-capture kernel config options (Arch Dependent, arm64)
----------------------------------------------------------
@@ -265,12 +269,12 @@ on the value of System RAM -- that's mostly for distributors that pre-setup
the kernel command line to avoid a unbootable system after some memory has
been removed from the machine.
-The syntax is:
+The syntax is::
crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset]
range=start-[end]
-For example:
+For example::
crashkernel=512M-2G:64M,2G-:128M
@@ -326,35 +330,46 @@ can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz
of dump-capture kernel. Following is the summary.
For i386 and x86_64:
+
- Use vmlinux if kernel is not relocatable.
- Use bzImage/vmlinuz if kernel is relocatable.
+
For ppc64:
+
- Use vmlinux
+
For ia64:
+
- Use vmlinux or vmlinuz.gz
+
For s390x:
+
- Use image or bzImage
+
For arm:
+
- Use zImage
+
For arm64:
+
- Use vmlinux or Image
If you are using an uncompressed vmlinux image then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-vmlinux-image> \
--initrd=<initrd-for-dump-capture-kernel> --args-linux \
--append="root=<root-dev> <arch-specific-options>"
If you are using a compressed bzImage/vmlinuz, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-bzImage> \
--initrd=<initrd-for-dump-capture-kernel> \
--append="root=<root-dev> <arch-specific-options>"
If you are using a compressed zImage, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec --type zImage -p <dump-capture-kernel-bzImage> \
--initrd=<initrd-for-dump-capture-kernel> \
@@ -362,7 +377,7 @@ to load dump-capture kernel.
--append="root=<root-dev> <arch-specific-options>"
If you are using an uncompressed Image, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
kexec -p <dump-capture-kernel-Image> \
--initrd=<initrd-for-dump-capture-kernel> \
@@ -376,18 +391,23 @@ Following are the arch specific command line options to be used while
loading dump-capture kernel.
For i386, x86_64 and ia64:
+
"1 irqpoll maxcpus=1 reset_devices"
For ppc64:
+
"1 maxcpus=1 noirqdistrib reset_devices"
For s390x:
+
"1 maxcpus=1 cgroup_disable=memory"
For arm:
+
"1 maxcpus=1 reset_devices"
For arm64:
+
"1 maxcpus=1 reset_devices"
Notes on loading the dump-capture kernel:
@@ -464,7 +484,7 @@ Write Out the Dump File
=======================
After the dump-capture kernel is booted, write out the dump file with
-the following command:
+the following command::
cp /proc/vmcore <dump-file>
@@ -476,7 +496,7 @@ Before analyzing the dump image, you should reboot into a stable kernel.
You can do limited analysis using GDB on the dump file copied out of
/proc/vmcore. Use the debug vmlinux built with -g and run the following
-command:
+command::
gdb vmlinux <dump-file>
@@ -504,6 +524,11 @@ to achieve the same behaviour.
Contact
=======
-Vivek Goyal ([email protected])
-Maneesh Soni ([email protected])
+- Vivek Goyal ([email protected])
+- Maneesh Soni ([email protected])
+GDB macros
+==========
+
+.. include:: gdbmacros.txt
+ :literal:
diff --git a/Documentation/kdump/vmcoreinfo.txt b/Documentation/kdump/vmcoreinfo.rst
similarity index 95%
rename from Documentation/kdump/vmcoreinfo.txt
rename to Documentation/kdump/vmcoreinfo.rst
index bb94a4bd597a..007a6b86e0ee 100644
--- a/Documentation/kdump/vmcoreinfo.txt
+++ b/Documentation/kdump/vmcoreinfo.rst
@@ -1,8 +1,7 @@
-================================================================
- VMCOREINFO
-================================================================
+==========
+VMCOREINFO
+==========
-===========
What is it?
===========
@@ -12,7 +11,6 @@ values, field offsets, etc. These data are packed into an ELF note
section and used by user-space tools like crash and makedumpfile to
analyze a kernel's memory layout.
-================
Common variables
================
@@ -49,7 +47,7 @@ in a system, one bit position per node number. Used to keep track of
which nodes are in the system and online.
swapper_pg_dir
--------------
+--------------
The global page directory pointer of the kernel. Used to translate
virtual to physical addresses.
@@ -132,16 +130,14 @@ nodemask_t
The size of a nodemask_t type. Used to compute the number of online
nodes.
-(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor|
- compound_order|compound_head)
--------------------------------------------------------------------
+(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor|compound_order|compound_head)
+-------------------------------------------------------------------------------------------------
User-space tools compute their values based on the offset of these
variables. The variables are used when excluding unnecessary pages.
-(pglist_data, node_zones|nr_zones|node_mem_map|node_start_pfn|node_
- spanned_pages|node_id)
--------------------------------------------------------------------
+(pglist_data, node_zones|nr_zones|node_mem_map|node_start_pfn|node_spanned_pages|node_id)
+-----------------------------------------------------------------------------------------
On NUMA machines, each NUMA node has a pg_data_t to describe its memory
layout. On UMA machines there is a single pglist_data which describes the
@@ -245,21 +241,25 @@ NR_FREE_PAGES
On linux-2.6.21 or later, the number of free pages is in
vm_stat[NR_FREE_PAGES]. Used to get the number of free pages.
-PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision
-|PG_head_mask|PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)
-|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
------------------------------------------------------------------
+PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision|PG_head_mask
+------------------------------------------------------------------------------
Page attributes. These flags are used to filter various unnecessary for
dumping pages.
+PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy)|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline)
+-----------------------------------------------------------------------------
+
+More page attributes. These flags are used to filter various unnecessary for
+dumping pages.
+
+
HUGETLB_PAGE_DTOR
-----------------
The HUGETLB_PAGE_DTOR flag denotes hugetlbfs pages. Makedumpfile
excludes these pages.
-======
x86_64
======
@@ -318,12 +318,12 @@ address.
Currently, sme_mask stores the value of the C-bit position. If needed,
additional SME-relevant info can be placed in that variable.
-For example:
-[ misc ][ enc bit ][ other misc SME info ]
-0000_0000_0000_0000_1000_0000_0000_0000_0000_0000_..._0000
-63 59 55 51 47 43 39 35 31 27 ... 3
+For example::
+
+ [ misc ][ enc bit ][ other misc SME info ]
+ 0000_0000_0000_0000_1000_0000_0000_0000_0000_0000_..._0000
+ 63 59 55 51 47 43 39 35 31 27 ... 3
-======
x86_32
======
@@ -335,7 +335,6 @@ of a higher page table lookup overhead, and also consumes more page
table space per process. Used to check whether PAE was enabled in the
crash kernel when converting virtual addresses to physical addresses.
-====
ia64
====
@@ -366,7 +365,6 @@ PGTABLE_3|PGTABLE_4
User-space tools need to know whether the crash kernel was in 3-level or
4-level paging mode. Used to distinguish the page table.
-=====
ARM64
=====
@@ -395,9 +393,8 @@ KERNELOFFSET
The kernel randomization offset. Used to compute the page offset. If
KASLR is disabled, this value is zero.
-====
arm
-====
+===
ARM_LPAE
--------
@@ -405,12 +402,11 @@ ARM_LPAE
It indicates whether the crash kernel supports large physical address
extensions. Used to translate virtual to physical addresses.
-====
s390
====
lowcore_ptr
-----------
+-----------
An array with a pointer to the lowcore of every CPU. Used to print the
psw and all registers information.
@@ -425,7 +421,6 @@ Used to get the vmalloc_start address from the high_memory symbol.
The maximum number of CPUs.
-=======
powerpc
=======
@@ -460,9 +455,8 @@ Page size definitions, i.e. 4k, 64k, or 16M.
Used to make vtop translations.
-vmemmap_backing|(vmemmap_backing, list)|(vmemmap_backing, phys)|
-(vmemmap_backing, virt_addr)
-----------------------------------------------------------------
+vmemmap_backing|(vmemmap_backing, list)|(vmemmap_backing, phys)|(vmemmap_backing, virt_addr)
+--------------------------------------------------------------------------------------------
The vmemmap virtual address space management does not have a traditional
page table to track which virtual struct pages are backed by a physical
@@ -480,7 +474,6 @@ member.
Used in vtop translations.
-==
sh
==
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt
index 18c5feef2577..0c41d6d463f3 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.txt
@@ -59,7 +59,7 @@ as follows:
the default calculated size. Use this option if default
boot memory size is not sufficient for second kernel to
boot successfully. For syntax of crashkernel= parameter,
- refer to Documentation/kdump/kdump.txt. If any offset is
+ refer to Documentation/kdump/kdump.rst. If any offset is
provided in crashkernel= parameter, it will be ignored
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt
index 93fa061cf9e4..368ddd05b304 100644
--- a/Documentation/translations/zh_CN/oops-tracing.txt
+++ b/Documentation/translations/zh_CN/oops-tracing.txt
@@ -53,7 +53,7 @@ cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“
（2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null
modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。
-（3）使用Kdump（请参看Documentation/kdump/kdump.txt），
+（3）使用Kdump（请参看Documentation/kdump/kdump.rst），
使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
环形缓冲区。
diff --git a/Documentation/watchdog/hpwdt.txt b/Documentation/watchdog/hpwdt.txt
index 55df692c5595..aaa9e4b4bdcd 100644
--- a/Documentation/watchdog/hpwdt.txt
+++ b/Documentation/watchdog/hpwdt.txt
@@ -51,7 +51,7 @@ Last reviewed: 08/20/2018
and loop forever. This is generally not what a watchdog user wants.
For those wishing to learn more please see:
- Documentation/kdump/kdump.txt
+ Documentation/kdump/kdump.rst
Documentation/admin-guide/kernel-parameters.txt (panic=)
Your Linux Distribution specific documentation.
diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index 204cbc6bf234..af58d31ee4e1 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -2006,7 +2006,7 @@ config CRASH_DUMP
kdump/kexec. The crash dump kernel must be compiled to a
memory address not used by the main kernel
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config AUTO_ZRELADDR
bool "Auto calculation of the decompressed kernel image address"
diff --git a/arch/arm64/Kconfig b/arch/arm64/Kconfig
index c2afcea9b19b..ac33b4bd1624 100644
--- a/arch/arm64/Kconfig
+++ b/arch/arm64/Kconfig
@@ -996,7 +996,7 @@ config CRASH_DUMP
reserved region and then later executed after a crash by
kdump/kexec.
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config XEN_DOM0
def_bool y
diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
index b77f512bb176..ce1a28654507 100644
--- a/arch/sh/Kconfig
+++ b/arch/sh/Kconfig
@@ -623,7 +623,7 @@ config CRASH_DUMP
to a memory address not used by the main kernel using
PHYSICAL_START.
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config KEXEC_JUMP
bool "kexec jump (EXPERIMENTAL)"
diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
index 4b37664e7471..a109141a8d3b 100644
--- a/arch/x86/Kconfig
+++ b/arch/x86/Kconfig
@@ -2038,7 +2038,7 @@ config CRASH_DUMP
to a memory address not used by the main kernel or BIOS using
PHYSICAL_START, or it must be built as a relocatable image
(CONFIG_RELOCATABLE=y).
- For more details see Documentation/kdump/kdump.txt
+ For more details see Documentation/kdump/kdump.rst
config KEXEC_JUMP
bool "kexec jump"
@@ -2075,7 +2075,7 @@ config PHYSICAL_START
the reserved region. In other words, it can be set based on
the "X" value as specified in the "crashkernel=YM@XM"
command line boot parameter passed to the panic-ed
- kernel. Please take a look at Documentation/kdump/kdump.txt
+ kernel. Please take a look at Documentation/kdump/kdump.rst
for more details about crash dumps.
Usage of bzImage for capturing the crash dump is recommended as
--
2.21.0
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 8bec064bb353..1f73ef8c25f5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7644,7 +7644,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
This is a very trivial conversion: adjust the title markup
and add a few literal block markups to produce a better
visual when parsed and avoid warnings.
As newer documents related to xilinx could be added in the future,
create a new index file for it.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/xilinx/{eemi.txt => eemi.rst} | 8 ++++----
Documentation/xilinx/index.rst | 17 +++++++++++++++++
2 files changed, 21 insertions(+), 4 deletions(-)
rename Documentation/xilinx/{eemi.txt => eemi.rst} (92%)
create mode 100644 Documentation/xilinx/index.rst
diff --git a/Documentation/xilinx/eemi.txt b/Documentation/xilinx/eemi.rst
similarity index 92%
rename from Documentation/xilinx/eemi.txt
rename to Documentation/xilinx/eemi.rst
index 5f39b4ffdcd4..9dcbc6f18d75 100644
--- a/Documentation/xilinx/eemi.txt
+++ b/Documentation/xilinx/eemi.rst
@@ -1,6 +1,6 @@
----------------------------------------------------------------------
+====================================
Xilinx Zynq MPSoC EEMI Documentation
----------------------------------------------------------------------
+====================================
Xilinx Zynq MPSoC Firmware Interface
-------------------------------------
@@ -21,7 +21,7 @@ The zynqmp-firmware driver maintain all EEMI APIs in zynqmp_eemi_ops
structure. Any driver who want to communicate with PMC using EEMI APIs
can call zynqmp_pm_get_eemi_ops().
-Example of EEMI ops:
+Example of EEMI ops::
/* zynqmp-firmware driver maintain all EEMI APIs */
struct zynqmp_eemi_ops {
@@ -34,7 +34,7 @@ Example of EEMI ops:
.query_data = zynqmp_pm_query_data,
};
-Example of EEMI ops usage:
+Example of EEMI ops usage::
static const struct zynqmp_eemi_ops *eemi_ops;
u32 ret_payload[PAYLOAD_ARG_CNT];
diff --git a/Documentation/xilinx/index.rst b/Documentation/xilinx/index.rst
new file mode 100644
index 000000000000..01cc1a0714df
--- /dev/null
+++ b/Documentation/xilinx/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+===========
+Xilinx FPGA
+===========
+
+.. toctree::
+ :maxdepth: 1
+
+ eemi
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
--
2.21.0
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
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 5ed1fc93969a..5fdbf6e78d46 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6283,7 +6283,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 those documents and prepare them to be part of the kernel
API book, as most of the stuff there are related to the
Kernel interfaces.
Still, in the future, it would make sense to split the docs,
as some of the stuff is clearly focused on sysadmin tasks.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[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 ++-
.../watchdog/watchdog-parameters.rst | 736 ++++++++++++++++++
.../watchdog/watchdog-parameters.txt | 410 ----------
.../{watchdog-pm.txt => watchdog-pm.rst} | 3 +
Documentation/watchdog/{wdt.txt => wdt.rst} | 31 +-
MAINTAINERS | 2 +-
drivers/watchdog/Kconfig | 6 +-
drivers/watchdog/smsc37b787_wdt.c | 2 +-
16 files changed, 1004 insertions(+), 553 deletions(-)
rename Documentation/watchdog/{convert_drivers_to_kernel_api.txt => convert_drivers_to_kernel_api.rst} (75%)
rename Documentation/watchdog/{hpwdt.txt => hpwdt.rst} (79%)
create mode 100644 Documentation/watchdog/index.rst
rename Documentation/watchdog/{mlx-wdt.txt => mlx-wdt.rst} (78%)
rename Documentation/watchdog/{pcwd-watchdog.txt => pcwd-watchdog.rst} (89%)
rename Documentation/watchdog/{watchdog-api.txt => watchdog-api.rst} (80%)
rename Documentation/watchdog/{watchdog-kernel-api.txt => watchdog-kernel-api.rst} (90%)
create mode 100644 Documentation/watchdog/watchdog-parameters.rst
delete mode 100644 Documentation/watchdog/watchdog-parameters.txt
rename Documentation/watchdog/{watchdog-pm.txt => watchdog-pm.rst} (92%)
rename Documentation/watchdog/{wdt.txt => wdt.rst} (68%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 0092a453f7dc..3d072ca532bb 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -5182,7 +5182,7 @@
Default: 3 = cyan.
watchdog timers [HW,WDT] For information on watchdog timers,
- see Documentation/watchdog/watchdog-parameters.txt
+ see Documentation/watchdog/watchdog-parameters.rst
or other driver-specific files in the
Documentation/watchdog/ directory.
diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.txt
index 23b0c8b20cd1..5623b9916411 100644
--- a/Documentation/kernel-per-CPU-kthreads.txt
+++ b/Documentation/kernel-per-CPU-kthreads.txt
@@ -348,7 +348,7 @@ To reduce its OS jitter, do at least one of the following:
2. Boot with "nosoftlockup=0", which will also prevent these kthreads
from being created. Other related watchdog and softlockup boot
parameters may be found in Documentation/admin-guide/kernel-parameters.rst
- and Documentation/watchdog/watchdog-parameters.txt.
+ and Documentation/watchdog/watchdog-parameters.rst.
3. Echo a zero to /proc/sys/kernel/watchdog to disable the
watchdog timer.
4. Echo a large number of /proc/sys/kernel/watchdog_thresh in
diff --git a/Documentation/watchdog/convert_drivers_to_kernel_api.txt b/Documentation/watchdog/convert_drivers_to_kernel_api.rst
similarity index 75%
rename from Documentation/watchdog/convert_drivers_to_kernel_api.txt
rename to Documentation/watchdog/convert_drivers_to_kernel_api.rst
index 9fffb2958d13..dd934cc08e40 100644
--- a/Documentation/watchdog/convert_drivers_to_kernel_api.txt
+++ b/Documentation/watchdog/convert_drivers_to_kernel_api.rst
@@ -1,6 +1,8 @@
+=========================================================
Converting old watchdog drivers to the watchdog framework
+=========================================================
+
by Wolfram Sang <[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.rst b/Documentation/watchdog/watchdog-parameters.rst
new file mode 100644
index 000000000000..b121caae7798
--- /dev/null
+++ b/Documentation/watchdog/watchdog-parameters.rst
@@ -0,0 +1,736 @@
+==========================
+WatchDog Module Parameters
+==========================
+
+This file provides information on the module parameters of many of
+the Linux watchdog drivers. Watchdog driver parameter specs should
+be listed here unless the driver has its own driver-specific information
+file.
+
+See Documentation/admin-guide/kernel-parameters.rst for information on
+providing kernel parameters for builtin drivers versus loadable
+modules.
+
+-------------------------------------------------
+
+acquirewdt:
+ wdt_stop:
+ Acquire WDT 'stop' io port (default 0x43)
+ wdt_start:
+ Acquire WDT 'start' io port (default 0x443)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+advantechwdt:
+ wdt_stop:
+ Advantech WDT 'stop' io port (default 0x443)
+ wdt_start:
+ Advantech WDT 'start' io port (default 0x443)
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=63, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+alim1535_wdt:
+ timeout:
+ Watchdog timeout in seconds. (0 < timeout < 18000, default=60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+alim7101_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30
+ use_gpio:
+ Use the gpio watchdog (required by old cobalt boards).
+ default=0/off/no
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ar7_wdt:
+ margin:
+ Watchdog margin in seconds (default=60)
+ nowayout:
+ Disable watchdog shutdown on close
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+armada_37xx_wdt:
+ timeout:
+ Watchdog timeout in seconds. (default=120)
+ nowayout:
+ Disable watchdog shutdown on close
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+at91rm9200_wdt:
+ wdt_time:
+ Watchdog time in seconds. (default=5)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+at91sam9_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+bcm47xx_wdt:
+ wdt_time:
+ Watchdog time in seconds. (default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+coh901327_wdt:
+ margin:
+ Watchdog margin in seconds (default 60s)
+
+-------------------------------------------------
+
+cpu5wdt:
+ port:
+ base address of watchdog card, default is 0x91
+ verbose:
+ be verbose, default is 0 (no)
+ ticks:
+ count down ticks, default is 10000
+
+-------------------------------------------------
+
+cpwd:
+ wd0_timeout:
+ Default watchdog0 timeout in 1/10secs
+ wd1_timeout:
+ Default watchdog1 timeout in 1/10secs
+ wd2_timeout:
+ Default watchdog2 timeout in 1/10secs
+
+-------------------------------------------------
+
+da9052wdt:
+ timeout:
+ Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+davinci_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 600, default 60
+
+-------------------------------------------------
+
+ebc-c384_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+
+-------------------------------------------------
+
+ep93xx_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
+
+-------------------------------------------------
+
+eurotechwdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ io:
+ Eurotech WDT io port (default=0x3f0)
+ irq:
+ Eurotech WDT irq (default=10)
+ ev:
+ Eurotech WDT event type (default is `int`)
+
+-------------------------------------------------
+
+gef_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+geodewdt:
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=131, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+i6300esb:
+ heartbeat:
+ Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+iTCO_wdt:
+ heartbeat:
+ Watchdog heartbeat in seconds.
+ (2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+iTCO_vendor_support:
+ vendorsupport:
+ iTCO vendor specific support mode, default=0 (none),
+ 1=SuperMicro Pent3, 2=SuperMicro Pent4+, 911=Broken SMI BIOS
+
+-------------------------------------------------
+
+ib700wdt:
+ timeout:
+ Watchdog timeout in seconds. 0<= timeout <=30, default=30.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ibmasr:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+imx2_wdt:
+ timeout:
+ Watchdog timeout in seconds (default 60 s)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+indydog:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+iop_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+it8712f_wdt:
+ margin:
+ Watchdog margin in seconds (default 60)
+ nowayout:
+ Disable watchdog shutdown on close
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+it87_wdt:
+ nogameport:
+ Forbid the activation of game port, default=0
+ nocir:
+ Forbid the use of CIR (workaround for some buggy setups); set to 1 if
+system resets despite watchdog daemon running, default=0
+ exclusive:
+ Watchdog exclusive device open, default=1
+ timeout:
+ Watchdog timeout in seconds, default=60
+ testmode:
+ Watchdog test mode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ixp4xx_wdt:
+ heartbeat:
+ Watchdog heartbeat in seconds (default 60s)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ks8695_wdt:
+ wdt_time:
+ Watchdog time in seconds. (default=5)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+machzwd:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ action:
+ after watchdog resets, generate:
+ 0 = RESET(*) 1 = SMI 2 = NMI 3 = SCI
+
+-------------------------------------------------
+
+max63xx_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 60, default 60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ nodelay:
+ Force selection of a timeout setting without initial delay
+ (max6373/74 only, default=0)
+
+-------------------------------------------------
+
+mixcomwd:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+mpc8xxx_wdt:
+ timeout:
+ Watchdog timeout in ticks. (0<timeout<65536, default=65535)
+ reset:
+ Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+mv64x60_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ni903x_wdt:
+ timeout:
+ Initial watchdog timeout in seconds (0<timeout<516, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+nic7018_wdt:
+ timeout:
+ Initial watchdog timeout in seconds (0<timeout<464, default=80)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+nuc900_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds.
+ (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+omap_wdt:
+ timer_margin:
+ initial watchdog timeout (in seconds)
+ early_enable:
+ Watchdog is started on module insertion (default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+orion_wdt:
+ heartbeat:
+ Initial watchdog heartbeat in seconds
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+pc87413_wdt:
+ io:
+ pc87413 WDT I/O port (default: io).
+ timeout:
+ Watchdog timeout in minutes (default=timeout).
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+pika_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 15)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+pnx4008_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 60, default 19
+ nowayout:
+ Set to 1 to keep watchdog running after device release
+
+-------------------------------------------------
+
+pnx833x_wdt:
+ timeout:
+ Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ start_enabled:
+ Watchdog is started on module insertion (default=1)
+
+-------------------------------------------------
+
+rc32434_wdt:
+ timeout:
+ Watchdog timeout value, in seconds (default=20)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+riowd:
+ riowd_timeout:
+ Watchdog timeout in minutes (default=1)
+
+-------------------------------------------------
+
+s3c2410_wdt:
+ tmr_margin:
+ Watchdog tmr_margin in seconds. (default=15)
+ tmr_atboot:
+ Watchdog is started at boot time if set to 1, default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ soft_noboot:
+ Watchdog action, set to 1 to ignore reboots, 0 to reboot
+ debug:
+ Watchdog debug, set to >1 for debug, (default 0)
+
+-------------------------------------------------
+
+sa1100_wdt:
+ margin:
+ Watchdog margin in seconds (default 60s)
+
+-------------------------------------------------
+
+sb_wdog:
+ timeout:
+ Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
+
+-------------------------------------------------
+
+sbc60xxwdt:
+ wdt_stop:
+ SBC60xx WDT 'stop' io port (default 0x45)
+ wdt_start:
+ SBC60xx WDT 'start' io port (default 0x443)
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sbc7240_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=255, default=30)
+ nowayout:
+ Disable watchdog when closing device file
+
+-------------------------------------------------
+
+sbc8360:
+ timeout:
+ Index into timeout table (0-63) (default=27 (60s))
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sbc_epx_c3:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sbc_fitpc2_wdt:
+ margin:
+ Watchdog margin in seconds (default 60s)
+ nowayout:
+ Watchdog cannot be stopped once started
+
+-------------------------------------------------
+
+sbsa_gwdt:
+ timeout:
+ Watchdog timeout in seconds. (default 10s)
+ action:
+ Watchdog action at the first stage timeout,
+ set to 0 to ignore, 1 to panic. (default=0)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sc1200wdt:
+ isapnp:
+ When set to 0 driver ISA PnP support will be disabled (default=1)
+ io:
+ io port
+ timeout:
+ range is 0-255 minutes, default is 1
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sc520_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sch311x_wdt:
+ force_id:
+ Override the detected device ID
+ therm_trip:
+ Should a ThermTrip trigger the reset generator
+ timeout:
+ Watchdog timeout in seconds. 1<= timeout <=15300, default=60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+scx200_wdt:
+ margin:
+ Watchdog margin in seconds
+ nowayout:
+ Disable watchdog shutdown on close
+
+-------------------------------------------------
+
+shwdt:
+ clock_division_ratio:
+ Clock division ratio. Valid ranges are from 0x5 (1.31ms)
+ to 0x7 (5.25ms). (default=7)
+ heartbeat:
+ Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+smsc37b787_wdt:
+ timeout:
+ range is 1-255 units, default is 60
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+softdog:
+ soft_margin:
+ Watchdog soft_margin in seconds.
+ (0 < soft_margin < 65536, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+ soft_noboot:
+ Softdog action, set to 1 to ignore reboots, 0 to reboot
+ (default=0)
+
+-------------------------------------------------
+
+stmp3xxx_wdt:
+ heartbeat:
+ Watchdog heartbeat period in seconds from 1 to 4194304, default 19
+
+-------------------------------------------------
+
+tegra_wdt:
+ heartbeat:
+ Watchdog heartbeats in seconds. (default = 120)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+ts72xx_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
+ nowayout:
+ Disable watchdog shutdown on close
+
+-------------------------------------------------
+
+twl4030_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+txx9wdt:
+ timeout:
+ Watchdog timeout in seconds. (0<timeout<N, default=60)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+uniphier_wdt:
+ timeout:
+ Watchdog timeout in power of two seconds.
+ (1 <= timeout <= 128, default=64)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+w83627hf_wdt:
+ wdt_io:
+ w83627hf/thf WDT io port (default 0x2E)
+ timeout:
+ Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+w83877f_wdt:
+ timeout:
+ Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+w83977f_wdt:
+ timeout:
+ Watchdog timeout in seconds (15..7635), default=45)
+ testmode:
+ Watchdog testmode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wafer5823wdt:
+ timeout:
+ Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wdt285:
+ soft_margin:
+ Watchdog timeout in seconds (default=60)
+
+-------------------------------------------------
+
+wdt977:
+ timeout:
+ Watchdog timeout in seconds (60..15300, default=60)
+ testmode:
+ Watchdog testmode (1 = no reboot), default=0
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wm831x_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+wm8350_wdt:
+ nowayout:
+ Watchdog cannot be stopped once started
+ (default=kernel config parameter)
+
+-------------------------------------------------
+
+sun4v_wdt:
+ timeout_ms:
+ Watchdog timeout in milliseconds 1..180000, default=60000)
+ nowayout:
+ Watchdog cannot be stopped once started
diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt
deleted file mode 100644
index 0b88e333f9e1..000000000000
--- a/Documentation/watchdog/watchdog-parameters.txt
+++ /dev/null
@@ -1,410 +0,0 @@
-This file provides information on the module parameters of many of
-the Linux watchdog drivers. Watchdog driver parameter specs should
-be listed here unless the driver has its own driver-specific information
-file.
-
-
-See Documentation/admin-guide/kernel-parameters.rst for information on
-providing kernel parameters for builtin drivers versus loadable
-modules.
-
-
--------------------------------------------------
-acquirewdt:
-wdt_stop: Acquire WDT 'stop' io port (default 0x43)
-wdt_start: Acquire WDT 'start' io port (default 0x443)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-advantechwdt:
-wdt_stop: Advantech WDT 'stop' io port (default 0x443)
-wdt_start: Advantech WDT 'start' io port (default 0x443)
-timeout: Watchdog timeout in seconds. 1<= timeout <=63, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-alim1535_wdt:
-timeout: Watchdog timeout in seconds. (0 < timeout < 18000, default=60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-alim7101_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30
-use_gpio: Use the gpio watchdog (required by old cobalt boards).
- default=0/off/no
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ar7_wdt:
-margin: Watchdog margin in seconds (default=60)
-nowayout: Disable watchdog shutdown on close
- (default=kernel config parameter)
--------------------------------------------------
-armada_37xx_wdt:
-timeout: Watchdog timeout in seconds. (default=120)
-nowayout: Disable watchdog shutdown on close
- (default=kernel config parameter)
--------------------------------------------------
-at91rm9200_wdt:
-wdt_time: Watchdog time in seconds. (default=5)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-at91sam9_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 15)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-bcm47xx_wdt:
-wdt_time: Watchdog time in seconds. (default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-coh901327_wdt:
-margin: Watchdog margin in seconds (default 60s)
--------------------------------------------------
-cpu5wdt:
-port: base address of watchdog card, default is 0x91
-verbose: be verbose, default is 0 (no)
-ticks: count down ticks, default is 10000
--------------------------------------------------
-cpwd:
-wd0_timeout: Default watchdog0 timeout in 1/10secs
-wd1_timeout: Default watchdog1 timeout in 1/10secs
-wd2_timeout: Default watchdog2 timeout in 1/10secs
--------------------------------------------------
-da9052wdt:
-timeout: Watchdog timeout in seconds. 2<= timeout <=131, default=2.048s
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-davinci_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 600, default 60
--------------------------------------------------
-ebc-c384_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=15300, default=60)
-nowayout: Watchdog cannot be stopped once started
--------------------------------------------------
-ep93xx_wdt:
-nowayout: Watchdog cannot be stopped once started
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD)
--------------------------------------------------
-eurotechwdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-io: Eurotech WDT io port (default=0x3f0)
-irq: Eurotech WDT irq (default=10)
-ev: Eurotech WDT event type (default is `int')
--------------------------------------------------
-gef_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-geodewdt:
-timeout: Watchdog timeout in seconds. 1<= timeout <=131, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-i6300esb:
-heartbeat: Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-iTCO_wdt:
-heartbeat: Watchdog heartbeat in seconds.
- (2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-iTCO_vendor_support:
-vendorsupport: iTCO vendor specific support mode, default=0 (none),
- 1=SuperMicro Pent3, 2=SuperMicro Pent4+, 911=Broken SMI BIOS
--------------------------------------------------
-ib700wdt:
-timeout: Watchdog timeout in seconds. 0<= timeout <=30, default=30.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ibmasr:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-imx2_wdt:
-timeout: Watchdog timeout in seconds (default 60 s)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-indydog:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-iop_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-it8712f_wdt:
-margin: Watchdog margin in seconds (default 60)
-nowayout: Disable watchdog shutdown on close
- (default=kernel config parameter)
--------------------------------------------------
-it87_wdt:
-nogameport: Forbid the activation of game port, default=0
-nocir: Forbid the use of CIR (workaround for some buggy setups); set to 1 if
-system resets despite watchdog daemon running, default=0
-exclusive: Watchdog exclusive device open, default=1
-timeout: Watchdog timeout in seconds, default=60
-testmode: Watchdog test mode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ixp4xx_wdt:
-heartbeat: Watchdog heartbeat in seconds (default 60s)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ks8695_wdt:
-wdt_time: Watchdog time in seconds. (default=5)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-machzwd:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-action: after watchdog resets, generate:
- 0 = RESET(*) 1 = SMI 2 = NMI 3 = SCI
--------------------------------------------------
-max63xx_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-nodelay: Force selection of a timeout setting without initial delay
- (max6373/74 only, default=0)
--------------------------------------------------
-mixcomwd:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-mpc8xxx_wdt:
-timeout: Watchdog timeout in ticks. (0<timeout<65536, default=65535)
-reset: Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-mv64x60_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ni903x_wdt:
-timeout: Initial watchdog timeout in seconds (0<timeout<516, default=60)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-nic7018_wdt:
-timeout: Initial watchdog timeout in seconds (0<timeout<464, default=80)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-nuc900_wdt:
-heartbeat: Watchdog heartbeats in seconds.
- (default = 15)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-omap_wdt:
-timer_margin: initial watchdog timeout (in seconds)
-early_enable: Watchdog is started on module insertion (default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-orion_wdt:
-heartbeat: Initial watchdog heartbeat in seconds
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-pc87413_wdt:
-io: pc87413 WDT I/O port (default: io).
-timeout: Watchdog timeout in minutes (default=timeout).
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-pika_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 15)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-pnx4008_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 19
-nowayout: Set to 1 to keep watchdog running after device release
--------------------------------------------------
-pnx833x_wdt:
-timeout: Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-start_enabled: Watchdog is started on module insertion (default=1)
--------------------------------------------------
-rc32434_wdt:
-timeout: Watchdog timeout value, in seconds (default=20)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-riowd:
-riowd_timeout: Watchdog timeout in minutes (default=1)
--------------------------------------------------
-s3c2410_wdt:
-tmr_margin: Watchdog tmr_margin in seconds. (default=15)
-tmr_atboot: Watchdog is started at boot time if set to 1, default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-soft_noboot: Watchdog action, set to 1 to ignore reboots, 0 to reboot
-debug: Watchdog debug, set to >1 for debug, (default 0)
--------------------------------------------------
-sa1100_wdt:
-margin: Watchdog margin in seconds (default 60s)
--------------------------------------------------
-sb_wdog:
-timeout: Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs)
--------------------------------------------------
-sbc60xxwdt:
-wdt_stop: SBC60xx WDT 'stop' io port (default 0x45)
-wdt_start: SBC60xx WDT 'start' io port (default 0x443)
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sbc7240_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=255, default=30)
-nowayout: Disable watchdog when closing device file
--------------------------------------------------
-sbc8360:
-timeout: Index into timeout table (0-63) (default=27 (60s))
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sbc_epx_c3:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sbc_fitpc2_wdt:
-margin: Watchdog margin in seconds (default 60s)
-nowayout: Watchdog cannot be stopped once started
--------------------------------------------------
-sbsa_gwdt:
-timeout: Watchdog timeout in seconds. (default 10s)
-action: Watchdog action at the first stage timeout,
- set to 0 to ignore, 1 to panic. (default=0)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sc1200wdt:
-isapnp: When set to 0 driver ISA PnP support will be disabled (default=1)
-io: io port
-timeout: range is 0-255 minutes, default is 1
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sc520_wdt:
-timeout: Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sch311x_wdt:
-force_id: Override the detected device ID
-therm_trip: Should a ThermTrip trigger the reset generator
-timeout: Watchdog timeout in seconds. 1<= timeout <=15300, default=60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-scx200_wdt:
-margin: Watchdog margin in seconds
-nowayout: Disable watchdog shutdown on close
--------------------------------------------------
-shwdt:
-clock_division_ratio: Clock division ratio. Valid ranges are from 0x5 (1.31ms)
- to 0x7 (5.25ms). (default=7)
-heartbeat: Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-smsc37b787_wdt:
-timeout: range is 1-255 units, default is 60
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-softdog:
-soft_margin: Watchdog soft_margin in seconds.
- (0 < soft_margin < 65536, default=60)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
-soft_noboot: Softdog action, set to 1 to ignore reboots, 0 to reboot
- (default=0)
--------------------------------------------------
-stmp3xxx_wdt:
-heartbeat: Watchdog heartbeat period in seconds from 1 to 4194304, default 19
--------------------------------------------------
-tegra_wdt:
-heartbeat: Watchdog heartbeats in seconds. (default = 120)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-ts72xx_wdt:
-timeout: Watchdog timeout in seconds. (1 <= timeout <= 8, default=8)
-nowayout: Disable watchdog shutdown on close
--------------------------------------------------
-twl4030_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-txx9wdt:
-timeout: Watchdog timeout in seconds. (0<timeout<N, default=60)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-uniphier_wdt:
-timeout: Watchdog timeout in power of two seconds.
- (1 <= timeout <= 128, default=64)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-w83627hf_wdt:
-wdt_io: w83627hf/thf WDT io port (default 0x2E)
-timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-w83877f_wdt:
-timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30)
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-w83977f_wdt:
-timeout: Watchdog timeout in seconds (15..7635), default=45)
-testmode: Watchdog testmode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wafer5823wdt:
-timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60.
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wdt285:
-soft_margin: Watchdog timeout in seconds (default=60)
--------------------------------------------------
-wdt977:
-timeout: Watchdog timeout in seconds (60..15300, default=60)
-testmode: Watchdog testmode (1 = no reboot), default=0
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wm831x_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-wm8350_wdt:
-nowayout: Watchdog cannot be stopped once started
- (default=kernel config parameter)
--------------------------------------------------
-sun4v_wdt:
-timeout_ms: Watchdog timeout in milliseconds 1..180000, default=60000)
-nowayout: Watchdog cannot be stopped once started
--------------------------------------------------
diff --git a/Documentation/watchdog/watchdog-pm.txt b/Documentation/watchdog/watchdog-pm.rst
similarity index 92%
rename from Documentation/watchdog/watchdog-pm.txt
rename to Documentation/watchdog/watchdog-pm.rst
index 7a4dd46e0d24..646e1f28f31f 100644
--- a/Documentation/watchdog/watchdog-pm.txt
+++ b/Documentation/watchdog/watchdog-pm.rst
@@ -1,5 +1,7 @@
+===============================================
The Linux WatchDog Timer Power Management Guide
===============================================
+
Last reviewed: 17-Dec-2018
Wolfram Sang <[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 71b4754ea7c3..b0b674f5aaca 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7040,7 +7040,7 @@ F: drivers/media/usb/hdpvr/
HEWLETT PACKARD ENTERPRISE ILO NMI WATCHDOG DRIVER
M: Jerry Hoemann <[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
Convert the TCM docs to ReST format and add them to the
bookset.
This has a mix of userspace-faced and Kernelspace faced
docs. Still, it sounds a better candidate to be added at
the kernel API set of docs.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/target/index.rst | 19 ++
Documentation/target/scripts.rst | 11 +
Documentation/target/tcm_mod_builder.rst | 149 ++++++++++
Documentation/target/tcm_mod_builder.txt | 145 ----------
.../{tcmu-design.txt => tcmu-design.rst} | 268 ++++++++++--------
scripts/documentation-file-ref-check | 2 +-
6 files changed, 326 insertions(+), 268 deletions(-)
create mode 100644 Documentation/target/index.rst
create mode 100644 Documentation/target/scripts.rst
create mode 100644 Documentation/target/tcm_mod_builder.rst
delete mode 100644 Documentation/target/tcm_mod_builder.txt
rename Documentation/target/{tcmu-design.txt => tcmu-design.rst} (69%)
diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst
new file mode 100644
index 000000000000..b68f48982392
--- /dev/null
+++ b/Documentation/target/index.rst
@@ -0,0 +1,19 @@
+:orphan:
+
+==================
+TCM Virtual Device
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ tcmu-design
+ tcm_mod_builder
+ scripts
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/target/scripts.rst b/Documentation/target/scripts.rst
new file mode 100644
index 000000000000..172d42b522e4
--- /dev/null
+++ b/Documentation/target/scripts.rst
@@ -0,0 +1,11 @@
+TCM mod builder script
+----------------------
+
+.. literalinclude:: tcm_mod_builder.py
+ :language: perl
+
+Target export device script
+---------------------------
+
+.. literalinclude:: target-export-device
+ :language: shell
diff --git a/Documentation/target/tcm_mod_builder.rst b/Documentation/target/tcm_mod_builder.rst
new file mode 100644
index 000000000000..9bfc9822e2bd
--- /dev/null
+++ b/Documentation/target/tcm_mod_builder.rst
@@ -0,0 +1,149 @@
+=========================================
+The TCM v4 fabric module script generator
+=========================================
+
+Greetings all,
+
+This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
+script to generate a brand new functional TCM v4 fabric .ko module of your very own,
+that once built can be immediately be loaded to start access the new TCM/ConfigFS
+fabric skeleton, by simply using::
+
+ modprobe $TCM_NEW_MOD
+ mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
+
+This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
+
+ 1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
+ ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
+ into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
+ 2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
+ using a skeleton struct target_core_fabric_ops API template.
+ 3) Based on user defined T10 Proto_Ident for the new fabric module being built,
+ the TransportID / Initiator and Target WWPN related handlers for
+ SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
+ using drivers/target/target_core_fabric_lib.c logic.
+ 4) NOP API calls for all other Data I/O path and fabric dependent attribute logic
+ in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
+
+tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
+$FABRIC_MOD_name' parameters, and actually running the script looks like::
+
+ target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
+ tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
+ Set fabric_mod_name: tcm_nab5000
+ Set fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Using proto_ident: iSCSI
+ Creating fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
+ Using tcm_mod_scan_fabric_ops:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
+ Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
+ Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
+
+At the end of tcm_mod_builder.py. the script will ask to add the following
+line to drivers/target/Kbuild::
+
+ obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
+
+and the same for drivers/target/Kconfig::
+
+ source "drivers/target/tcm_nab5000/Kconfig"
+
+#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item::
+
+ <M> TCM_NAB5000 fabric module
+
+#) Build using 'make modules', once completed you will have::
+
+ target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
+ total 1348
+ drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
+ drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
+ -rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
+ -rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
+ -rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
+ -rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
+ -rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
+ -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
+ -rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
+ -rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
+ -rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
+ -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
+ -rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
+ -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
+ -rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
+ -rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
+ -rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
+ -rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
+ -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
+ -rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
+
+#) Load the new module, create a lun_0 configfs group, and add new TCM Core
+ IBLOCK backstore symlink to port::
+
+ target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
+ target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
+ target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
+
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
+ target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
+ /sys/kernel/config/target/nab5000/
+ |-- discovery_auth
+ |-- iqn.foo
+ | `-- tpgt_1
+ | |-- acls
+ | |-- attrib
+ | |-- lun
+ | | `-- lun_0
+ | | |-- alua_tg_pt_gp
+ | | |-- alua_tg_pt_offline
+ | | |-- alua_tg_pt_status
+ | | |-- alua_tg_pt_write_md
+ | | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
+ | |-- np
+ | `-- param
+ `-- version
+
+ target:/mnt/sdb/lio-core-2.6.git# lsmod
+ Module Size Used by
+ tcm_nab5000 3935 4
+ iscsi_target_mod 193211 0
+ target_core_stgt 8090 0
+ target_core_pscsi 11122 1
+ target_core_file 9172 2
+ target_core_iblock 9280 1
+ target_core_mod 228575 31
+ tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
+ libfc 73681 0
+ scsi_debug 56265 0
+ scsi_tgt 8666 1 target_core_stgt
+ configfs 20644 2 target_core_mod
+
+----------------------------------------------------------------------
+
+Future TODO items
+=================
+
+ 1) Add more T10 proto_idents
+ 2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
+ defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
+ structure members.
+
+October 5th, 2010
+
+Nicholas A. Bellinger <[email protected]>
diff --git a/Documentation/target/tcm_mod_builder.txt b/Documentation/target/tcm_mod_builder.txt
deleted file mode 100644
index ae22f7005540..000000000000
--- a/Documentation/target/tcm_mod_builder.txt
+++ /dev/null
@@ -1,145 +0,0 @@
->>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<<
-
-Greetings all,
-
-This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
-script to generate a brand new functional TCM v4 fabric .ko module of your very own,
-that once built can be immediately be loaded to start access the new TCM/ConfigFS
-fabric skeleton, by simply using:
-
- modprobe $TCM_NEW_MOD
- mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
-
-This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
-
- *) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
- ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
- into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
- *) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
- using a skeleton struct target_core_fabric_ops API template.
- *) Based on user defined T10 Proto_Ident for the new fabric module being built,
- the TransportID / Initiator and Target WWPN related handlers for
- SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
- using drivers/target/target_core_fabric_lib.c logic.
- *) NOP API calls for all other Data I/O path and fabric dependent attribute logic
- in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
-
-tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
-$FABRIC_MOD_name' parameters, and actually running the script looks like:
-
-target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
-tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
-Set fabric_mod_name: tcm_nab5000
-Set fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Using proto_ident: iSCSI
-Creating fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
-Using tcm_mod_scan_fabric_ops:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
-Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
-Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
-
-At the end of tcm_mod_builder.py. the script will ask to add the following
-line to drivers/target/Kbuild:
-
- obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
-
-and the same for drivers/target/Kconfig:
-
- source "drivers/target/tcm_nab5000/Kconfig"
-
-*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:
-
- <M> TCM_NAB5000 fabric module
-
-*) Build using 'make modules', once completed you will have:
-
-target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
-total 1348
-drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
-drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
--rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
--rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
--rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
--rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
--rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
--rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
--rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
--rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
--rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
--rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
--rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
--rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
--rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
--rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
--rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
--rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
--rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
--rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
-
-*) Load the new module, create a lun_0 configfs group, and add new TCM Core
- IBLOCK backstore symlink to port:
-
-target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
-target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
-target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
-
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
-target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
-/sys/kernel/config/target/nab5000/
-|-- discovery_auth
-|-- iqn.foo
-| `-- tpgt_1
-| |-- acls
-| |-- attrib
-| |-- lun
-| | `-- lun_0
-| | |-- alua_tg_pt_gp
-| | |-- alua_tg_pt_offline
-| | |-- alua_tg_pt_status
-| | |-- alua_tg_pt_write_md
-| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
-| |-- np
-| `-- param
-`-- version
-
-target:/mnt/sdb/lio-core-2.6.git# lsmod
-Module Size Used by
-tcm_nab5000 3935 4
-iscsi_target_mod 193211 0
-target_core_stgt 8090 0
-target_core_pscsi 11122 1
-target_core_file 9172 2
-target_core_iblock 9280 1
-target_core_mod 228575 31
-tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
-libfc 73681 0
-scsi_debug 56265 0
-scsi_tgt 8666 1 target_core_stgt
-configfs 20644 2 target_core_mod
-
-----------------------------------------------------------------------
-
-Future TODO items:
-
- *) Add more T10 proto_idents
- *) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
- defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
- structure members.
-
-October 5th, 2010
-Nicholas A. Bellinger <[email protected]>
diff --git a/Documentation/target/tcmu-design.txt b/Documentation/target/tcmu-design.rst
similarity index 69%
rename from Documentation/target/tcmu-design.txt
rename to Documentation/target/tcmu-design.rst
index 4cebc1ebf99a..a7b426707bf6 100644
--- a/Documentation/target/tcmu-design.txt
+++ b/Documentation/target/tcmu-design.rst
@@ -1,25 +1,30 @@
-Contents:
+====================
+TCM Userspace Design
+====================
+
+
+.. Contents:
-1) TCM Userspace Design
- a) Background
- b) Benefits
- c) Design constraints
- d) Implementation overview
- i. Mailbox
- ii. Command ring
- iii. Data Area
- e) Device discovery
- f) Device events
- g) Other contingencies
-2) Writing a user pass-through handler
- a) Discovering and configuring TCMU uio devices
- b) Waiting for events on the device(s)
- c) Managing the command ring
-3) A final note
+ 1) TCM Userspace Design
+ a) Background
+ b) Benefits
+ c) Design constraints
+ d) Implementation overview
+ i. Mailbox
+ ii. Command ring
+ iii. Data Area
+ e) Device discovery
+ f) Device events
+ g) Other contingencies
+ 2) Writing a user pass-through handler
+ a) Discovering and configuring TCMU uio devices
+ b) Waiting for events on the device(s)
+ c) Managing the command ring
+ 3) A final note
TCM Userspace Design
---------------------
+====================
TCM is another name for LIO, an in-kernel iSCSI target (server).
Existing TCM targets run in the kernel. TCMU (TCM in Userspace)
@@ -32,7 +37,8 @@ modules for file, block device, RAM or using another SCSI device as
storage. These are called "backstores" or "storage engines". These
built-in modules are implemented entirely as kernel code.
-Background:
+Background
+----------
In addition to modularizing the transport protocol used for carrying
SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes
@@ -60,7 +66,8 @@ kernel, another approach is to create a userspace pass-through
backstore for LIO, "TCMU".
-Benefits:
+Benefits
+--------
In addition to allowing relatively easy support for RBD and GLFS, TCMU
will also allow easier development of new backstores. TCMU combines
@@ -72,21 +79,25 @@ The disadvantage is there are more distinct components to configure, and
potentially to malfunction. This is unavoidable, but hopefully not
fatal if we're careful to keep things as simple as possible.
-Design constraints:
+Design constraints
+------------------
- Good performance: high throughput, low latency
- Cleanly handle if userspace:
+
1) never attaches
2) hangs
3) dies
4) misbehaves
+
- Allow future flexibility in user & kernel implementations
- Be reasonably memory-efficient
- Simple to configure & run
- Simple to write a userspace backend
-Implementation overview:
+Implementation overview
+-----------------------
The core of the TCMU interface is a memory region that is shared
between kernel and userspace. Within this region is: a control area
@@ -108,7 +119,8 @@ the region mapped at a different virtual address.
See target_core_user.h for the struct definitions.
-The Mailbox:
+The Mailbox
+-----------
The mailbox is always at the start of the shared memory region, and
contains a version, details about the starting offset and size of the
@@ -117,19 +129,27 @@ userspace (respectively) to put commands on the ring, and indicate
when the commands are completed.
version - 1 (userspace should abort if otherwise)
+
flags:
-- TCMU_MAILBOX_FLAG_CAP_OOOC: indicates out-of-order completion is
- supported. See "The Command Ring" for details.
-cmdr_off - The offset of the start of the command ring from the start
-of the memory region, to account for the mailbox size.
-cmdr_size - The size of the command ring. This does *not* need to be a
-power of two.
-cmd_head - Modified by the kernel to indicate when a command has been
-placed on the ring.
-cmd_tail - Modified by userspace to indicate when it has completed
-processing of a command.
+ - TCMU_MAILBOX_FLAG_CAP_OOOC:
+ indicates out-of-order completion is supported.
+ See "The Command Ring" for details.
-The Command Ring:
+cmdr_off
+ The offset of the start of the command ring from the start
+ of the memory region, to account for the mailbox size.
+cmdr_size
+ The size of the command ring. This does *not* need to be a
+ power of two.
+cmd_head
+ Modified by the kernel to indicate when a command has been
+ placed on the ring.
+cmd_tail
+ Modified by userspace to indicate when it has completed
+ processing of a command.
+
+The Command Ring
+----------------
Commands are placed on the ring by the kernel incrementing
mailbox.cmd_head by the size of the command, modulo cmdr_size, and
@@ -180,29 +200,31 @@ opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in
hdr.uflags, update cmd_tail, and proceed with processing additional
commands, if any.
-The Data Area:
+The Data Area
+-------------
This is shared-memory space after the command ring. The organization
of this area is not defined in the TCMU interface, and userspace
should access only the parts referenced by pending iovs.
-Device Discovery:
+Device Discovery
+----------------
Other devices may be using UIO besides TCMU. Unrelated user processes
may also be handling different sets of TCMU devices. TCMU userspace
processes must find their devices by scanning sysfs
class/uio/uio*/name. For TCMU devices, these names will be of the
-format:
+format::
-tcm-user/<hba_num>/<device_name>/<subtype>/<path>
+ tcm-user/<hba_num>/<device_name>/<subtype>/<path>
where "tcm-user" is common for all TCMU-backed UIO devices. <hba_num>
and <device_name> allow userspace to find the device's path in the
kernel target's configfs tree. Assuming the usual mount point, it is
-found at:
+found at::
-/sys/kernel/config/target/core/user_<hba_num>/<device_name>
+ /sys/kernel/config/target/core/user_<hba_num>/<device_name>
This location contains attributes such as "hw_block_size", that
userspace needs to know for correct operation.
@@ -214,15 +236,16 @@ configure the device, if needed. The name cannot contain ':', due to
LIO limitations.
For all devices so discovered, the user handler opens /dev/uioX and
-calls mmap():
+calls mmap()::
-mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
+ mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
where size must be equal to the value read from
/sys/class/uio/uioX/maps/map0/size.
-Device Events:
+Device Events
+-------------
If a new device is added or removed, a notification will be broadcast
over netlink, using a generic netlink family name of "TCM-USER" and a
@@ -233,7 +256,8 @@ the LIO device, so that after determining the device is supported
(based on subtype) it can take the appropriate action.
-Other contingencies:
+Other contingencies
+-------------------
Userspace handler process never attaches:
@@ -258,7 +282,7 @@ Userspace handler process is malicious:
Writing a user pass-through handler (with example code)
--------------------------------------------------------
+=======================================================
A user process handing a TCMU device must support the following:
@@ -277,103 +301,103 @@ TCMU is designed so that multiple unrelated processes can manage TCMU
devices separately. All handlers should make sure to only open their
devices, based opon a known subtype string.
-a) Discovering and configuring TCMU UIO devices:
+a) Discovering and configuring TCMU UIO devices::
-(error checking omitted for brevity)
+ /* error checking omitted for brevity */
-int fd, dev_fd;
-char buf[256];
-unsigned long long map_len;
-void *map;
+ int fd, dev_fd;
+ char buf[256];
+ unsigned long long map_len;
+ void *map;
-fd = open("/sys/class/uio/uio0/name", O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open("/sys/class/uio/uio0/name", O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-/* we only want uio devices whose name is a format we expect */
-if (strncmp(buf, "tcm-user", 8))
+ /* we only want uio devices whose name is a format we expect */
+ if (strncmp(buf, "tcm-user", 8))
exit(-1);
-/* Further checking for subtype also needed here */
+ /* Further checking for subtype also needed here */
-fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-map_len = strtoull(buf, NULL, 0);
+ map_len = strtoull(buf, NULL, 0);
-dev_fd = open("/dev/uio0", O_RDWR);
-map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
+ dev_fd = open("/dev/uio0", O_RDWR);
+ map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
-b) Waiting for events on the device(s)
+ b) Waiting for events on the device(s)
-while (1) {
- char buf[4];
+ while (1) {
+ char buf[4];
- int ret = read(dev_fd, buf, 4); /* will block */
+ int ret = read(dev_fd, buf, 4); /* will block */
- handle_device_events(dev_fd, map);
-}
-
-
-c) Managing the command ring
-
-#include <linux/target_core_user.h>
-
-int handle_device_events(int fd, void *map)
-{
- struct tcmu_mailbox *mb = map;
- struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- int did_some_work = 0;
-
- /* Process events from cmd ring until we catch up with cmd_head */
- while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
-
- if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
- uint8_t *cdb = (void *)mb + ent->req.cdb_off;
- bool success = true;
+ handle_device_events(dev_fd, map);
+ }
- /* Handle command here. */
- printf("SCSI opcode: 0x%x\n", cdb[0]);
- /* Set response fields */
- if (success)
- ent->rsp.scsi_status = SCSI_NO_SENSE;
- else {
- /* Also fill in rsp->sense_buffer here */
- ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+c) Managing the command ring::
+
+ #include <linux/target_core_user.h>
+
+ int handle_device_events(int fd, void *map)
+ {
+ struct tcmu_mailbox *mb = map;
+ struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ int did_some_work = 0;
+
+ /* Process events from cmd ring until we catch up with cmd_head */
+ while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
+
+ if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
+ uint8_t *cdb = (void *)mb + ent->req.cdb_off;
+ bool success = true;
+
+ /* Handle command here. */
+ printf("SCSI opcode: 0x%x\n", cdb[0]);
+
+ /* Set response fields */
+ if (success)
+ ent->rsp.scsi_status = SCSI_NO_SENSE;
+ else {
+ /* Also fill in rsp->sense_buffer here */
+ ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+ }
+ }
+ else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
+ /* Tell the kernel we didn't handle unknown opcodes */
+ ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
+ }
+ else {
+ /* Do nothing for PAD entries except update cmd_tail */
+ }
+
+ /* update cmd_tail */
+ mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
+ ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ did_some_work = 1;
+ }
+
+ /* Notify the kernel that work has been finished */
+ if (did_some_work) {
+ uint32_t buf = 0;
+
+ write(fd, &buf, 4);
+ }
+
+ return 0;
}
- }
- else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
- /* Tell the kernel we didn't handle unknown opcodes */
- ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
- }
- else {
- /* Do nothing for PAD entries except update cmd_tail */
- }
-
- /* update cmd_tail */
- mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
- ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- did_some_work = 1;
- }
-
- /* Notify the kernel that work has been finished */
- if (did_some_work) {
- uint32_t buf = 0;
-
- write(fd, &buf, 4);
- }
-
- return 0;
-}
A final note
-------------
+============
Please be careful to return codes as defined by the SCSI
specifications. These are different than some values defined in the
diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check
index 440227bb55a9..a4139a576726 100755
--- a/scripts/documentation-file-ref-check
+++ b/scripts/documentation-file-ref-check
@@ -124,7 +124,7 @@ while (<IN>) {
# Remove sched-pelt false-positive
next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
- # Discard some build examples from Documentation/target/tcm_mod_builder.txt
+ # Discard some build examples from Documentation/target/tcm_mod_builder.rst
next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
# Check if exists, evaluating wildcards
--
2.21.0
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]>
Acked-by: Federico Vaga <[email protected]>
---
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/locking/index.rst | 24 +++
...{lockdep-design.txt => lockdep-design.rst} | 51 +++--
Documentation/locking/lockstat.rst | 204 ++++++++++++++++++
Documentation/locking/lockstat.txt | 183 ----------------
.../{locktorture.txt => locktorture.rst} | 105 +++++----
.../{mutex-design.txt => mutex-design.rst} | 26 ++-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++++++------
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +--
.../locking/{spinlocks.txt => spinlocks.rst} | 32 ++-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +++----
Documentation/pi-futex.txt | 2 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/rwsem.h | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
lib/Kconfig.debug | 4 +-
20 files changed, 511 insertions(+), 387 deletions(-)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
create mode 100644 Documentation/locking/lockstat.rst
delete mode 100644 Documentation/locking/lockstat.txt
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index 519673df0e82..71a843464ec2 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -1364,7 +1364,7 @@ Futex API reference
Further reading
===============
-- ``Documentation/locking/spinlocks.txt``: Linus Torvalds' spinlocking
+- ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking
tutorial in the kernel sources.
- Unix Systems for Modern Architectures: Symmetric Multiprocessing and
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
new file mode 100644
index 000000000000..ef5da7fe9aac
--- /dev/null
+++ b/Documentation/locking/index.rst
@@ -0,0 +1,24 @@
+:orphan:
+
+=======
+locking
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ lockdep-design
+ lockstat
+ locktorture
+ mutex-design
+ rt-mutex-design
+ rt-mutex
+ spinlocks
+ ww-mutex-design
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.rst
similarity index 93%
rename from Documentation/locking/lockdep-design.txt
rename to Documentation/locking/lockdep-design.rst
index f189d130e543..23fcbc4d3fc0 100644
--- a/Documentation/locking/lockdep-design.txt
+++ b/Documentation/locking/lockdep-design.rst
@@ -2,6 +2,7 @@ Runtime locking correctness validator
=====================================
started by Ingo Molnar <[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.rst b/Documentation/locking/lockstat.rst
new file mode 100644
index 000000000000..536eab8dbd99
--- /dev/null
+++ b/Documentation/locking/lockstat.rst
@@ -0,0 +1,204 @@
+===============
+Lock Statistics
+===============
+
+What
+====
+
+As the name suggests, it provides statistics on locks.
+
+
+Why
+===
+
+Because things like lock contention can severely impact performance.
+
+How
+===
+
+Lockdep already has hooks in the lock functions and maps lock instances to
+lock classes. We build on that (see Documentation/locking/lockdep-design.rst).
+The graph below shows the relation between the lock functions and the various
+hooks therein::
+
+ __acquire
+ |
+ lock _____
+ | \
+ | __contended
+ | |
+ | <wait>
+ | _______/
+ |/
+ |
+ __acquired
+ |
+ .
+ <hold>
+ .
+ |
+ __release
+ |
+ unlock
+
+ lock, unlock - the regular lock functions
+ __* - the hooks
+ <> - states
+
+With these hooks we provide the following statistics:
+
+ con-bounces
+ - number of lock contention that involved x-cpu data
+ contentions
+ - number of lock acquisitions that had to wait
+ wait time
+ min
+ - shortest (non-0) time we ever had to wait for a lock
+ max
+ - longest time we ever had to wait for a lock
+ total
+ - total time we spend waiting on this lock
+ avg
+ - average time spent waiting on this lock
+ acq-bounces
+ - number of lock acquisitions that involved x-cpu data
+ acquisitions
+ - number of times we took the lock
+ hold time
+ min
+ - shortest (non-0) time we ever held the lock
+ max
+ - longest time we ever held the lock
+ total
+ - total time this lock was held
+ avg
+ - average time this lock was held
+
+These numbers are gathered per lock class, per read/write state (when
+applicable).
+
+It also tracks 4 contention points per class. A contention point is a call site
+that had to wait on lock acquisition.
+
+Configuration
+-------------
+
+Lock statistics are enabled via CONFIG_LOCK_STAT.
+
+Usage
+-----
+
+Enable collection of statistics::
+
+ # echo 1 >/proc/sys/kernel/lock_stat
+
+Disable collection of statistics::
+
+ # echo 0 >/proc/sys/kernel/lock_stat
+
+Look at the current lock statistics::
+
+ ( line numbers not part of actual output, done for clarity in the explanation
+ below )
+
+ # less /proc/lock_stat
+
+ 01 lock_stat version 0.4
+ 02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
+ 04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 05
+ 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
+ 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
+ 08 ---------------
+ 09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
+ 10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
+ 13 ---------------
+ 14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
+ 15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
+ 16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 18
+ 19.............................................................................................................................................................................................................................
+ 20
+ 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
+ 22 ---------------
+ 23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+ 27 ---------------
+ 28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+
+
+This excerpt shows the first two lock class statistics. Line 01 shows the
+output version - each time the format changes this will be updated. Line 02-04
+show the header with column descriptions. Lines 05-18 and 20-31 show the actual
+statistics. These statistics come in two parts; the actual stats separated by a
+short separator (line 08, 13) from the contention points.
+
+Lines 09-12 show the first 4 recorded contention points (the code
+which tries to get the lock) and lines 14-17 show the first 4 recorded
+contended points (the lock holder). It is possible that the max
+con-bounces point is missing in the statistics.
+
+The first lock (05-18) is a read/write lock, and shows two lines above the
+short separator. The contention points don't match the column descriptors,
+they have two: contentions and [<IP>] symbol. The second set of contention
+points are the points we're contending with.
+
+The integer part of the time values is in us.
+
+Dealing with nested locks, subclasses may appear::
+
+ 32...........................................................................................................................................................................................................................
+ 33
+ 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
+ 35 ---------
+ 36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
+ 39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
+ 40 ---------
+ 41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 45
+ 46...........................................................................................................................................................................................................................
+ 47
+ 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
+ 49 -----------
+ 50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 51 -----------
+ 52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+
+Line 48 shows statistics for the second subclass (/1) of &rq->lock class
+(subclass starts from 0), since in this case, as line 50 suggests,
+double_rq_lock actually acquires a nested lock of two spinlocks.
+
+View the top contending locks::
+
+ # grep : /proc/lock_stat | head
+ clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
+ tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
+ &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
+ &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
+ &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
+ tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
+ tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
+ rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
+ &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
+ rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
+
+Clear the statistics::
+
+ # echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt
deleted file mode 100644
index fdbeb0c45ef3..000000000000
--- a/Documentation/locking/lockstat.txt
+++ /dev/null
@@ -1,183 +0,0 @@
-
-LOCK STATISTICS
-
-- WHAT
-
-As the name suggests, it provides statistics on locks.
-
-- WHY
-
-Because things like lock contention can severely impact performance.
-
-- HOW
-
-Lockdep already has hooks in the lock functions and maps lock instances to
-lock classes. We build on that (see Documentation/locking/lockdep-design.txt).
-The graph below shows the relation between the lock functions and the various
-hooks therein.
-
- __acquire
- |
- lock _____
- | \
- | __contended
- | |
- | <wait>
- | _______/
- |/
- |
- __acquired
- |
- .
- <hold>
- .
- |
- __release
- |
- unlock
-
-lock, unlock - the regular lock functions
-__* - the hooks
-<> - states
-
-With these hooks we provide the following statistics:
-
- con-bounces - number of lock contention that involved x-cpu data
- contentions - number of lock acquisitions that had to wait
- wait time min - shortest (non-0) time we ever had to wait for a lock
- max - longest time we ever had to wait for a lock
- total - total time we spend waiting on this lock
- avg - average time spent waiting on this lock
- acq-bounces - number of lock acquisitions that involved x-cpu data
- acquisitions - number of times we took the lock
- hold time min - shortest (non-0) time we ever held the lock
- max - longest time we ever held the lock
- total - total time this lock was held
- avg - average time this lock was held
-
-These numbers are gathered per lock class, per read/write state (when
-applicable).
-
-It also tracks 4 contention points per class. A contention point is a call site
-that had to wait on lock acquisition.
-
- - CONFIGURATION
-
-Lock statistics are enabled via CONFIG_LOCK_STAT.
-
- - USAGE
-
-Enable collection of statistics:
-
-# echo 1 >/proc/sys/kernel/lock_stat
-
-Disable collection of statistics:
-
-# echo 0 >/proc/sys/kernel/lock_stat
-
-Look at the current lock statistics:
-
-( line numbers not part of actual output, done for clarity in the explanation
- below )
-
-# less /proc/lock_stat
-
-01 lock_stat version 0.4
-02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
-04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-05
-06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
-07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
-08 ---------------
-09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
-10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
-13 ---------------
-14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
-15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
-16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-18
-19.............................................................................................................................................................................................................................
-20
-21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
-22 ---------------
-23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-27 ---------------
-28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-
-
-This excerpt shows the first two lock class statistics. Line 01 shows the
-output version - each time the format changes this will be updated. Line 02-04
-show the header with column descriptions. Lines 05-18 and 20-31 show the actual
-statistics. These statistics come in two parts; the actual stats separated by a
-short separator (line 08, 13) from the contention points.
-
-Lines 09-12 show the first 4 recorded contention points (the code
-which tries to get the lock) and lines 14-17 show the first 4 recorded
-contended points (the lock holder). It is possible that the max
-con-bounces point is missing in the statistics.
-
-The first lock (05-18) is a read/write lock, and shows two lines above the
-short separator. The contention points don't match the column descriptors,
-they have two: contentions and [<IP>] symbol. The second set of contention
-points are the points we're contending with.
-
-The integer part of the time values is in us.
-
-Dealing with nested locks, subclasses may appear:
-
-32...........................................................................................................................................................................................................................
-33
-34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
-35 ---------
-36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
-39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
-40 ---------
-41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
-45
-46...........................................................................................................................................................................................................................
-47
-48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
-49 -----------
-50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-51 -----------
-52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
-54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-
-Line 48 shows statistics for the second subclass (/1) of &rq->lock class
-(subclass starts from 0), since in this case, as line 50 suggests,
-double_rq_lock actually acquires a nested lock of two spinlocks.
-
-View the top contending locks:
-
-# grep : /proc/lock_stat | head
- clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
- tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
- &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
- &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
- &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
- tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
- tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
- rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
- &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
- rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
-
-Clear the statistics:
-
-# echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.rst
similarity index 57%
rename from Documentation/locking/locktorture.txt
rename to Documentation/locking/locktorture.rst
index 6a8df4cd19bf..e79eeeca3ac6 100644
--- a/Documentation/locking/locktorture.txt
+++ b/Documentation/locking/locktorture.rst
@@ -1,6 +1,9 @@
+==================================
Kernel Lock Torture Test Operation
+==================================
CONFIG_LOCK_TORTURE_TEST
+========================
The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
that runs torture tests on core kernel locking primitives. The kernel
@@ -18,61 +21,77 @@ can be simulated by either enlarging this critical region hold time and/or
creating more kthreads.
-MODULE PARAMETERS
+Module Parameters
+=================
This module has the following parameters:
- ** Locktorture-specific **
+Locktorture-specific
+--------------------
-nwriters_stress Number of kernel threads that will stress exclusive lock
+nwriters_stress
+ Number of kernel threads that will stress exclusive lock
ownership (writers). The default value is twice the number
of online CPUs.
-nreaders_stress Number of kernel threads that will stress shared lock
+nreaders_stress
+ Number of kernel threads that will stress shared lock
ownership (readers). The default is the same amount of writer
locks. If the user did not specify nwriters_stress, then
both readers and writers be the amount of online CPUs.
-torture_type Type of lock to torture. By default, only spinlocks will
+torture_type
+ Type of lock to torture. By default, only spinlocks will
be tortured. This module can torture the following locks,
with string values as follows:
- o "lock_busted": Simulates a buggy lock implementation.
+ - "lock_busted":
+ Simulates a buggy lock implementation.
- o "spin_lock": spin_lock() and spin_unlock() pairs.
+ - "spin_lock":
+ spin_lock() and spin_unlock() pairs.
- o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq()
- pairs.
+ - "spin_lock_irq":
+ spin_lock_irq() and spin_unlock_irq() pairs.
- o "rw_lock": read/write lock() and unlock() rwlock pairs.
+ - "rw_lock":
+ read/write lock() and unlock() rwlock pairs.
- o "rw_lock_irq": read/write lock_irq() and unlock_irq()
- rwlock pairs.
+ - "rw_lock_irq":
+ read/write lock_irq() and unlock_irq()
+ rwlock pairs.
- o "mutex_lock": mutex_lock() and mutex_unlock() pairs.
+ - "mutex_lock":
+ mutex_lock() and mutex_unlock() pairs.
- o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock()
- pairs. Kernel must have CONFIG_RT_MUTEX=y.
+ - "rtmutex_lock":
+ rtmutex_lock() and rtmutex_unlock() pairs.
+ Kernel must have CONFIG_RT_MUTEX=y.
- o "rwsem_lock": read/write down() and up() semaphore pairs.
+ - "rwsem_lock":
+ read/write down() and up() semaphore pairs.
- ** Torture-framework (RCU + locking) **
+Torture-framework (RCU + locking)
+---------------------------------
-shutdown_secs The number of seconds to run the test before terminating
+shutdown_secs
+ The number of seconds to run the test before terminating
the test and powering off the system. The default is
zero, which disables test termination and system shutdown.
This capability is useful for automated testing.
-onoff_interval The number of seconds between each attempt to execute a
+onoff_interval
+ The number of seconds between each attempt to execute a
randomly selected CPU-hotplug operation. Defaults
to zero, which disables CPU hotplugging. In
CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
refuse to do any CPU-hotplug operations regardless of
what value is specified for onoff_interval.
-onoff_holdoff The number of seconds to wait until starting CPU-hotplug
+onoff_holdoff
+ The number of seconds to wait until starting CPU-hotplug
operations. This would normally only be used when
locktorture was built into the kernel and started
automatically at boot time, in which case it is useful
@@ -80,53 +99,59 @@ onoff_holdoff The number of seconds to wait until starting CPU-hotplug
coming and going. This parameter is only useful if
CONFIG_HOTPLUG_CPU is enabled.
-stat_interval Number of seconds between statistics-related printk()s.
+stat_interval
+ Number of seconds between statistics-related printk()s.
By default, locktorture will report stats every 60 seconds.
Setting the interval to zero causes the statistics to
be printed -only- when the module is unloaded, and this
is the default.
-stutter The length of time to run the test before pausing for this
+stutter
+ The length of time to run the test before pausing for this
same period of time. Defaults to "stutter=5", so as
to run and pause for (roughly) five-second intervals.
Specifying "stutter=0" causes the test to run continuously
without pausing, which is the old default behavior.
-shuffle_interval The number of seconds to keep the test threads affinitied
+shuffle_interval
+ The number of seconds to keep the test threads affinitied
to a particular subset of the CPUs, defaults to 3 seconds.
Used in conjunction with test_no_idle_hz.
-verbose Enable verbose debugging printing, via printk(). Enabled
+verbose
+ Enable verbose debugging printing, via printk(). Enabled
by default. This extra information is mostly related to
high-level errors and reports from the main 'torture'
framework.
-STATISTICS
+Statistics
+==========
-Statistics are printed in the following format:
+Statistics are printed in the following format::
-spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
- (A) (B) (C) (D) (E)
+ spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
+ (A) (B) (C) (D) (E)
-(A): Lock type that is being tortured -- torture_type parameter.
+ (A): Lock type that is being tortured -- torture_type parameter.
-(B): Number of writer lock acquisitions. If dealing with a read/write primitive
- a second "Reads" statistics line is printed.
+ (B): Number of writer lock acquisitions. If dealing with a read/write
+ primitive a second "Reads" statistics line is printed.
-(C): Number of times the lock was acquired.
+ (C): Number of times the lock was acquired.
-(D): Min and max number of times threads failed to acquire the lock.
+ (D): Min and max number of times threads failed to acquire the lock.
-(E): true/false values if there were errors acquiring the lock. This should
- -only- be positive if there is a bug in the locking primitive's
- implementation. Otherwise a lock should never fail (i.e., spin_lock()).
- Of course, the same applies for (C), above. A dummy example of this is
- the "lock_busted" type.
+ (E): true/false values if there were errors acquiring the lock. This should
+ -only- be positive if there is a bug in the locking primitive's
+ implementation. Otherwise a lock should never fail (i.e., spin_lock()).
+ Of course, the same applies for (C), above. A dummy example of this is
+ the "lock_busted" type.
-USAGE
+Usage
+=====
-The following script may be used to torture locks:
+The following script may be used to torture locks::
#!/bin/sh
diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.rst
similarity index 94%
rename from Documentation/locking/mutex-design.txt
rename to Documentation/locking/mutex-design.rst
index 818aca19612f..4d8236b81fa5 100644
--- a/Documentation/locking/mutex-design.txt
+++ b/Documentation/locking/mutex-design.rst
@@ -1,6 +1,9 @@
+=======================
Generic Mutex Subsystem
+=======================
started by Ingo Molnar <[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
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.
Also, removed the Maintained by, as requested by Geert.
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} | 80 ++--
Documentation/fb/{gxfb.txt => gxfb.rst} | 24 +-
Documentation/fb/index.rst | 50 ++
.../fb/{intel810.txt => intel810.rst} | 79 ++--
Documentation/fb/{intelfb.txt => intelfb.rst} | 62 +--
.../fb/{internals.txt => internals.rst} | 24 +-
Documentation/fb/{lxfb.txt => lxfb.rst} | 25 +-
Documentation/fb/matroxfb.rst | 443 ++++++++++++++++++
Documentation/fb/matroxfb.txt | 413 ----------------
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/pvr2fb.rst | 66 +++
Documentation/fb/pvr2fb.txt | 65 ---
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +++-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
Documentation/fb/sh7760fb.rst | 130 +++++
Documentation/fb/sh7760fb.txt | 131 ------
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/sstfb.rst | 207 ++++++++
Documentation/fb/sstfb.txt | 174 -------
Documentation/fb/{tgafb.txt => tgafb.rst} | 30 +-
.../fb/{tridentfb.txt => tridentfb.rst} | 36 +-
Documentation/fb/{udlfb.txt => udlfb.rst} | 55 ++-
Documentation/fb/{uvesafb.txt => uvesafb.rst} | 128 ++---
Documentation/fb/{vesafb.txt => vesafb.rst} | 121 ++---
Documentation/fb/viafb.rst | 297 ++++++++++++
Documentation/fb/viafb.txt | 252 ----------
.../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +-
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 +-
47 files changed, 1944 insertions(+), 1657 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%)
create mode 100644 Documentation/fb/matroxfb.rst
delete mode 100644 Documentation/fb/matroxfb.txt
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
create mode 100644 Documentation/fb/pvr2fb.rst
delete mode 100644 Documentation/fb/pvr2fb.txt
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
create mode 100644 Documentation/fb/sh7760fb.rst
delete mode 100644 Documentation/fb/sh7760fb.txt
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
create mode 100644 Documentation/fb/sstfb.rst
delete mode 100644 Documentation/fb/sstfb.txt
rename Documentation/fb/{tgafb.txt => tgafb.rst} (71%)
rename Documentation/fb/{tridentfb.txt => tridentfb.rst} (70%)
rename Documentation/fb/{udlfb.txt => udlfb.rst} (77%)
rename Documentation/fb/{uvesafb.txt => uvesafb.rst} (52%)
rename Documentation/fb/{vesafb.txt => vesafb.rst} (57%)
create mode 100644 Documentation/fb/viafb.rst
delete mode 100644 Documentation/fb/viafb.txt
rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 83e64d779887..581d8888e829 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..7fe087310c82 100644
--- a/Documentation/fb/framebuffer.txt
+++ b/Documentation/fb/framebuffer.rst
@@ -1,7 +1,7 @@
- The Frame Buffer Device
- -----------------------
+=======================
+The Frame Buffer Device
+=======================
-Maintained by Geert Uytterhoeven <[email protected]>
Last revised: May 10, 2001
@@ -26,7 +26,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 +34,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 +54,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 +90,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 +113,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 +129,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 +146,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 +172,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 +212,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 +256,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 +272,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 +312,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 +340,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.rst b/Documentation/fb/matroxfb.rst
new file mode 100644
index 000000000000..f1859d98606e
--- /dev/null
+++ b/Documentation/fb/matroxfb.rst
@@ -0,0 +1,443 @@
+=================
+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.
+
+Advantages:
+
+ * It provides a nice large console (128 cols + 48 lines with 1024x768)
+ without using tiny, unreadable fonts.
+ * You can run XF{68,86}_FBDev or XFree86 fbdev driver on top of /dev/fb0
+ * Most important: boot logo :-)
+
+Disadvantages:
+
+ * graphic mode is slower than text mode... but you should not notice
+ if you use same resolution as you used in textmode.
+
+
+How to use it?
+==============
+
+Switching modes is done using the video=matroxfb:vesa:... boot parameter
+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.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
+(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`.
+
+
+X11
+===
+
+XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel
+architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp
+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
+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.
+
+
+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.
+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.
+
+
+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 `:`).
+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.
+ 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
+ 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).
+============ ===================================================================
+
+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`.
+============ ===================================================================
+
+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
+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.
+============ ==================================================================
+
+
+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
+ 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,
+ but I'm not sure.
+ - 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...
+
+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
+
+ 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
+ (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
+ G16V16 are not supported
+ - 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
+ specify vslen=4000 and so on).
+ - maybe more...
+
+And following features:
+
+ - 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
+ 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
+ Millennium I/II and SVGALib compatibility.
+
+
+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
+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::
+
+ 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
+ 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
+
+ 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
+
+ TEXT
+ 8x16
+ Millennium I G200
+ TEXT 3.29 1.50
+
+ * Yes, it is slower than Millennium I.
+
+
+Dualhead G400
+=============
+Driver supports dualhead G400 with some limitations:
+ + secondary head shares videomemory with primary head. It is not problem
+ if you have 32MB of videoram, but if you have only 16MB, you may have
+ to think twice before choosing videomode (for example twice 1880x1440x32bpp
+ is not possible).
+ + due to hardware limitation, secondary head can use only 16 and 32bpp
+ videomodes.
+ + secondary head is not accelerated. There were bad problems with accelerated
+ XFree when secondary head used to use acceleration.
+ + secondary head always powerups in 640x480@60-32 videomode. You have to use
+ fbset to change this mode.
+ + secondary head always powerups in monitor mode. You have to use fbmatroxset
+ to change it to TV mode. Also, you must select at least 525 lines for
+ NTSC output and 625 lines for PAL output.
+ + kernel is not fully multihead ready. So some things are impossible to do.
+ + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
+ and matroxfb_crtc2 into kernel.
+
+
+Dualhead G450
+=============
+Driver supports dualhead G450 with some limitations:
+ + secondary head shares videomemory with primary head. It is not problem
+ if you have 32MB of videoram, but if you have only 16MB, you may have
+ to think twice before choosing videomode.
+ + due to hardware limitation, secondary head can use only 16 and 32bpp
+ videomodes.
+ + secondary head is not accelerated.
+ + secondary head always powerups in 640x480@60-32 videomode. You have to use
+ fbset to change this mode.
+ + TV output is not supported
+ + 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/matroxfb.txt b/Documentation/fb/matroxfb.txt
deleted file mode 100644
index b95f5bb522f2..000000000000
--- a/Documentation/fb/matroxfb.txt
+++ /dev/null
@@ -1,413 +0,0 @@
-[This file is cloned from VesaFB. Thanks go to Gerd Knorr]
-
-What is matroxfb?
-=================
-
-This is a driver for a graphic framebuffer for Matrox devices on
-Alpha, Intel and PPC boxes.
-
-Advantages:
-
- * It provides a nice large console (128 cols + 48 lines with 1024x768)
- without using tiny, unreadable fonts.
- * You can run XF{68,86}_FBDev or XFree86 fbdev driver on top of /dev/fb0
- * Most important: boot logo :-)
-
-Disadvantages:
-
- * graphic mode is slower than text mode... but you should not notice
- if you use same resolution as you used in textmode.
-
-
-How to use it?
-==============
-
-Switching modes is done using the video=matroxfb:vesa:... boot parameter
-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).
-
-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
-(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'.
-
-
-X11
-===
-
-XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel
-architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp
-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
-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.
-
-
-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.
-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.
-
-
-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 `:').
-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.
- 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
- 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).
-
-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'.
-
-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
-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.
-
-
-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
- 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,
- but I'm not sure.
- + 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...
-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
- 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
- (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
- G16V16 are not supported
- + 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
- specify vslen=4000 and so on).
- + maybe more...
-And following features:
- + 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
- 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
- Millennium I/II and SVGALib compatibility.
-
-
-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
-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.
-
-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
- 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
-
-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
-
-TEXT
- 8x16
- Millennium I G200
-TEXT 3.29 1.50
-
-* Yes, it is slower than Millennium I.
-
-
-Dualhead G400
-=============
-Driver supports dualhead G400 with some limitations:
- + secondary head shares videomemory with primary head. It is not problem
- if you have 32MB of videoram, but if you have only 16MB, you may have
- to think twice before choosing videomode (for example twice 1880x1440x32bpp
- is not possible).
- + due to hardware limitation, secondary head can use only 16 and 32bpp
- videomodes.
- + secondary head is not accelerated. There were bad problems with accelerated
- XFree when secondary head used to use acceleration.
- + secondary head always powerups in 640x480@60-32 videomode. You have to use
- fbset to change this mode.
- + secondary head always powerups in monitor mode. You have to use fbmatroxset
- to change it to TV mode. Also, you must select at least 525 lines for
- NTSC output and 625 lines for PAL output.
- + kernel is not fully multihead ready. So some things are impossible to do.
- + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
- and matroxfb_crtc2 into kernel.
-
-
-Dualhead G450
-=============
-Driver supports dualhead G450 with some limitations:
- + secondary head shares videomemory with primary head. It is not problem
- if you have 32MB of videoram, but if you have only 16MB, you may have
- to think twice before choosing videomode.
- + due to hardware limitation, secondary head can use only 16 and 32bpp
- videomodes.
- + secondary head is not accelerated.
- + secondary head always powerups in 640x480@60-32 videomode. You have to use
- fbset to change this mode.
- + TV output is not supported
- + 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.rst b/Documentation/fb/pvr2fb.rst
new file mode 100644
index 000000000000..fcf2c21c8fcf
--- /dev/null
+++ b/Documentation/fb/pvr2fb.rst
@@ -0,0 +1,66 @@
+===============
+What is pvr2fb?
+===============
+
+This is a driver for PowerVR 2 based graphics frame buffers, such as the
+one found in the Dreamcast.
+
+Advantages:
+
+ * It provides a nice large console (128 cols + 48 lines with 1024x768)
+ without using tiny, unreadable fonts (NOT on the Dreamcast)
+ * You can run XF86_FBDev on top of /dev/fb0
+ * Most important: boot logo :-)
+
+Disadvantages:
+
+ * Driver is largely untested on non-Dreamcast systems.
+
+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 `:`).
+
+Accepted options:
+
+========== ==================================================================
+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.
+
+inverse invert colors on screen (for LCD displays)
+
+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.
+
+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
+===
+
+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/pvr2fb.txt b/Documentation/fb/pvr2fb.txt
deleted file mode 100644
index 36bdeff585e2..000000000000
--- a/Documentation/fb/pvr2fb.txt
+++ /dev/null
@@ -1,65 +0,0 @@
-$Id: pvr2fb.txt,v 1.1 2001/05/24 05:09:16 mrbrown Exp $
-
-What is pvr2fb?
-===============
-
-This is a driver for PowerVR 2 based graphics frame buffers, such as the
-one found in the Dreamcast.
-
-Advantages:
-
- * It provides a nice large console (128 cols + 48 lines with 1024x768)
- without using tiny, unreadable fonts (NOT on the Dreamcast)
- * You can run XF86_FBDev on top of /dev/fb0
- * Most important: boot logo :-)
-
-Disadvantages:
-
- * Driver is largely untested on non-Dreamcast systems.
-
-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 `:').
-Accepted options:
-
-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.
-
-inverse - invert colors on screen (for LCD displays)
-
-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.
-
-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
-===
-
-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.rst b/Documentation/fb/sh7760fb.rst
new file mode 100644
index 000000000000..c3266485f810
--- /dev/null
+++ b/Documentation/fb/sh7760fb.rst
@@ -0,0 +1,130 @@
+================================================
+SH7760/SH7763 integrated LCDC Framebuffer driver
+================================================
+
+0. Overview
+-----------
+The SH7760/SH7763 have an integrated LCD Display controller (LCDC) which
+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
+ get a large enough contiguous chunk of memory.
+
+* The driver does not support changing resolution while loaded
+ (displays aren't hotpluggable anyway)
+
+* Heavy flickering may be observed
+ a) if you're using 15/16bit color modes at >= 640x480 px resolutions,
+ b) during PCMCIA (or any other slow bus) activity.
+
+* 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.rst
+
+1. Platform setup
+-----------------
+SH7760:
+ Video data is fetched via the DMABRG DMA engine, so you have to
+ configure the SH DMAC for DMABRG mode (write 0x94808080 to the
+ DMARSRA register somewhere at boot).
+
+ PFC registers PCCR and PCDR must be set to peripheral mode.
+ (write zeros to both).
+
+The driver does NOT do the above for you since board setup is, well, job
+of the board setup code.
+
+2. Panel definitions
+--------------------
+The LCDC must explicitly be told about the type of LCD panel
+attached. Data must be wrapped in a "struct sh7760fb_platdata" and
+passed to the driver as platform_data.
+
+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::
+
+ #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,
+ };
+
+ 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,
+ },
+ };
+
+ 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/sh7760fb.txt b/Documentation/fb/sh7760fb.txt
deleted file mode 100644
index b994c3b10549..000000000000
--- a/Documentation/fb/sh7760fb.txt
+++ /dev/null
@@ -1,131 +0,0 @@
-SH7760/SH7763 integrated LCDC Framebuffer driver
-================================================
-
-0. Overview
------------
-The SH7760/SH7763 have an integrated LCD Display controller (LCDC) which
-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
- get a large enough contiguous chunk of memory.
-
-* The driver does not support changing resolution while loaded
- (displays aren't hotpluggable anyway)
-
-* Heavy flickering may be observed
- a) if you're using 15/16bit color modes at >= 640x480 px resolutions,
- b) during PCMCIA (or any other slow bus) activity.
-
-* 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
-
-1. Platform setup
------------------
-SH7760:
- Video data is fetched via the DMABRG DMA engine, so you have to
- configure the SH DMAC for DMABRG mode (write 0x94808080 to the
- DMARSRA register somewhere at boot).
-
- PFC registers PCCR and PCDR must be set to peripheral mode.
- (write zeros to both).
-
-The driver does NOT do the above for you since board setup is, well, job
-of the board setup code.
-
-2. Panel definitions
---------------------
-The LCDC must explicitly be told about the type of LCD panel
-attached. Data must be wrapped in a "struct sh7760fb_platdata" and
-passed to the driver as platform_data.
-
-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:
-
-====================== cut here ======================================
-
-#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,
-};
-
-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,
- },
-};
-
-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 ======================================
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.rst b/Documentation/fb/sstfb.rst
new file mode 100644
index 000000000000..8e8c1b940359
--- /dev/null
+++ b/Documentation/fb/sstfb.rst
@@ -0,0 +1,207 @@
+=====
+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)
+
+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
+============
+
+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 :)
+
+
+Module Usage
+============
+
+.. 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
+ 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:
+ 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
+
+ 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
+ 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" ...
+
+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
+
+
+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:
+
+=============== =============== ===============================================
+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.
+ doesn't work yet...
+
+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.
+
+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
+ 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.
+
+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 ...
+
+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 ...
+
+Ghozlane Toumi <[email protected]>
+
+
+Date: 2002/05/09 20:11:45
+
+http://sstfb.sourceforge.net/README
diff --git a/Documentation/fb/sstfb.txt b/Documentation/fb/sstfb.txt
deleted file mode 100644
index 13db1075e4a5..000000000000
--- a/Documentation/fb/sstfb.txt
+++ /dev/null
@@ -1,174 +0,0 @@
-
-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)
-
- 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
-
- 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 :)
-
-
-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
- 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
- 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:
- 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
- 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
- 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" ...
-
- 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
-
-
-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 :
-
-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.
- doesn't work yet...
-
-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.
-
-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
- 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 .
-
-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 ...
-
-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 ...
-
-ghoz.
-
---
-Ghozlane Toumi <[email protected]>
-
-
-$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.rst b/Documentation/fb/viafb.rst
new file mode 100644
index 000000000000..8eb7a3bb068c
--- /dev/null
+++ b/Documentation/fb/viafb.rst
@@ -0,0 +1,297 @@
+=======================================================
+VIA Integration Graphic Chip Console Framebuffer Driver
+=======================================================
+
+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)
+
+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)
+
+ color depth: 8 bpp, 16 bpp, 32 bpp supports.
+
+ Support 2D hardware accelerator.
+
+Using the viafb module
+----------------------
+ Start viafb with default settings::
+
+ #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
+
+ viafb_bpp:
+ - 8, 16, 32 (default:32)
+
+ viafb_refresh:
+ - 60, 75, 85, 100, 120 (default:60)
+
+ viafb_lcd_dsp_method:
+ - 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
+
+ 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
+
+ - 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)
+
+ viafb_SAMM_ON:
+ - 0 : viafb_SAMM_ON disable (default)
+ - 1 : viafb_SAMM_ON enable
+
+ viafb_mode1: (secondary display device)
+ - 640x480 (default)
+ - 720x480
+ - 800x600
+ - 1024x768
+
+ viafb_bpp1: (secondary display device)
+ - 8, 16, 32 (default:32)
+
+ viafb_refresh1: (secondary display device)
+ - 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...
+
+ 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)
+
+ viafb_second_size:
+ 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
+
+ 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
+
+ viafb_device_lcd_dualedge:
+ 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...
+
+Notes:
+ 1. CRT may not display properly for DuoView CRT & DVI display at
+ the "640x480" PAL mode with DVI overscan enabled.
+ 2. SAMM stands for single adapter multi monitors. It is different from
+ multi-head since SAMM support multi monitor at driver layers, thus fbcon
+ layer doesn't even know about it; SAMM's second screen doesn't have a
+ device node file, thus a user mode application can't access it directly.
+ When SAMM is enabled, viafb_mode and viafb_mode1, viafb_bpp and
+ viafb_bpp1, viafb_refresh and viafb_refresh1 can be different.
+ 3. When console is depending on viafbinfo1, dynamically change resolution
+ and bpp, need to call VIAFB specified ioctl interface VIAFB_SET_DEVICE
+ instead of calling common ioctl function FBIOPUT_VSCREENINFO since
+ viafb doesn't support multi-head well, or it will cause screen crush.
+
+
+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>
+
+ 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>
+
+ example::
+
+ # 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::
+
+ append = "video=viafb:viafb_mode=1024x768,viafb_bpp=32,viafb_refresh=85"
+
+
+VIA Framebuffer modes
+=====================
+
+.. include:: viafb.modes
+ :literal:
diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.txt
deleted file mode 100644
index 1cb2462a71ce..000000000000
--- a/Documentation/fb/viafb.txt
+++ /dev/null
@@ -1,252 +0,0 @@
-
- VIA Integration Graphic Chip Console Framebuffer Driver
-
-[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)
-
-[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)
-
- color depth: 8 bpp, 16 bpp, 32 bpp supports.
-
- Support 2D hardware accelerator.
-
-[Using the viafb module]
--- -- --------------------
- Start viafb with default settings:
- #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
- ......
-
- viafb_bpp:
- 8, 16, 32 (default:32)
-
- viafb_refresh:
- 60, 75, 85, 100, 120 (default:60)
-
- viafb_lcd_dsp_method:
- 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
-
- 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
-
- 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)
-
- viafb_SAMM_ON:
- 0 : viafb_SAMM_ON disable (default)
- 1 : viafb_SAMM_ON enable
-
- viafb_mode1: (secondary display device)
- 640x480 (default)
- 720x480
- 800x600
- 1024x768
- ... ...
-
- viafb_bpp1: (secondary display device)
- 8, 16, 32 (default:32)
-
- viafb_refresh1: (secondary display device)
- 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...
-
- 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)
-
- viafb_second_size:
- 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
-
- 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
-
- viafb_device_lcd_dualedge:
- 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...
-
-Notes:
- 1. CRT may not display properly for DuoView CRT & DVI display at
- the "640x480" PAL mode with DVI overscan enabled.
- 2. SAMM stands for single adapter multi monitors. It is different from
- multi-head since SAMM support multi monitor at driver layers, thus fbcon
- layer doesn't even know about it; SAMM's second screen doesn't have a
- device node file, thus a user mode application can't access it directly.
- When SAMM is enabled, viafb_mode and viafb_mode1, viafb_bpp and
- viafb_bpp1, viafb_refresh and viafb_refresh1 can be different.
- 3. When console is depending on viafbinfo1, dynamically change resolution
- and bpp, need to call VIAFB specified ioctl interface VIAFB_SET_DEVICE
- instead of calling common ioctl function FBIOPUT_VSCREENINFO since
- viafb doesn't support multi-head well, or it will cause screen crush.
-
-
-[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>
-
- 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>
-
- example,
- # 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:
- append = "video=viafb:viafb_mode=1024x768,viafb_bpp=32,viafb_refresh=85"
-
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 aa9a382d6da5..5ed1fc93969a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4808,7 +4808,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]>
@@ -7957,7 +7957,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
@@ -14405,7 +14405,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]>
@@ -14475,7 +14475,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
@@ -16682,7 +16682,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 df4c40e28f05..2315a5b72d71 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.
@@ -615,7 +615,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.
@@ -630,7 +630,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"
@@ -828,7 +828,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"
@@ -991,7 +991,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"
@@ -1061,7 +1061,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"
@@ -1098,7 +1098,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"
@@ -1249,7 +1249,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.
@@ -1511,7 +1511,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
@@ -1543,7 +1543,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.
@@ -1783,7 +1783,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]>
Acked-by: Federico Vaga <[email protected]>
---
...ault-injection.txt => fault-injection.rst} | 265 +++++++++---------
Documentation/fault-injection/index.rst | 20 ++
...r-inject.txt => notifier-error-inject.rst} | 18 +-
.../fault-injection/nvme-fault-injection.rst | 120 ++++++++
.../fault-injection/nvme-fault-injection.txt | 116 --------
.../fault-injection/provoke-crashes.rst | 48 ++++
.../fault-injection/provoke-crashes.txt | 38 ---
Documentation/process/4.Coding.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
include/linux/fault-inject.h | 2 +-
lib/Kconfig.debug | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
14 files changed, 344 insertions(+), 295 deletions(-)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
create mode 100644 Documentation/fault-injection/nvme-fault-injection.rst
delete mode 100644 Documentation/fault-injection/nvme-fault-injection.txt
create mode 100644 Documentation/fault-injection/provoke-crashes.rst
delete mode 100644 Documentation/fault-injection/provoke-crashes.txt
diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.rst
similarity index 68%
rename from Documentation/fault-injection/fault-injection.txt
rename to Documentation/fault-injection/fault-injection.rst
index a17517a083c3..f51bb21d20e4 100644
--- a/Documentation/fault-injection/fault-injection.txt
+++ b/Documentation/fault-injection/fault-injection.rst
@@ -1,3 +1,4 @@
+===========================================
Fault injection capabilities infrastructure
===========================================
@@ -7,36 +8,36 @@ See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug.
Available fault injection capabilities
--------------------------------------
-o failslab
+- failslab
injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
-o fail_page_alloc
+- fail_page_alloc
injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
-o fail_futex
+- fail_futex
injects futex deadlock and uaddr fault errors.
-o fail_make_request
+- fail_make_request
injects disk IO errors on devices permitted by setting
/sys/block/<device>/make-it-fail or
/sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
-o fail_mmc_request
+- fail_mmc_request
injects MMC data errors on devices permitted by setting
debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
-o fail_function
+- fail_function
injects error return on specific functions, which are marked by
ALLOW_ERROR_INJECTION() macro, by setting debugfs entries
under /sys/kernel/debug/fail_function. No boot option supported.
-o NVMe fault injection
+- NVMe fault injection
inject NVMe status code and retry flag on devices permitted by setting
debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default
@@ -47,7 +48,8 @@ o NVMe fault injection
Configure fault-injection capabilities behavior
-----------------------------------------------
-o debugfs entries
+debugfs entries
+^^^^^^^^^^^^^^^
fault-inject-debugfs kernel module provides some debugfs entries for runtime
configuration of fault-injection capabilities.
@@ -55,6 +57,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/probability:
likelihood of failure injection, in percent.
+
Format: <percent>
Note that one-failure-per-hundred is a very high error rate
@@ -83,6 +86,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/verbose
Format: { 0 | 1 | 2 }
+
specifies the verbosity of the messages when failure is
injected. '0' means no messages; '1' will print only a single
log line per failure; '2' will print a call trace too -- useful
@@ -91,14 +95,15 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/task-filter:
Format: { 'Y' | 'N' }
+
A value of 'N' disables filtering by process (default).
Any positive value limits failures to only processes indicated by
/proc/<pid>/make-it-fail==1.
-- /sys/kernel/debug/fail*/require-start:
-- /sys/kernel/debug/fail*/require-end:
-- /sys/kernel/debug/fail*/reject-start:
-- /sys/kernel/debug/fail*/reject-end:
+- /sys/kernel/debug/fail*/require-start,
+ /sys/kernel/debug/fail*/require-end,
+ /sys/kernel/debug/fail*/reject-start,
+ /sys/kernel/debug/fail*/reject-end:
specifies the range of virtual addresses tested during
stacktrace walking. Failure is injected only if some caller
@@ -116,6 +121,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' won't inject failures into
highmem/user allocations.
@@ -123,6 +129,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will inject failures
only into non-sleep allocations (GFP_ATOMIC allocations).
@@ -134,12 +141,14 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_futex/ignore-private:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will disable failure injections
when dealing with private (address space) futexes.
- /sys/kernel/debug/fail_function/inject:
Format: { 'function-name' | '!function-name' | '' }
+
specifies the target function of error injection by name.
If the function name leads '!' prefix, given function is
removed from injection list. If nothing specified ('')
@@ -160,10 +169,11 @@ configuration of fault-injection capabilities.
function for given function. This will be created when
user specifies new injection entry.
-o Boot option
+Boot option
+^^^^^^^^^^^
In order to inject faults while debugfs is not available (early boot time),
-use the boot option:
+use the boot option::
failslab=
fail_page_alloc=
@@ -171,10 +181,11 @@ use the boot option:
fail_futex=
mmc_core.fail_request=<interval>,<probability>,<space>,<times>
-o proc entries
+proc entries
+^^^^^^^^^^^^
-- /proc/<pid>/fail-nth:
-- /proc/self/task/<tid>/fail-nth:
+- /proc/<pid>/fail-nth,
+ /proc/self/task/<tid>/fail-nth:
Write to this file of integer N makes N-th call in the task fail.
Read from this file returns a integer value. A value of '0' indicates
@@ -191,16 +202,16 @@ o proc entries
How to add new fault injection capability
-----------------------------------------
-o #include <linux/fault-inject.h>
+- #include <linux/fault-inject.h>
-o define the fault attributes
+- define the fault attributes
DECLARE_FAULT_ATTR(name);
Please see the definition of struct fault_attr in fault-inject.h
for details.
-o provide a way to configure fault attributes
+- provide a way to configure fault attributes
- boot option
@@ -222,126 +233,126 @@ o provide a way to configure fault attributes
single kernel module, it is better to provide module parameters to
configure the fault attributes.
-o add a hook to insert failures
+- add a hook to insert failures
- Upon should_fail() returning true, client code should inject a failure.
+ Upon should_fail() returning true, client code should inject a failure:
should_fail(attr, size);
Application Examples
--------------------
-o Inject slab allocation failures into module init/exit code
+- Inject slab allocation failures into module init/exit code::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=failslab
-echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ FAILTYPE=failslab
+ echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-faulty_system()
-{
+ faulty_system()
+ {
bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
-}
+ }
-if [ $# -eq 0 ]
-then
+ if [ $# -eq 0 ]
+ then
echo "Usage: $0 modulename [ modulename ... ]"
exit 1
-fi
+ fi
-for m in $*
-do
+ for m in $*
+ do
echo inserting $m...
faulty_system modprobe $m
echo removing $m...
faulty_system modprobe -r $m
-done
+ done
------------------------------------------------------------------------------
-o Inject page allocation failures only for a specific module
+- Inject page allocation failures only for a specific module::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=fail_page_alloc
-module=$1
+ FAILTYPE=fail_page_alloc
+ module=$1
-if [ -z $module ]
-then
+ if [ -z $module ]
+ then
echo "Usage: $0 <modulename>"
exit 1
-fi
+ fi
-modprobe $module
+ modprobe $module
-if [ ! -d /sys/module/$module/sections ]
-then
+ if [ ! -d /sys/module/$module/sections ]
+ then
echo Module $module is not loaded
exit 1
-fi
+ fi
-cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
-cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
+ cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
+ cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
-echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
+ echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
-trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
+ trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
-echo "Injecting errors into the module $module... (interrupt to stop)"
-sleep 1000000
+ echo "Injecting errors into the module $module... (interrupt to stop)"
+ sleep 1000000
------------------------------------------------------------------------------
-o Inject open_ctree error while btrfs mount
+- Inject open_ctree error while btrfs mount::
-#!/bin/bash
+ #!/bin/bash
-rm -f testfile.img
-dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
-DEVICE=$(losetup --show -f testfile.img)
-mkfs.btrfs -f $DEVICE
-mkdir -p tmpmnt
+ rm -f testfile.img
+ dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
+ DEVICE=$(losetup --show -f testfile.img)
+ mkfs.btrfs -f $DEVICE
+ mkdir -p tmpmnt
-FAILTYPE=fail_function
-FAILFUNC=open_ctree
-echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
-echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 100 > /sys/kernel/debug/$FAILTYPE/probability
-echo 0 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
+ FAILTYPE=fail_function
+ FAILFUNC=open_ctree
+ echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
+ echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 100 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 0 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
-mount -t btrfs $DEVICE tmpmnt
-if [ $? -ne 0 ]
-then
+ mount -t btrfs $DEVICE tmpmnt
+ if [ $? -ne 0 ]
+ then
echo "SUCCESS!"
-else
+ else
echo "FAILED!"
umount tmpmnt
-fi
+ fi
-echo > /sys/kernel/debug/$FAILTYPE/inject
+ echo > /sys/kernel/debug/$FAILTYPE/inject
-rmdir tmpmnt
-losetup -d $DEVICE
-rm testfile.img
+ rmdir tmpmnt
+ losetup -d $DEVICE
+ rm testfile.img
Tool to run command with failslab or fail_page_alloc
@@ -354,43 +365,43 @@ see the following examples.
Examples:
Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
-allocation failure.
+allocation failure::
# ./tools/testing/fault-injection/failcmd.sh \
-- make -C tools/testing/selftests/ run_tests
Same as above except to specify 100 times failures at most instead of one time
-at most by default.
+at most by default::
# ./tools/testing/fault-injection/failcmd.sh --times=100 \
-- make -C tools/testing/selftests/ run_tests
Same as above except to inject page allocation failure instead of slab
-allocation failure.
+allocation failure::
# env FAILCMD_TYPE=fail_page_alloc \
./tools/testing/fault-injection/failcmd.sh --times=100 \
- -- make -C tools/testing/selftests/ run_tests
+ -- make -C tools/testing/selftests/ run_tests
Systematic faults using fail-nth
---------------------------------
The following code systematically faults 0-th, 1-st, 2-nd and so on
-capabilities in the socketpair() system call.
+capabilities in the socketpair() system call::
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/socket.h>
-#include <sys/syscall.h>
-#include <fcntl.h>
-#include <unistd.h>
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-#include <errno.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <sys/socket.h>
+ #include <sys/syscall.h>
+ #include <fcntl.h>
+ #include <unistd.h>
+ #include <string.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <errno.h>
-int main()
-{
+ int main()
+ {
int i, err, res, fail_nth, fds[2];
char buf[128];
@@ -413,23 +424,23 @@ int main()
break;
}
return 0;
-}
+ }
-An example output:
+An example output::
-1-th fault Y: res=-1/23
-2-th fault Y: res=-1/23
-3-th fault Y: res=-1/12
-4-th fault Y: res=-1/12
-5-th fault Y: res=-1/23
-6-th fault Y: res=-1/23
-7-th fault Y: res=-1/23
-8-th fault Y: res=-1/12
-9-th fault Y: res=-1/12
-10-th fault Y: res=-1/12
-11-th fault Y: res=-1/12
-12-th fault Y: res=-1/12
-13-th fault Y: res=-1/12
-14-th fault Y: res=-1/12
-15-th fault Y: res=-1/12
-16-th fault N: res=0/12
+ 1-th fault Y: res=-1/23
+ 2-th fault Y: res=-1/23
+ 3-th fault Y: res=-1/12
+ 4-th fault Y: res=-1/12
+ 5-th fault Y: res=-1/23
+ 6-th fault Y: res=-1/23
+ 7-th fault Y: res=-1/23
+ 8-th fault Y: res=-1/12
+ 9-th fault Y: res=-1/12
+ 10-th fault Y: res=-1/12
+ 11-th fault Y: res=-1/12
+ 12-th fault Y: res=-1/12
+ 13-th fault Y: res=-1/12
+ 14-th fault Y: res=-1/12
+ 15-th fault Y: res=-1/12
+ 16-th fault N: res=0/12
diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst
new file mode 100644
index 000000000000..92b5639ed07a
--- /dev/null
+++ b/Documentation/fault-injection/index.rst
@@ -0,0 +1,20 @@
+:orphan:
+
+===============
+fault-injection
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ fault-injection
+ notifier-error-inject
+ nvme-fault-injection
+ provoke-crashes
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/fault-injection/notifier-error-inject.txt b/Documentation/fault-injection/notifier-error-inject.rst
similarity index 83%
rename from Documentation/fault-injection/notifier-error-inject.txt
rename to Documentation/fault-injection/notifier-error-inject.rst
index e861d761de24..1668b6e48d3a 100644
--- a/Documentation/fault-injection/notifier-error-inject.txt
+++ b/Documentation/fault-injection/notifier-error-inject.rst
@@ -14,7 +14,8 @@ modules that can be used to test the following notifiers.
PM notifier error injection module
----------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
Possible PM notifier events to be failed are:
@@ -22,7 +23,7 @@ Possible PM notifier events to be failed are:
* PM_SUSPEND_PREPARE
* PM_RESTORE_PREPARE
-Example: Inject PM suspend error (-12 = -ENOMEM)
+Example: Inject PM suspend error (-12 = -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/pm/
# echo -12 > actions/PM_SUSPEND_PREPARE/error
@@ -32,14 +33,15 @@ Example: Inject PM suspend error (-12 = -ENOMEM)
Memory hotplug notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
Possible memory notifier events to be failed are:
* MEM_GOING_ONLINE
* MEM_GOING_OFFLINE
-Example: Inject memory hotplug offline error (-12 == -ENOMEM)
+Example: Inject memory hotplug offline error (-12 == -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/memory
# echo -12 > actions/MEM_GOING_OFFLINE/error
@@ -49,7 +51,8 @@ Example: Inject memory hotplug offline error (-12 == -ENOMEM)
powerpc pSeries reconfig notifier error injection module
--------------------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
Possible pSeries reconfig notifier events to be failed are:
@@ -61,7 +64,8 @@ Possible pSeries reconfig notifier events to be failed are:
Netdevice notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
Netdevice notifier events which can be failed are:
@@ -75,7 +79,7 @@ Netdevice notifier events which can be failed are:
* NETDEV_PRECHANGEUPPER
* NETDEV_CHANGEUPPER
-Example: Inject netdevice mtu change error (-22 == -EINVAL)
+Example: Inject netdevice mtu change error (-22 == -EINVAL)::
# cd /sys/kernel/debug/notifier-error-inject/netdev
# echo -22 > actions/NETDEV_CHANGEMTU/error
diff --git a/Documentation/fault-injection/nvme-fault-injection.rst b/Documentation/fault-injection/nvme-fault-injection.rst
new file mode 100644
index 000000000000..bbb1bf3e8650
--- /dev/null
+++ b/Documentation/fault-injection/nvme-fault-injection.rst
@@ -0,0 +1,120 @@
+NVMe Fault Injection
+====================
+Linux's fault injection framework provides a systematic way to support
+error injection via debugfs in the /sys/kernel/debug directory. When
+enabled, the default NVME_SC_INVALID_OPCODE with no retry will be
+injected into the nvme_end_request. Users can change the default status
+code and no retry flag via the debugfs. The list of Generic Command
+Status can be found in include/linux/nvme.h
+
+Following examples show how to inject an error into the nvme.
+
+First, enable CONFIG_FAULT_INJECTION_DEBUG_FS kernel config,
+recompile the kernel. After booting up the kernel, do the
+following.
+
+Example 1: Inject default status code with no retry
+---------------------------------------------------
+
+::
+
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ cp a.file /mnt
+
+Expected Result::
+
+ cp: cannot stat ‘/mnt/a.file’: Input/output error
+
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
+ Hardware name: innotek GmbH VirtualBox/VirtualBox,
+ BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x2f/0x50 [nvme_core]
+ nvme_process_cq+0xe7/0x1d0 [nvme]
+ nvme_irq+0x1e/0x40 [nvme]
+ __handle_irq_event_percpu+0x3a/0x190
+ handle_irq_event_percpu+0x30/0x70
+ handle_irq_event+0x36/0x60
+ handle_fasteoi_irq+0x78/0x120
+ handle_irq+0xa7/0x130
+ ? tick_irq_enter+0xa8/0xc0
+ do_IRQ+0x43/0xc0
+ common_interrupt+0xa2/0xa2
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
+ RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
+ R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_kernel+0x4c4/0x4e4
+ ? set_init_arg+0x55/0x55
+ secondary_startup_64+0xa5/0xb0
+ print_req_error: I/O error, dev nvme0n1, sector 9240
+ EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
+ inode #2: comm cp: reading directory lblock 0
+
+Example 2: Inject default status code with retry
+------------------------------------------------
+
+::
+
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
+ echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
+
+ cp a.file /mnt
+
+Expected Result::
+
+ command success without error
+
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
+ Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x30/0x60 [nvme_core]
+ nvme_loop_queue_response+0x84/0x110 [nvme_loop]
+ nvmet_req_complete+0x11/0x40 [nvmet]
+ nvmet_bio_done+0x28/0x40 [nvmet]
+ blk_update_request+0xb0/0x310
+ blk_mq_end_request+0x18/0x60
+ flush_smp_call_function_queue+0x3d/0xf0
+ smp_call_function_single_interrupt+0x2c/0xc0
+ call_function_single_interrupt+0xa2/0xb0
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
+ RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
+ R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_secondary+0x187/0x1e0
+ secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/nvme-fault-injection.txt b/Documentation/fault-injection/nvme-fault-injection.txt
deleted file mode 100644
index 8fbf3bf60b62..000000000000
--- a/Documentation/fault-injection/nvme-fault-injection.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-NVMe Fault Injection
-====================
-Linux's fault injection framework provides a systematic way to support
-error injection via debugfs in the /sys/kernel/debug directory. When
-enabled, the default NVME_SC_INVALID_OPCODE with no retry will be
-injected into the nvme_end_request. Users can change the default status
-code and no retry flag via the debugfs. The list of Generic Command
-Status can be found in include/linux/nvme.h
-
-Following examples show how to inject an error into the nvme.
-
-First, enable CONFIG_FAULT_INJECTION_DEBUG_FS kernel config,
-recompile the kernel. After booting up the kernel, do the
-following.
-
-Example 1: Inject default status code with no retry
----------------------------------------------------
-
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-cp a.file /mnt
-
-Expected Result:
-
-cp: cannot stat ‘/mnt/a.file’: Input/output error
-
-Message from dmesg:
-
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
-Hardware name: innotek GmbH VirtualBox/VirtualBox,
-BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x2f/0x50 [nvme_core]
- nvme_process_cq+0xe7/0x1d0 [nvme]
- nvme_irq+0x1e/0x40 [nvme]
- __handle_irq_event_percpu+0x3a/0x190
- handle_irq_event_percpu+0x30/0x70
- handle_irq_event+0x36/0x60
- handle_fasteoi_irq+0x78/0x120
- handle_irq+0xa7/0x130
- ? tick_irq_enter+0xa8/0xc0
- do_IRQ+0x43/0xc0
- common_interrupt+0xa2/0xa2
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
-RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
-R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_kernel+0x4c4/0x4e4
- ? set_init_arg+0x55/0x55
- secondary_startup_64+0xa5/0xb0
- print_req_error: I/O error, dev nvme0n1, sector 9240
-EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
-inode #2: comm cp: reading directory lblock 0
-
-Example 2: Inject default status code with retry
-------------------------------------------------
-
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
-echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
-
-cp a.file /mnt
-
-Expected Result:
-
-command success without error
-
-Message from dmesg:
-
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
-Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x30/0x60 [nvme_core]
- nvme_loop_queue_response+0x84/0x110 [nvme_loop]
- nvmet_req_complete+0x11/0x40 [nvmet]
- nvmet_bio_done+0x28/0x40 [nvmet]
- blk_update_request+0xb0/0x310
- blk_mq_end_request+0x18/0x60
- flush_smp_call_function_queue+0x3d/0xf0
- smp_call_function_single_interrupt+0x2c/0xc0
- call_function_single_interrupt+0xa2/0xb0
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
-RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
-R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_secondary+0x187/0x1e0
- secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/provoke-crashes.rst b/Documentation/fault-injection/provoke-crashes.rst
new file mode 100644
index 000000000000..9279a3e12278
--- /dev/null
+++ b/Documentation/fault-injection/provoke-crashes.rst
@@ -0,0 +1,48 @@
+===============
+Provoke crashes
+===============
+
+The lkdtm module provides an interface to crash or injure the kernel at
+predefined crashpoints to evaluate the reliability of crash dumps obtained
+using different dumping solutions. The module uses KPROBEs to instrument
+crashing points, but can also crash the kernel directly without KRPOBE
+support.
+
+
+You can provide the way either through module arguments when inserting
+the module, or through a debugfs interface.
+
+Usage::
+
+ insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
+ [cpoint_count={>0}]
+
+recur_count
+ Recursion level for the stack overflow test. Default is 10.
+
+cpoint_name
+ Crash point where the kernel is to be crashed. It can be
+ one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
+ FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
+ IDE_CORE_CP, DIRECT
+
+cpoint_type
+ Indicates the action to be taken on hitting the crash point.
+ It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
+ CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
+ WRITE_AFTER_FREE,
+
+cpoint_count
+ Indicates the number of times the crash point is to be hit
+ to trigger an action. The default is 10.
+
+You can also induce failures by mounting debugfs and writing the type to
+<mountpoint>/provoke-crash/<crashpoint>. E.g.::
+
+ mount -t debugfs debugfs /mnt
+ echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
+
+
+A special file is `DIRECT` which will induce the crash directly without
+KPROBE instrumentation. This mode is the only one available when the module
+is built on a kernel without KPROBEs support.
diff --git a/Documentation/fault-injection/provoke-crashes.txt b/Documentation/fault-injection/provoke-crashes.txt
deleted file mode 100644
index 7a9d3d81525b..000000000000
--- a/Documentation/fault-injection/provoke-crashes.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-The lkdtm module provides an interface to crash or injure the kernel at
-predefined crashpoints to evaluate the reliability of crash dumps obtained
-using different dumping solutions. The module uses KPROBEs to instrument
-crashing points, but can also crash the kernel directly without KRPOBE
-support.
-
-
-You can provide the way either through module arguments when inserting
-the module, or through a debugfs interface.
-
-Usage: insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
- [cpoint_count={>0}]
-
- recur_count : Recursion level for the stack overflow test. Default is 10.
-
- cpoint_name : Crash point where the kernel is to be crashed. It can be
- one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
- FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
- IDE_CORE_CP, DIRECT
-
- cpoint_type : Indicates the action to be taken on hitting the crash point.
- It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
- CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
- WRITE_AFTER_FREE,
-
- cpoint_count : Indicates the number of times the crash point is to be hit
- to trigger an action. The default is 10.
-
-You can also induce failures by mounting debugfs and writing the type to
-<mountpoint>/provoke-crash/<crashpoint>. E.g.,
-
- mount -t debugfs debugfs /mnt
- echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
-
-
-A special file is `DIRECT' which will induce the crash directly without
-KPROBE instrumentation. This mode is the only one available when the module
-is built on a kernel without KPROBEs support.
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 4b7a5ab3cec1..13dd893c9f88 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -298,7 +298,7 @@ enabled, a configurable percentage of memory allocations will be made to
fail; these failures can be restricted to a specific range of code.
Running with fault injection enabled allows the programmer to see how the
code responds when things go badly. See
-Documentation/fault-injection/fault-injection.txt for more information on
+Documentation/fault-injection/fault-injection.rst for more information on
how to use this facility.
Other kinds of errors can be found with the "sparse" static analysis tool.
diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst
index c05b89e616dd..a5e36aa60448 100644
--- a/Documentation/translations/it_IT/process/4.Coding.rst
+++ b/Documentation/translations/it_IT/process/4.Coding.rst
@@ -314,7 +314,7 @@ di allocazione di memoria sarà destinata al fallimento; questi fallimenti
possono essere ridotti ad uno specifico pezzo di codice. Procedere con
l'inserimento dei fallimenti attivo permette al programmatore di verificare
come il codice risponde quando le cose vanno male. Consultate:
-Documentation/fault-injection/fault-injection.txt per avere maggiori
+Documentation/fault-injection/fault-injection.rst per avere maggiori
informazioni su come utilizzare questo strumento.
Altre tipologie di errori possono essere riscontrati con lo strumento di
diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
index 8bb777941394..b82b1dde3122 100644
--- a/Documentation/translations/zh_CN/process/4.Coding.rst
+++ b/Documentation/translations/zh_CN/process/4.Coding.rst
@@ -205,7 +205,7 @@ Linus对这个问题给出了最佳答案:
启用故障注入后，内存分配的可配置百分比将失败；这些失败可以限制在特定的代码
范围内。在启用了故障注入的情况下运行，程序员可以看到当情况恶化时代码如何响
应。有关如何使用此工具的详细信息，请参阅
-Documentation/fault-injection/fault-injection.txt。
+Documentation/fault-injection/fault-injection.rst。
使用“sparse”静态分析工具可以发现其他类型的错误。对于sparse，可以警告程序员
用户空间和内核空间地址之间的混淆、big endian和small endian数量的混合、在需
diff --git a/drivers/misc/lkdtm/core.c b/drivers/misc/lkdtm/core.c
index df9429e3fd3a..c7a507482051 100644
--- a/drivers/misc/lkdtm/core.c
+++ b/drivers/misc/lkdtm/core.c
@@ -15,7 +15,7 @@
*
* Debugfs support added by Simon Kagstrom <[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
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 -
Documentation/cdrom/cdrom-standard.tex | 1026 -----------------------
Documentation/cdrom/cdrom-standard.txt | 1063 ++++++++++++++++++++++++
drivers/cdrom/cdrom.c | 2 +-
4 files changed, 1064 insertions(+), 1048 deletions(-)
delete mode 100644 Documentation/cdrom/Makefile
delete mode 100644 Documentation/cdrom/cdrom-standard.tex
create mode 100644 Documentation/cdrom/cdrom-standard.txt
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.tex
deleted file mode 100644
index f7cd455973f7..000000000000
--- a/Documentation/cdrom/cdrom-standard.tex
+++ /dev/null
@@ -1,1026 +0,0 @@
-\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}}
-
-\evensidemargin=0pt
-\oddsidemargin=0pt
-\topmargin=-\headheight \advance\topmargin by -\headsep
-\textwidth=15.99cm \textheight=24.62cm % normal A4, 1'' margin
-
-\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}}
-
-\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
-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
-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()$
-call varies greatly from one device driver to another. To avoid making
-their drivers totally inconsistent, the writers of \linux\ \cdrom\
-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.
-
-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
-both IDE/ATAPI and SCSI, now use this Uniform interface.
-
-When the \cdrom\ was developed, the interface between the \cdrom\ drive
-and the computer was not specified in the standards. As a result, many
-different \cdrom\ 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
-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\
-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
-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
-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\
-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
-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.
-
-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
-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,
-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.
-
-\newsection{Standardizing through another software level}
-\label{cdrom.c}
-
-At the time this document was conceived, all drivers directly
-implemented the \cdrom\ $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
-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
-done to help ensure that the user is only presented with only one cdrom
-interface, the interface defined in \cdromh.
-
-\cdrom\ drives are specific enough (\ie, 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$.
-These operations are different from the classical block-device file
-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
-}
-$$
-
-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
-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
-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$]
- This structure contains information about the low-level driver for a
- \cdrom\ 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,
- 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
-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
-low-level driver.
-
-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
-through the functions in this structure. It is impossible to know all
-the capabilities of future \cdrom\ 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
-}
-$$
-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.
-
-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
-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,
-since many of them only support one device.) This will be available
-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
-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$
-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
-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$,
-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
-initialized.
-
-The intermediate software layer that \cdromc\ 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
-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
-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
-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
-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
-should only be concerned with proper initialization, such as spinning
-up the disc, etc. % and device-use count
-
-
-\subsection{$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$.
-
-\subsection{$Int\ drive_status(struct\ cdrom_device_info * cdi, int\ slot_nr)$}
-\label{drive status}
-
-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
-}
-$$
-
-\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).
-
-\subsection{$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
-the desired direction of movement:
-\begin{itemize}
-\item[0] Close tray
-\item[1] Open tray
-\end{itemize}
-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.
-
-\subsection{$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
-state:
-\begin{itemize}
-\item[0] Unlock door, manual opening is allowed
-\item[1] Lock door, tray cannot be ejected manually
-\end{itemize}
-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.
-
-\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
-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.
-
-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,
-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
-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)$}
-
-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
-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
-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
-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
-expected as a 13-character string, terminated by a null-character.
-
-\subsection{$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
-listen to commands anymore). Preferably, control is returned to the
-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
-implemented by the routines described above, and hence the function
-$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,
-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
-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.
-
-An unimplemented ioctl should return $-ENOSYS$, but a harmless request
-(\eg, $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.)
-
-\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,
-they are introduced to service some capabilities of certain drives. In
-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
-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
-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
-accidentally tampering with the contents. The capability fags actually
-inform \cdromc\ 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$.
-
-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}.
-
-\subsection{Options}
-
-A final flag register controls the {\em behavior\/} of the \cdrom\
-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
-}
-$$
-
-The initial value of this register is $CDO_AUTO_CLOSE \mathrel|
-CDO_USE_FFLAGS \mathrel| 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
-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.
-
-\newsection{The need to know the purpose of opening the \cdrom\ 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
-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
-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.
-
-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
-disc drive is ready for operation upon opening the device. In the old
-scheme, some \cdrom\ 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;
-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
-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
-desirable.
-
-These two ways of using a \cdrom\ 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
-device in order to get a file handle which is needed for issuing
-$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
-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.
-
-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}
-
-\subsection{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
-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\
-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$
-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)$.
-
-\subsection{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
-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}
-We hope that these option can convince everybody (both driver
-maintainers and user program developers) to adopt the new \cdrom\
-driver scheme and option flag interpretation.
-
-\newsection{Description of routines in \cdromc}
-
-Only a few routines in \cdromc\ 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.
-
-\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$.
-
-\subsection{$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));
-$$
-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.
-
-\subsection{$Void\ unregister_cdrom(struct\ cdrom_device_info * cdi)$}
-
-Unregistering device $cdi$ with minor number $MINOR(cdi\to 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
-success, and non-zero upon failure.
-
-\subsection{$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
-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.
-
-\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)$.
-
-
-\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\
-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
-the remaining ones, that are presumable device-dependent. Generally, a
-negative return value indicates an error.
-
-\subsubsection{Directly implemented $ioctl$s}
-\label{ioctl-direct}
-
-The following `old' \cdrom-$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}
-
-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}
-
-\subsubsection{New $ioctl$s in \cdromc}
-
-The following $ioctl$s have been introduced to allow user programs to
-control the behavior of individual \cdrom\ 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.
-
-\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}
-
-\subsubsection{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.
-
-\newsection{How to update your driver}
-
-\begin{enumerate}
-\item Make a backup of your current driver.
-\item Get hold of the files \cdromc\ and \cdromh, 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
- 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
- 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
- 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
- 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
- change the prototype a little. Remove entries listed in the first
- part in section~\ref{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
- 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
- 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
- way.
-\end{enumerate}
-
-\newsection{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
-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
-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/Documentation/cdrom/cdrom-standard.txt b/Documentation/cdrom/cdrom-standard.txt
new file mode 100644
index 000000000000..dde4f7f7fdbf
--- /dev/null
+++ b/Documentation/cdrom/cdrom-standard.txt
@@ -0,0 +1,1063 @@
+=======================
+A Linux CD-ROM standard
+=======================
+
+:Author: David van Leeuwen <[email protected]>
+:Date: 12 March 1999
+:Updated by: Erik Andersen ([email protected])
+:Updated by: Jens Axboe ([email protected])
+
+
+Introduction
+============
+
+Linux is probably the Unix-like operating system that supports
+the widest variety of hardware devices. The reasons for this are
+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 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 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 CD-ROM drivers.
+
+This document describes an effort to establish Uniform behavior across
+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 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 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
+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 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 `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 *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.
+
+.. [#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 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 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 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 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 **find** anything less than a
+16 speed CD-ROM drive, and 24 speed drives are common.
+
+.. _cdrom_api:
+
+Standardizing through another software level
+============================================
+
+At the time this document was conceived, all drivers directly
+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 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
+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 `cdrom.h`.
+
+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 **CD-ROM device operations**, *<cdrom-device>_dops*.
+These operations are different from the classical block-device file
+operations, *<block-device>_fops*.
+
+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*::
+
+ 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 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:
+
+cdrom_device_ops
+ This structure contains information about the low-level driver for a
+ 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).
+
+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.
+
+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
+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
+of pointers to the functions which are implemented in the low-level
+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 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::
+
+ 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
+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
+which the major and minor number can be extracted. (Most low-level
+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.
+
+The drive-specific, minor-like information that is registered with
+`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->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 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 **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
+initialized.
+
+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
+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
+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 **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.
+
+::
+
+ int open(struct cdrom_device_info *cdi, int purpose)
+
+*Open()* should try to open the device for a specific *purpose*, which
+can be either:
+
+- 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.
+
+::
+
+ 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*.
+
+.. _cdrom_drive_status:
+
+::
+
+ 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 `cdrom.h` the possibilities are listed::
+
+
+ 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 */
+
+::
+
+ 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
+the desired direction of movement:
+
+- 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.
+
+::
+
+ 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
+state:
+
+- 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.
+
+::
+
+ 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.
+
+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 (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
+current disc loaded and the return value should be positive. A negative
+return value indicates an error.
+
+::
+
+ 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.
+
+::
+
+ 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->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.
+
+::
+
+ 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
+expected as a 13-character string, terminated by a null-character.
+
+::
+
+ 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
+listen to commands anymore). Preferably, control is returned to the
+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.
+
+::
+
+ 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
+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,
+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
+old driver scheme. For example, you may look up the function
+*cm206_audio_ioctl()* `cm206.c` that should be updated with
+this documentation.
+
+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 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.)
+
+::
+
+ 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
+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
+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
+the exact frame boundaries, since there are no synchronization headers
+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 `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 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 `cdrom.c` you will encounter many constructions of the type::
+
+ if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
+
+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::
+
+ 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 `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 `setcd`, available from the Debian distribution
+and `sunsite.unc.edu`, allows user level control of these flags.
+
+
+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 CD-ROM drives, is that they can be used for
+two entirely different purposes. One is to mount removable
+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 **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 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 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 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 **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 CD-ROM and its correct type (data), would be
+desirable.
+
+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
+device in order to get a file handle which is needed for issuing
+*ioctl* commands, while data use wants to open for correct and
+reliable data transfer. The only way user programs can indicate what
+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
+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
+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-CD-ROM. Thus, our proposal of the
+implementation for the *open()* call for CD-ROM s is:
+
+- 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
+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\ [#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*
+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)*.
+
+The preferred strategy of *open()*
+----------------------------------
+
+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:
+
+`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 CD-ROM
+driver scheme and option flag interpretation.
+
+Description of routines in `cdrom.c`
+====================================
+
+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 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`.
+
+::
+
+ struct file_operations cdrom_fops
+
+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*.
+
+::
+
+ 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 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::
+
+ struct cdrom_device_info <device>_info = {
+ <device>_dops;
+ ...
+ }
+
+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 CD-ROM interface. This function returns zero upon
+success, and non-zero upon failure.
+
+::
+
+ 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
+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.
+
+::
+
+ 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)*.
+
+
+.. _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
+the remaining ones, that are presumable device-dependent. Generally, a
+negative return value indicates an error.
+
+Directly implemented *ioctl()'s*
+--------------------------------
+
+The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
+calling device-operations in *cdrom_device_ops*, if implemented and
+not masked:
+
+`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.
+
+*Ioctl*s routed through *audio_ioctl()*
+---------------------------------------
+
+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.
+
+`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.
+
+`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.
+
+ 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.
+
+ 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*).
+
+ This *ioctl* can return::
+
+ 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 */
+
+ 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.
+- 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
+ capabilities your driver currently supports. If your driver
+ has a capability that is not listed, please send me a message.
+- 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.
+- 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.
+- Rename your `<device>_ioctl()` function to *audio_ioctl* and
+ change the prototype a little. Remove entries listed in the first
+ part in cdrom_ioctl_, if your code was OK, these are
+ just calls to the routines you adapted in the previous step.
+- 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!
+- Change the prototypes of *<device>_open()* and
+ *<device>_release()*, and remove any strategic code (i. e., tray
+ movement, door locking, etc.).
+- 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.
+
+Thanks
+======
+
+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ß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.
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
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
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]>
---
.../{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 b3746e7b5652..5c5714eddde4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12709,7 +12709,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
On Wed, 12 Jun 2019 14:52:36 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> This is mostly a rebase of the /33 series v3 I sent, on the top of the latest
> linux-next (next-20190612).
>
> Changes from v3:
>
> - dropped cpufreq conversion - documents are too outdated;
> - infiniband patch is not here anymore - as it should be merged via RDMA;
> - s390 patches were already merged;
> - Dropped Geert as Maintainer from fb/framebuffer.rst, as per his request;
> - Did a minor editorial change at popwerpc/cxl.rst per Andrew Donellan
> request;
> - Added acks/reviews;
> - trivial rebase fixups.
So I had to pull docs-next forward to -rc4, but then I was able to apply
this set except for parts 5, 6, 14, 18, and 19. Some progress made, but
this is somewhat painful work...
jon
On Wed, 12 Jun 2019 14:52:50 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> Convert the locking documents to ReST and add them to the
> kernel development book where it belongs.
>
> Most of the stuff here is just to make Sphinx to properly
> parse the text file, as they're already in good shape,
> not requiring massive changes in order to be parsed.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> Acked-by: Federico Vaga <[email protected]>
This patch contains linux-next changes and doesn't apply to docs-next.
Perhaps the best thing to do is to apply it to the locking tree?
Thanks,
jon
Em Fri, 14 Jun 2019 14:36:40 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Wed, 12 Jun 2019 14:52:36 -0300
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > This is mostly a rebase of the /33 series v3 I sent, on the top of the latest
> > linux-next (next-20190612).
> >
> > Changes from v3:
> >
> > - dropped cpufreq conversion - documents are too outdated;
> > - infiniband patch is not here anymore - as it should be merged via RDMA;
> > - s390 patches were already merged;
> > - Dropped Geert as Maintainer from fb/framebuffer.rst, as per his request;
> > - Did a minor editorial change at popwerpc/cxl.rst per Andrew Donellan
> > request;
> > - Added acks/reviews;
> > - trivial rebase fixups.
>
> So I had to pull docs-next forward to -rc4, but then I was able to apply
> this set except for parts 5, 6, 14, 18, and 19.
Patch 5 went via Cgroups tree;
Patch 18 went via power tree;
Patch 6 is obsolete, as the cgroups-v1 CBQ chapter was removed;
So, what's left from this series are patches 14 and 19.
I have a rebased version of them on the top of linux-next
on my working tree. Perhaps we should try to push those two late
during the merge window.
> Some progress made, but
> this is somewhat painful work...
Yeah, a change like that is not easy.
Thanks,
Mauro
Mauro,
> Convert the TCM docs to ReST format and add them to the
> bookset.
Looks good to me.
Acked-by: Martin K. Petersen <[email protected]>
--
Martin K. Petersen Oracle Linux Engineering