* [PATCH v4 00/28] Convert files to ReST - part 1
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Palmer Dabbelt, Albert Ou, Alexei Starovoitov, Daniel Borkmann,
Martin KaFai Lau, Song Liu, Yonghong Song, Greentime Hu,
Vincent Chen, linux-riscv, netdev, bpf
This is mostly a rebase of the /33 series v3 I sent, on the top of the latest
linux-next (next-20190612).
Changes from v3:
- dropped cpufreq conversion - documents are too outdated;
- infiniband patch is not here anymore - as it should be merged via RDMA;
- s390 patches were already merged;
- Dropped Geert as Maintainer from fb/framebuffer.rst, as per his request;
- Did a minor editorial change at popwerpc/cxl.rst per Andrew Donellan
request;
- Added acks/reviews;
- trivial rebase fixups.
Jon,
the first version of this series was sent back on April, 15. So, I
suspect it should be fine to merge those patches via docs tree.
I should be sending soon the next part of this conversion series.
-
This is the first part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, this series is based on today's docs-next
+ linux-next, at tag next-20190607.
I have right now about 85 patches with this undergoing work. That's
because I opted to do ~1 patch per converted directory.
That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts. Those patches should probably be good to be merged
either by subsystem maintainers or via the docs tree.
I opted to mark new files not included yet to the main index.rst (directly or
indirectly ) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement.
Both this series and the next parts are on my devel git tree,
at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v4.2
The final output in html (after all patches I currently have, including
the upcoming series) can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
Mauro Carvalho Chehab (28):
docs: aoe: convert docs to ReST and rename to *.rst
docs: arm64: convert docs to ReST and rename to .rst
docs: cdrom-standard.tex: convert from LaTeX to ReST
docs: cdrom: convert docs to ReST and rename to *.rst
docs: cgroup-v1: convert docs to ReST and rename to *.rst
docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
docs: convert docs to ReST and rename to *.rst
docs: fault-injection: convert docs to ReST and rename to *.rst
docs: fb: convert docs to ReST and rename to *.rst
docs: fpga: convert docs to ReST and rename to *.rst
docs: ide: convert docs to ReST and rename to *.rst
docs: kbuild: convert docs to ReST and rename to *.rst
docs: kdump: convert docs to ReST and rename to *.rst
docs: locking: convert docs to ReST and rename to *.rst
docs: mic: convert docs to ReST and rename to *.rst
docs: netlabel: convert docs to ReST and rename to *.rst
docs: pcmcia: convert docs to ReST and rename to *.rst
docs: convert docs to ReST and rename to *.rst
docs: powerpc: convert docs to ReST and rename to *.rst
docs: pps.txt: convert to ReST and rename to pps.rst
docs: ptp.txt: convert to ReST and move to driver-api
docs: riscv: convert docs to ReST and rename to *.rst
docs: target: convert docs to ReST and rename to *.rst
docs: timers: convert docs to ReST and rename to *.rst
docs: watchdog: convert docs to ReST and rename to *.rst
docs: xilinx: convert eemi.txt to eemi.rst
docs: scheduler: convert docs to ReST and rename to *.rst
docs: EDID/HOWTO.txt: convert it and rename to howto.rst
.../ABI/testing/sysfs-class-powercap | 2 +-
Documentation/ABI/testing/sysfs-kernel-uids | 2 +-
Documentation/EDID/{HOWTO.txt => howto.rst} | 31 +-
Documentation/PCI/pci-error-recovery.rst | 23 +-
Documentation/admin-guide/README.rst | 2 +-
Documentation/admin-guide/bug-hunting.rst | 2 +-
Documentation/admin-guide/hw-vuln/l1tf.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 24 +-
.../admin-guide/mm/numa_memory_policy.rst | 2 +-
Documentation/aoe/{aoe.txt => aoe.rst} | 63 +-
Documentation/aoe/examples.rst | 23 +
Documentation/aoe/index.rst | 19 +
Documentation/aoe/{todo.txt => todo.rst} | 3 +
Documentation/aoe/udev.txt | 2 +-
...object_usage.txt => acpi_object_usage.rst} | 288 +++--
.../arm64/{arm-acpi.txt => arm-acpi.rst} | 155 +--
.../arm64/{booting.txt => booting.rst} | 91 +-
...egisters.txt => cpu-feature-registers.rst} | 204 ++--
.../arm64/{elf_hwcaps.txt => elf_hwcaps.rst} | 56 +-
.../{hugetlbpage.txt => hugetlbpage.rst} | 7 +-
Documentation/arm64/index.rst | 28 +
...structions.txt => legacy_instructions.rst} | 43 +-
Documentation/arm64/memory.rst | 98 ++
Documentation/arm64/memory.txt | 97 --
...ication.txt => pointer-authentication.rst} | 2 +
...{silicon-errata.txt => silicon-errata.rst} | 65 +-
Documentation/arm64/{sve.txt => sve.rst} | 12 +-
...agged-pointers.txt => tagged-pointers.rst} | 6 +-
Documentation/block/bfq-iosched.txt | 2 +-
Documentation/cdrom/Makefile | 21 -
Documentation/cdrom/cdrom-standard.rst | 1063 +++++++++++++++++
Documentation/cdrom/cdrom-standard.tex | 1026 ----------------
Documentation/cdrom/{ide-cd => ide-cd.rst} | 196 +--
Documentation/cdrom/index.rst | 19 +
...{packet-writing.txt => packet-writing.rst} | 27 +-
...io-controller.txt => blkio-controller.rst} | 103 +-
.../cgroup-v1/{cgroups.txt => cgroups.rst} | 184 +--
.../cgroup-v1/{cpuacct.txt => cpuacct.rst} | 15 +-
.../cgroup-v1/{cpusets.txt => cpusets.rst} | 205 ++--
.../cgroup-v1/{devices.txt => devices.rst} | 40 +-
...er-subsystem.txt => freezer-subsystem.rst} | 14 +-
.../cgroup-v1/{hugetlb.txt => hugetlb.rst} | 39 +-
Documentation/cgroup-v1/index.rst | 30 +
.../{memcg_test.txt => memcg_test.rst} | 263 ++--
.../cgroup-v1/{memory.txt => memory.rst} | 449 ++++---
.../cgroup-v1/{net_cls.txt => net_cls.rst} | 37 +-
.../cgroup-v1/{net_prio.txt => net_prio.rst} | 24 +-
.../cgroup-v1/{pids.txt => pids.rst} | 78 +-
.../cgroup-v1/{rdma.txt => rdma.rst} | 66 +-
Documentation/cpu-freq/core.txt | 2 +-
...{cache-policies.txt => cache-policies.rst} | 24 +-
.../device-mapper/{cache.txt => cache.rst} | 206 ++--
.../device-mapper/{delay.txt => delay.rst} | 29 +-
.../{dm-crypt.txt => dm-crypt.rst} | 57 +-
.../{dm-flakey.txt => dm-flakey.rst} | 45 +-
.../{dm-init.txt => dm-init.rst} | 75 +-
.../{dm-integrity.txt => dm-integrity.rst} | 62 +-
.../device-mapper/{dm-io.txt => dm-io.rst} | 14 +-
.../device-mapper/{dm-log.txt => dm-log.rst} | 5 +-
...m-queue-length.txt => dm-queue-length.rst} | 25 +-
.../{dm-raid.txt => dm-raid.rst} | 225 ++--
...m-service-time.txt => dm-service-time.rst} | 68 +-
Documentation/device-mapper/dm-uevent.rst | 110 ++
Documentation/device-mapper/dm-uevent.txt | 97 --
.../{dm-zoned.txt => dm-zoned.rst} | 10 +-
.../device-mapper/{era.txt => era.rst} | 36 +-
Documentation/device-mapper/index.rst | 44 +
.../device-mapper/{kcopyd.txt => kcopyd.rst} | 10 +-
Documentation/device-mapper/linear.rst | 63 +
Documentation/device-mapper/linear.txt | 61 -
.../{log-writes.txt => log-writes.rst} | 91 +-
...ersistent-data.txt => persistent-data.rst} | 4 +
.../{snapshot.txt => snapshot.rst} | 116 +-
.../{statistics.txt => statistics.rst} | 62 +-
Documentation/device-mapper/striped.rst | 61 +
Documentation/device-mapper/striped.txt | 57 -
.../device-mapper/{switch.txt => switch.rst} | 47 +-
...provisioning.txt => thin-provisioning.rst} | 68 +-
.../{unstriped.txt => unstriped.rst} | 111 +-
.../device-mapper/{verity.txt => verity.rst} | 20 +-
.../{writecache.txt => writecache.rst} | 13 +-
.../device-mapper/{zero.txt => zero.rst} | 14 +-
Documentation/driver-api/pm/devices.rst | 6 +-
.../{pps/pps.txt => driver-api/pps.rst} | 67 +-
.../{ptp/ptp.txt => driver-api/ptp.rst} | 26 +-
.../driver-api/usb/power-management.rst | 2 +-
...ault-injection.txt => fault-injection.rst} | 265 ++--
Documentation/fault-injection/index.rst | 20 +
...r-inject.txt => notifier-error-inject.rst} | 18 +-
.../fault-injection/nvme-fault-injection.rst | 120 ++
.../fault-injection/nvme-fault-injection.txt | 116 --
.../fault-injection/provoke-crashes.rst | 48 +
.../fault-injection/provoke-crashes.txt | 38 -
Documentation/fb/{api.txt => api.rst} | 29 +-
Documentation/fb/{arkfb.txt => arkfb.rst} | 8 +-
.../fb/{aty128fb.txt => aty128fb.rst} | 35 +-
.../fb/{cirrusfb.txt => cirrusfb.rst} | 47 +-
.../fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} | 57 +-
.../fb/{deferred_io.txt => deferred_io.rst} | 28 +-
Documentation/fb/{efifb.txt => efifb.rst} | 18 +-
.../fb/{ep93xx-fb.txt => ep93xx-fb.rst} | 27 +-
Documentation/fb/{fbcon.txt => fbcon.rst} | 177 +--
.../fb/{framebuffer.txt => framebuffer.rst} | 80 +-
Documentation/fb/{gxfb.txt => gxfb.rst} | 24 +-
Documentation/fb/index.rst | 50 +
.../fb/{intel810.txt => intel810.rst} | 79 +-
Documentation/fb/{intelfb.txt => intelfb.rst} | 62 +-
.../fb/{internals.txt => internals.rst} | 24 +-
Documentation/fb/{lxfb.txt => lxfb.rst} | 25 +-
Documentation/fb/matroxfb.rst | 443 +++++++
Documentation/fb/matroxfb.txt | 413 -------
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/pvr2fb.rst | 66 +
Documentation/fb/pvr2fb.txt | 65 -
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
Documentation/fb/sh7760fb.rst | 130 ++
Documentation/fb/sh7760fb.txt | 131 --
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/sstfb.rst | 207 ++++
Documentation/fb/sstfb.txt | 174 ---
Documentation/fb/{tgafb.txt => tgafb.rst} | 30 +-
.../fb/{tridentfb.txt => tridentfb.rst} | 36 +-
Documentation/fb/{udlfb.txt => udlfb.rst} | 55 +-
Documentation/fb/{uvesafb.txt => uvesafb.rst} | 128 +-
Documentation/fb/{vesafb.txt => vesafb.rst} | 121 +-
Documentation/fb/viafb.rst | 297 +++++
Documentation/fb/viafb.txt | 252 ----
.../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +-
Documentation/filesystems/tmpfs.txt | 2 +-
.../filesystems/ubifs-authentication.md | 4 +-
Documentation/fpga/{dfl.txt => dfl.rst} | 58 +-
Documentation/fpga/index.rst | 17 +
Documentation/ide/changelogs.rst | 17 +
.../ide/{ide-tape.txt => ide-tape.rst} | 23 +-
Documentation/ide/{ide.txt => ide.rst} | 147 +--
Documentation/ide/index.rst | 21 +
...arm-plug-howto.txt => warm-plug-howto.rst} | 10 +-
...eaders_install.txt => headers_install.rst} | 5 +-
Documentation/kbuild/index.rst | 27 +
Documentation/kbuild/issues.rst | 11 +
.../kbuild/{kbuild.txt => kbuild.rst} | 119 +-
...nfig-language.txt => kconfig-language.rst} | 232 ++--
...anguage.txt => kconfig-macro-language.rst} | 37 +-
.../kbuild/{kconfig.txt => kconfig.rst} | 136 ++-
.../kbuild/{makefiles.txt => makefiles.rst} | 530 +++++---
.../kbuild/{modules.txt => modules.rst} | 168 +--
Documentation/kdump/index.rst | 21 +
Documentation/kdump/{kdump.txt => kdump.rst} | 131 +-
.../kdump/{vmcoreinfo.txt => vmcoreinfo.rst} | 59 +-
Documentation/kernel-hacking/hacking.rst | 4 +-
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/kernel-per-CPU-kthreads.txt | 2 +-
Documentation/locking/index.rst | 24 +
...{lockdep-design.txt => lockdep-design.rst} | 51 +-
Documentation/locking/lockstat.rst | 204 ++++
Documentation/locking/lockstat.txt | 183 ---
.../{locktorture.txt => locktorture.rst} | 105 +-
.../{mutex-design.txt => mutex-design.rst} | 26 +-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++-
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +-
.../locking/{spinlocks.txt => spinlocks.rst} | 32 +-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +-
Documentation/mic/index.rst | 18 +
.../{mic_overview.txt => mic_overview.rst} | 6 +-
.../{scif_overview.txt => scif_overview.rst} | 58 +-
.../{cipso_ipv4.txt => cipso_ipv4.rst} | 19 +-
Documentation/netlabel/draft_ietf.rst | 5 +
Documentation/netlabel/index.rst | 21 +
.../{introduction.txt => introduction.rst} | 16 +-
.../{lsm_interface.txt => lsm_interface.rst} | 16 +-
Documentation/networking/timestamping.txt | 2 +-
.../{devicetable.txt => devicetable.rst} | 4 +
...{driver-changes.txt => driver-changes.rst} | 35 +-
.../pcmcia/{driver.txt => driver.rst} | 18 +-
Documentation/pcmcia/index.rst | 20 +
.../pcmcia/{locking.txt => locking.rst} | 39 +-
Documentation/pi-futex.txt | 2 +-
.../power/{apm-acpi.txt => apm-acpi.rst} | 10 +-
...m-debugging.txt => basic-pm-debugging.rst} | 79 +-
...harger-manager.txt => charger-manager.rst} | 101 +-
...rivers-testing.txt => drivers-testing.rst} | 15 +-
.../{energy-model.txt => energy-model.rst} | 101 +-
...ing-of-tasks.txt => freezing-of-tasks.rst} | 91 +-
Documentation/power/index.rst | 46 +
.../power/{interface.txt => interface.rst} | 24 +-
Documentation/power/{opp.txt => opp.rst} | 175 +--
Documentation/power/{pci.txt => pci.rst} | 87 +-
...qos_interface.txt => pm_qos_interface.rst} | 127 +-
Documentation/power/power_supply_class.rst | 282 +++++
Documentation/power/power_supply_class.txt | 231 ----
Documentation/power/powercap/powercap.rst | 257 ++++
Documentation/power/powercap/powercap.txt | 236 ----
.../regulator/{consumer.txt => consumer.rst} | 141 ++-
.../regulator/{design.txt => design.rst} | 9 +-
.../regulator/{machine.txt => machine.rst} | 47 +-
.../regulator/{overview.txt => overview.rst} | 57 +-
Documentation/power/regulator/regulator.rst | 32 +
Documentation/power/regulator/regulator.txt | 30 -
.../power/{runtime_pm.txt => runtime_pm.rst} | 234 ++--
Documentation/power/{s2ram.txt => s2ram.rst} | 20 +-
...hotplug.txt => suspend-and-cpuhotplug.rst} | 42 +-
...errupts.txt => suspend-and-interrupts.rst} | 2 +
...ap-files.txt => swsusp-and-swap-files.rst} | 17 +-
...{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} | 120 +-
Documentation/power/swsusp.rst | 501 ++++++++
Documentation/power/swsusp.txt | 446 -------
.../power/{tricks.txt => tricks.rst} | 6 +-
...serland-swsusp.txt => userland-swsusp.rst} | 55 +-
Documentation/power/{video.txt => video.rst} | 156 ++-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 119 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
Documentation/powerpc/ptrace.rst | 156 +++
Documentation/powerpc/ptrace.txt | 151 ---
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/process/4.Coding.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
Documentation/process/submit-checklist.rst | 2 +-
Documentation/process/submitting-drivers.rst | 2 +-
Documentation/riscv/index.rst | 17 +
Documentation/riscv/{pmu.txt => pmu.rst} | 98 +-
.../{completion.txt => completion.rst} | 38 +-
Documentation/scheduler/index.rst | 29 +
.../{sched-arch.txt => sched-arch.rst} | 18 +-
.../{sched-bwc.txt => sched-bwc.rst} | 30 +-
...{sched-deadline.txt => sched-deadline.rst} | 297 ++---
...ed-design-CFS.txt => sched-design-CFS.rst} | 17 +-
.../{sched-domains.txt => sched-domains.rst} | 8 +-
.../{sched-energy.txt => sched-energy.rst} | 53 +-
...-nice-design.txt => sched-nice-design.rst} | 6 +-
...{sched-rt-group.txt => sched-rt-group.rst} | 30 +-
.../{sched-stats.txt => sched-stats.rst} | 35 +-
Documentation/scheduler/text_files.rst | 5 +
Documentation/target/index.rst | 19 +
Documentation/target/scripts.rst | 11 +
Documentation/target/tcm_mod_builder.rst | 149 +++
Documentation/target/tcm_mod_builder.txt | 145 ---
.../{tcmu-design.txt => tcmu-design.rst} | 268 +++--
.../timers/{highres.txt => highres.rst} | 13 +-
Documentation/timers/{hpet.txt => hpet.rst} | 4 +-
.../timers/{hrtimers.txt => hrtimers.rst} | 6 +-
Documentation/timers/index.rst | 22 +
Documentation/timers/{NO_HZ.txt => no_hz.rst} | 40 +-
.../{timekeeping.txt => timekeeping.rst} | 3 +-
.../{timers-howto.txt => timers-howto.rst} | 15 +-
Documentation/trace/coresight-cpu-debug.txt | 2 +-
.../it_IT/kernel-hacking/hacking.rst | 4 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../it_IT/process/coding-style.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../translations/zh_CN/arm64/booting.txt | 4 +-
.../zh_CN/arm64/legacy_instructions.txt | 4 +-
.../translations/zh_CN/arm64/memory.txt | 4 +-
.../zh_CN/arm64/silicon-errata.txt | 4 +-
.../zh_CN/arm64/tagged-pointers.txt | 4 +-
.../translations/zh_CN/oops-tracing.txt | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
.../zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
.../zh_CN/process/submitting-drivers.rst | 2 +-
Documentation/virtual/kvm/api.txt | 2 +-
Documentation/vm/numa.rst | 6 +-
Documentation/vm/page_migration.rst | 2 +-
Documentation/vm/unevictable-lru.rst | 2 +-
....txt => convert_drivers_to_kernel_api.rst} | 109 +-
.../watchdog/{hpwdt.txt => hpwdt.rst} | 27 +-
Documentation/watchdog/index.rst | 25 +
.../watchdog/{mlx-wdt.txt => mlx-wdt.rst} | 24 +-
.../{pcwd-watchdog.txt => pcwd-watchdog.rst} | 13 +-
.../{watchdog-api.txt => watchdog-api.rst} | 76 +-
...kernel-api.txt => watchdog-kernel-api.rst} | 91 +-
.../watchdog/watchdog-parameters.rst | 736 ++++++++++++
.../watchdog/watchdog-parameters.txt | 410 -------
.../{watchdog-pm.txt => watchdog-pm.rst} | 3 +
Documentation/watchdog/{wdt.txt => wdt.rst} | 31 +-
.../x86/x86_64/fake-numa-for-cpusets.rst | 4 +-
Documentation/xilinx/{eemi.txt => eemi.rst} | 8 +-
Documentation/xilinx/index.rst | 17 +
Kconfig | 2 +-
MAINTAINERS | 34 +-
arch/arc/plat-eznps/Kconfig | 2 +-
arch/arm/Kconfig | 2 +-
arch/arm64/Kconfig | 2 +-
arch/arm64/include/asm/efi.h | 2 +-
arch/arm64/include/asm/image.h | 2 +-
arch/arm64/include/uapi/asm/sigcontext.h | 2 +-
arch/arm64/kernel/kexec_image.c | 2 +-
arch/c6x/Kconfig | 2 +-
arch/m68k/q40/README | 2 +-
arch/microblaze/Kconfig.debug | 2 +-
arch/microblaze/Kconfig.platform | 2 +-
arch/nds32/Kconfig | 2 +-
arch/openrisc/Kconfig | 2 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
arch/powerpc/sysdev/Kconfig | 2 +-
arch/riscv/Kconfig | 2 +-
arch/sh/Kconfig | 2 +-
arch/x86/Kconfig | 6 +-
block/Kconfig | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/block/Kconfig | 2 +-
drivers/cdrom/cdrom.c | 2 +-
drivers/firmware/Kconfig | 2 +-
drivers/gpu/drm/Kconfig | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 2 +-
drivers/ide/Kconfig | 20 +-
drivers/ide/ide-cd.c | 2 +-
drivers/md/Kconfig | 2 +-
drivers/md/dm-init.c | 2 +-
drivers/md/dm-raid.c | 2 +-
drivers/media/usb/dvb-usb-v2/anysee.c | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
drivers/mtd/devices/Kconfig | 2 +-
drivers/net/ethernet/smsc/Kconfig | 6 +-
drivers/net/wireless/intel/iwlegacy/Kconfig | 4 +-
drivers/net/wireless/intel/iwlwifi/Kconfig | 2 +-
drivers/opp/Kconfig | 2 +-
drivers/parport/Kconfig | 2 +-
drivers/pcmcia/ds.c | 2 +-
drivers/power/supply/power_supply_core.c | 2 +-
drivers/regulator/core.c | 2 +-
drivers/scsi/Kconfig | 4 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/staging/sm750fb/Kconfig | 2 +-
drivers/tty/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
drivers/usb/misc/Kconfig | 4 +-
drivers/video/fbdev/Kconfig | 38 +-
drivers/video/fbdev/matrox/matroxfb_base.c | 2 +-
drivers/video/fbdev/pxafb.c | 2 +-
drivers/video/fbdev/sh7760fb.c | 2 +-
drivers/watchdog/Kconfig | 6 +-
drivers/watchdog/smsc37b787_wdt.c | 2 +-
include/linux/cgroup-defs.h | 2 +-
include/linux/fault-inject.h | 2 +-
include/linux/interrupt.h | 2 +-
include/linux/iopoll.h | 4 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/pci.h | 2 +-
include/linux/pm.h | 2 +-
include/linux/regmap.h | 4 +-
include/linux/rwsem.h | 2 +-
include/pcmcia/ds.h | 2 +-
include/pcmcia/ss.h | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
include/uapi/linux/bpf.h | 2 +-
init/Kconfig | 8 +-
kernel/cgroup/cpuset.c | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
kernel/power/Kconfig | 6 +-
kernel/sched/deadline.c | 2 +-
lib/Kconfig.debug | 6 +-
net/bridge/netfilter/Kconfig | 2 +-
net/ipv4/netfilter/Kconfig | 2 +-
net/ipv6/netfilter/Kconfig | 2 +-
net/netfilter/Kconfig | 16 +-
net/tipc/Kconfig | 2 +-
net/wireless/Kconfig | 2 +-
scripts/Kbuild.include | 4 +-
scripts/Makefile.host | 2 +-
scripts/checkpatch.pl | 8 +-
scripts/documentation-file-ref-check | 2 +-
scripts/kconfig/symbol.c | 2 +-
.../tests/err_recursive_dep/expected_stderr | 14 +-
security/device_cgroup.c | 2 +-
sound/oss/dmasound/Kconfig | 6 +-
sound/soc/sof/ops.h | 2 +-
tools/include/uapi/linux/bpf.h | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
392 files changed, 12880 insertions(+), 9641 deletions(-)
rename Documentation/EDID/{HOWTO.txt => howto.rst} (83%)
rename Documentation/aoe/{aoe.txt => aoe.rst} (79%)
create mode 100644 Documentation/aoe/examples.rst
create mode 100644 Documentation/aoe/index.rst
rename Documentation/aoe/{todo.txt => todo.rst} (98%)
rename Documentation/arm64/{acpi_object_usage.txt => acpi_object_usage.rst} (84%)
rename Documentation/arm64/{arm-acpi.txt => arm-acpi.rst} (86%)
rename Documentation/arm64/{booting.txt => booting.rst} (86%)
rename Documentation/arm64/{cpu-feature-registers.txt => cpu-feature-registers.rst} (65%)
rename Documentation/arm64/{elf_hwcaps.txt => elf_hwcaps.rst} (92%)
rename Documentation/arm64/{hugetlbpage.txt => hugetlbpage.rst} (86%)
create mode 100644 Documentation/arm64/index.rst
rename Documentation/arm64/{legacy_instructions.txt => legacy_instructions.rst} (73%)
create mode 100644 Documentation/arm64/memory.rst
delete mode 100644 Documentation/arm64/memory.txt
rename Documentation/arm64/{pointer-authentication.txt => pointer-authentication.rst} (99%)
rename Documentation/arm64/{silicon-errata.txt => silicon-errata.rst} (55%)
rename Documentation/arm64/{sve.txt => sve.rst} (98%)
rename Documentation/arm64/{tagged-pointers.txt => tagged-pointers.rst} (94%)
delete mode 100644 Documentation/cdrom/Makefile
create mode 100644 Documentation/cdrom/cdrom-standard.rst
delete mode 100644 Documentation/cdrom/cdrom-standard.tex
rename Documentation/cdrom/{ide-cd => ide-cd.rst} (82%)
create mode 100644 Documentation/cdrom/index.rst
rename Documentation/cdrom/{packet-writing.txt => packet-writing.rst} (91%)
rename Documentation/cgroup-v1/{blkio-controller.txt => blkio-controller.rst} (89%)
rename Documentation/cgroup-v1/{cgroups.txt => cgroups.rst} (88%)
rename Documentation/cgroup-v1/{cpuacct.txt => cpuacct.rst} (90%)
rename Documentation/cgroup-v1/{cpusets.txt => cpusets.rst} (90%)
rename Documentation/cgroup-v1/{devices.txt => devices.rst} (88%)
rename Documentation/cgroup-v1/{freezer-subsystem.txt => freezer-subsystem.rst} (95%)
rename Documentation/cgroup-v1/{hugetlb.txt => hugetlb.rst} (70%)
create mode 100644 Documentation/cgroup-v1/index.rst
rename Documentation/cgroup-v1/{memcg_test.txt => memcg_test.rst} (62%)
rename Documentation/cgroup-v1/{memory.txt => memory.rst} (71%)
rename Documentation/cgroup-v1/{net_cls.txt => net_cls.rst} (50%)
rename Documentation/cgroup-v1/{net_prio.txt => net_prio.rst} (71%)
rename Documentation/cgroup-v1/{pids.txt => pids.rst} (62%)
rename Documentation/cgroup-v1/{rdma.txt => rdma.rst} (79%)
rename Documentation/device-mapper/{cache-policies.txt => cache-policies.rst} (94%)
rename Documentation/device-mapper/{cache.txt => cache.rst} (61%)
rename Documentation/device-mapper/{delay.txt => delay.rst} (53%)
rename Documentation/device-mapper/{dm-crypt.txt => dm-crypt.rst} (87%)
rename Documentation/device-mapper/{dm-flakey.txt => dm-flakey.rst} (60%)
rename Documentation/device-mapper/{dm-init.txt => dm-init.rst} (69%)
rename Documentation/device-mapper/{dm-integrity.txt => dm-integrity.rst} (90%)
rename Documentation/device-mapper/{dm-io.txt => dm-io.rst} (92%)
rename Documentation/device-mapper/{dm-log.txt => dm-log.rst} (90%)
rename Documentation/device-mapper/{dm-queue-length.txt => dm-queue-length.rst} (76%)
rename Documentation/device-mapper/{dm-raid.txt => dm-raid.rst} (71%)
rename Documentation/device-mapper/{dm-service-time.txt => dm-service-time.rst} (60%)
create mode 100644 Documentation/device-mapper/dm-uevent.rst
delete mode 100644 Documentation/device-mapper/dm-uevent.txt
rename Documentation/device-mapper/{dm-zoned.txt => dm-zoned.rst} (97%)
rename Documentation/device-mapper/{era.txt => era.rst} (70%)
create mode 100644 Documentation/device-mapper/index.rst
rename Documentation/device-mapper/{kcopyd.txt => kcopyd.rst} (93%)
create mode 100644 Documentation/device-mapper/linear.rst
delete mode 100644 Documentation/device-mapper/linear.txt
rename Documentation/device-mapper/{log-writes.txt => log-writes.rst} (61%)
rename Documentation/device-mapper/{persistent-data.txt => persistent-data.rst} (98%)
rename Documentation/device-mapper/{snapshot.txt => snapshot.rst} (62%)
rename Documentation/device-mapper/{statistics.txt => statistics.rst} (87%)
create mode 100644 Documentation/device-mapper/striped.rst
delete mode 100644 Documentation/device-mapper/striped.txt
rename Documentation/device-mapper/{switch.txt => switch.rst} (84%)
rename Documentation/device-mapper/{thin-provisioning.txt => thin-provisioning.rst} (92%)
rename Documentation/device-mapper/{unstriped.txt => unstriped.rst} (60%)
rename Documentation/device-mapper/{verity.txt => verity.rst} (98%)
rename Documentation/device-mapper/{writecache.txt => writecache.rst} (96%)
rename Documentation/device-mapper/{zero.txt => zero.rst} (83%)
rename Documentation/{pps/pps.txt => driver-api/pps.rst} (89%)
rename Documentation/{ptp/ptp.txt => driver-api/ptp.rst} (88%)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
create mode 100644 Documentation/fault-injection/nvme-fault-injection.rst
delete mode 100644 Documentation/fault-injection/nvme-fault-injection.txt
create mode 100644 Documentation/fault-injection/provoke-crashes.rst
delete mode 100644 Documentation/fault-injection/provoke-crashes.txt
rename Documentation/fb/{api.txt => api.rst} (97%)
rename Documentation/fb/{arkfb.txt => arkfb.rst} (92%)
rename Documentation/fb/{aty128fb.txt => aty128fb.rst} (61%)
rename Documentation/fb/{cirrusfb.txt => cirrusfb.rst} (75%)
rename Documentation/fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} (50%)
rename Documentation/fb/{deferred_io.txt => deferred_io.rst} (86%)
rename Documentation/fb/{efifb.txt => efifb.rst} (75%)
rename Documentation/fb/{ep93xx-fb.txt => ep93xx-fb.rst} (85%)
rename Documentation/fb/{fbcon.txt => fbcon.rst} (69%)
rename Documentation/fb/{framebuffer.txt => framebuffer.rst} (92%)
rename Documentation/fb/{gxfb.txt => gxfb.rst} (60%)
create mode 100644 Documentation/fb/index.rst
rename Documentation/fb/{intel810.txt => intel810.rst} (83%)
rename Documentation/fb/{intelfb.txt => intelfb.rst} (73%)
rename Documentation/fb/{internals.txt => internals.rst} (82%)
rename Documentation/fb/{lxfb.txt => lxfb.rst} (60%)
create mode 100644 Documentation/fb/matroxfb.rst
delete mode 100644 Documentation/fb/matroxfb.txt
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
create mode 100644 Documentation/fb/pvr2fb.rst
delete mode 100644 Documentation/fb/pvr2fb.txt
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
create mode 100644 Documentation/fb/sh7760fb.rst
delete mode 100644 Documentation/fb/sh7760fb.txt
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
create mode 100644 Documentation/fb/sstfb.rst
delete mode 100644 Documentation/fb/sstfb.txt
rename Documentation/fb/{tgafb.txt => tgafb.rst} (71%)
rename Documentation/fb/{tridentfb.txt => tridentfb.rst} (70%)
rename Documentation/fb/{udlfb.txt => udlfb.rst} (77%)
rename Documentation/fb/{uvesafb.txt => uvesafb.rst} (52%)
rename Documentation/fb/{vesafb.txt => vesafb.rst} (57%)
create mode 100644 Documentation/fb/viafb.rst
delete mode 100644 Documentation/fb/viafb.txt
rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%)
rename Documentation/fpga/{dfl.txt => dfl.rst} (89%)
create mode 100644 Documentation/fpga/index.rst
create mode 100644 Documentation/ide/changelogs.rst
rename Documentation/ide/{ide-tape.txt => ide-tape.rst} (83%)
rename Documentation/ide/{ide.txt => ide.rst} (72%)
create mode 100644 Documentation/ide/index.rst
rename Documentation/ide/{warm-plug-howto.txt => warm-plug-howto.rst} (61%)
rename Documentation/kbuild/{headers_install.txt => headers_install.rst} (96%)
create mode 100644 Documentation/kbuild/index.rst
create mode 100644 Documentation/kbuild/issues.rst
rename Documentation/kbuild/{kbuild.txt => kbuild.rst} (72%)
rename Documentation/kbuild/{kconfig-language.txt => kconfig-language.rst} (85%)
rename Documentation/kbuild/{kconfig-macro-language.txt => kconfig-macro-language.rst} (94%)
rename Documentation/kbuild/{kconfig.txt => kconfig.rst} (80%)
rename Documentation/kbuild/{makefiles.txt => makefiles.rst} (83%)
rename Documentation/kbuild/{modules.txt => modules.rst} (84%)
create mode 100644 Documentation/kdump/index.rst
rename Documentation/kdump/{kdump.txt => kdump.rst} (91%)
rename Documentation/kdump/{vmcoreinfo.txt => vmcoreinfo.rst} (95%)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
create mode 100644 Documentation/locking/lockstat.rst
delete mode 100644 Documentation/locking/lockstat.txt
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
create mode 100644 Documentation/mic/index.rst
rename Documentation/mic/{mic_overview.txt => mic_overview.rst} (96%)
rename Documentation/mic/{scif_overview.txt => scif_overview.rst} (76%)
rename Documentation/netlabel/{cipso_ipv4.txt => cipso_ipv4.rst} (87%)
create mode 100644 Documentation/netlabel/draft_ietf.rst
create mode 100644 Documentation/netlabel/index.rst
rename Documentation/netlabel/{introduction.txt => introduction.rst} (91%)
rename Documentation/netlabel/{lsm_interface.txt => lsm_interface.rst} (88%)
rename Documentation/pcmcia/{devicetable.txt => devicetable.rst} (97%)
rename Documentation/pcmcia/{driver-changes.txt => driver-changes.rst} (90%)
rename Documentation/pcmcia/{driver.txt => driver.rst} (66%)
create mode 100644 Documentation/pcmcia/index.rst
rename Documentation/pcmcia/{locking.txt => locking.rst} (81%)
rename Documentation/power/{apm-acpi.txt => apm-acpi.rst} (87%)
rename Documentation/power/{basic-pm-debugging.txt => basic-pm-debugging.rst} (87%)
rename Documentation/power/{charger-manager.txt => charger-manager.rst} (78%)
rename Documentation/power/{drivers-testing.txt => drivers-testing.rst} (86%)
rename Documentation/power/{energy-model.txt => energy-model.rst} (74%)
rename Documentation/power/{freezing-of-tasks.txt => freezing-of-tasks.rst} (75%)
create mode 100644 Documentation/power/index.rst
rename Documentation/power/{interface.txt => interface.rst} (84%)
rename Documentation/power/{opp.txt => opp.rst} (78%)
rename Documentation/power/{pci.txt => pci.rst} (97%)
rename Documentation/power/{pm_qos_interface.txt => pm_qos_interface.rst} (62%)
create mode 100644 Documentation/power/power_supply_class.rst
delete mode 100644 Documentation/power/power_supply_class.txt
create mode 100644 Documentation/power/powercap/powercap.rst
delete mode 100644 Documentation/power/powercap/powercap.txt
rename Documentation/power/regulator/{consumer.txt => consumer.rst} (61%)
rename Documentation/power/regulator/{design.txt => design.rst} (86%)
rename Documentation/power/regulator/{machine.txt => machine.rst} (75%)
rename Documentation/power/regulator/{overview.txt => overview.rst} (79%)
create mode 100644 Documentation/power/regulator/regulator.rst
delete mode 100644 Documentation/power/regulator/regulator.txt
rename Documentation/power/{runtime_pm.txt => runtime_pm.rst} (89%)
rename Documentation/power/{s2ram.txt => s2ram.rst} (92%)
rename Documentation/power/{suspend-and-cpuhotplug.txt => suspend-and-cpuhotplug.rst} (90%)
rename Documentation/power/{suspend-and-interrupts.txt => suspend-and-interrupts.rst} (98%)
rename Documentation/power/{swsusp-and-swap-files.txt => swsusp-and-swap-files.rst} (83%)
rename Documentation/power/{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} (67%)
create mode 100644 Documentation/power/swsusp.rst
delete mode 100644 Documentation/power/swsusp.txt
rename Documentation/power/{tricks.txt => tricks.rst} (93%)
rename Documentation/power/{userland-swsusp.txt => userland-swsusp.rst} (85%)
rename Documentation/power/{video.txt => video.rst} (56%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
create mode 100644 Documentation/powerpc/ptrace.rst
delete mode 100644 Documentation/powerpc/ptrace.txt
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
create mode 100644 Documentation/riscv/index.rst
rename Documentation/riscv/{pmu.txt => pmu.rst} (77%)
rename Documentation/scheduler/{completion.txt => completion.rst} (94%)
create mode 100644 Documentation/scheduler/index.rst
rename Documentation/scheduler/{sched-arch.txt => sched-arch.rst} (81%)
rename Documentation/scheduler/{sched-bwc.txt => sched-bwc.rst} (90%)
rename Documentation/scheduler/{sched-deadline.txt => sched-deadline.rst} (88%)
rename Documentation/scheduler/{sched-design-CFS.txt => sched-design-CFS.rst} (97%)
rename Documentation/scheduler/{sched-domains.txt => sched-domains.rst} (97%)
rename Documentation/scheduler/{sched-energy.txt => sched-energy.rst} (96%)
rename Documentation/scheduler/{sched-nice-design.txt => sched-nice-design.rst} (98%)
rename Documentation/scheduler/{sched-rt-group.txt => sched-rt-group.rst} (95%)
rename Documentation/scheduler/{sched-stats.txt => sched-stats.rst} (91%)
create mode 100644 Documentation/scheduler/text_files.rst
create mode 100644 Documentation/target/index.rst
create mode 100644 Documentation/target/scripts.rst
create mode 100644 Documentation/target/tcm_mod_builder.rst
delete mode 100644 Documentation/target/tcm_mod_builder.txt
rename Documentation/target/{tcmu-design.txt => tcmu-design.rst} (69%)
rename Documentation/timers/{highres.txt => highres.rst} (98%)
rename Documentation/timers/{hpet.txt => hpet.rst} (91%)
rename Documentation/timers/{hrtimers.txt => hrtimers.rst} (98%)
create mode 100644 Documentation/timers/index.rst
rename Documentation/timers/{NO_HZ.txt => no_hz.rst} (93%)
rename Documentation/timers/{timekeeping.txt => timekeeping.rst} (98%)
rename Documentation/timers/{timers-howto.txt => timers-howto.rst} (93%)
rename Documentation/watchdog/{convert_drivers_to_kernel_api.txt => convert_drivers_to_kernel_api.rst} (75%)
rename Documentation/watchdog/{hpwdt.txt => hpwdt.rst} (78%)
create mode 100644 Documentation/watchdog/index.rst
rename Documentation/watchdog/{mlx-wdt.txt => mlx-wdt.rst} (78%)
rename Documentation/watchdog/{pcwd-watchdog.txt => pcwd-watchdog.rst} (89%)
rename Documentation/watchdog/{watchdog-api.txt => watchdog-api.rst} (80%)
rename Documentation/watchdog/{watchdog-kernel-api.txt => watchdog-kernel-api.rst} (90%)
create mode 100644 Documentation/watchdog/watchdog-parameters.rst
delete mode 100644 Documentation/watchdog/watchdog-parameters.txt
rename Documentation/watchdog/{watchdog-pm.txt => watchdog-pm.rst} (92%)
rename Documentation/watchdog/{wdt.txt => wdt.rst} (68%)
rename Documentation/xilinx/{eemi.txt => eemi.rst} (92%)
create mode 100644 Documentation/xilinx/index.rst
--
2.21.0
^ permalink raw reply
* [PATCH v4 11/28] docs: ide: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Borislav Petkov, Jens Axboe, David S. Miller,
Geert Uytterhoeven, linux-ide, linux-m68k
In-Reply-To: <cover.1560361364.git.mchehab+samsung@kernel.org>
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Geert Uytterhoeven <geert@linux-m68k.org>
---
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/cdrom/ide-cd.rst | 18 +--
Documentation/ide/changelogs.rst | 17 ++
.../ide/{ide-tape.txt => ide-tape.rst} | 23 +--
Documentation/ide/{ide.txt => ide.rst} | 147 ++++++++++--------
Documentation/ide/index.rst | 21 +++
...arm-plug-howto.txt => warm-plug-howto.rst} | 10 +-
arch/m68k/q40/README | 2 +-
drivers/ide/Kconfig | 20 +--
9 files changed, 155 insertions(+), 105 deletions(-)
create mode 100644 Documentation/ide/changelogs.rst
rename Documentation/ide/{ide-tape.txt => ide-tape.rst} (83%)
rename Documentation/ide/{ide.txt => ide.rst} (72%)
create mode 100644 Documentation/ide/index.rst
rename Documentation/ide/{warm-plug-howto.txt => warm-plug-howto.rst} (61%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 581d8888e829..affed5d447de 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1502,7 +1502,7 @@
Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc
.vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr
.cdrom .chs .ignore_cable are additional options
- See Documentation/ide/ide.txt.
+ See Documentation/ide/ide.rst.
ide-generic.probe-mask= [HW] (E)IDE subsystem
Format: <int>
diff --git a/Documentation/cdrom/ide-cd.rst b/Documentation/cdrom/ide-cd.rst
index dadc94ef6b6c..bdccb74fc92d 100644
--- a/Documentation/cdrom/ide-cd.rst
+++ b/Documentation/cdrom/ide-cd.rst
@@ -47,7 +47,7 @@ This driver provides the following features:
---------------
0. The ide-cd relies on the ide disk driver. See
- Documentation/ide/ide.txt for up-to-date information on the ide
+ Documentation/ide/ide.rst for up-to-date information on the ide
driver.
1. Make sure that the ide and ide-cd drivers are compiled into the
@@ -62,7 +62,7 @@ This driver provides the following features:
Depending on what type of IDE interface you have, you may need to
specify additional configuration options. See
- Documentation/ide/ide.txt.
+ Documentation/ide/ide.rst.
2. You should also ensure that the iso9660 filesystem is either
compiled into the kernel or available as a loadable module. You
@@ -82,7 +82,7 @@ This driver provides the following features:
on the primary IDE interface are called `hda` and `hdb`,
respectively. The drives on the secondary interface are called
`hdc` and `hdd`. (Interfaces at other locations get other letters
- in the third position; see Documentation/ide/ide.txt.)
+ in the third position; see Documentation/ide/ide.rst.)
If you want your CDROM drive to be found automatically by the
driver, you should make sure your IDE interface uses either the
@@ -91,7 +91,7 @@ This driver provides the following features:
be jumpered as `master`. (If for some reason you cannot configure
your system in this manner, you can probably still use the driver.
You may have to pass extra configuration information to the kernel
- when you boot, however. See Documentation/ide/ide.txt for more
+ when you boot, however. See Documentation/ide/ide.rst for more
information.)
4. Boot the system. If the drive is recognized, you should see a
@@ -163,7 +163,7 @@ to change. If the slot number is -1, the drive is unloaded.
This section discusses some common problems encountered when trying to
use the driver, and some possible solutions. Note that if you are
experiencing problems, you should probably also review
-Documentation/ide/ide.txt for current information about the underlying
+Documentation/ide/ide.rst for current information about the underlying
IDE support code. Some of these items apply only to earlier versions
of the driver, but are mentioned here for completeness.
@@ -173,7 +173,7 @@ from the driver.
a. Drive is not detected during booting.
- Review the configuration instructions above and in
- Documentation/ide/ide.txt, and check how your hardware is
+ Documentation/ide/ide.rst, and check how your hardware is
configured.
- If your drive is the only device on an IDE interface, it should
@@ -181,7 +181,7 @@ a. Drive is not detected during booting.
- If your IDE interface is not at the standard addresses of 0x170
or 0x1f0, you'll need to explicitly inform the driver using a
- lilo option. See Documentation/ide/ide.txt. (This feature was
+ lilo option. See Documentation/ide/ide.rst. (This feature was
added around kernel version 1.3.30.)
- If the autoprobing is not finding your drive, you can tell the
@@ -207,7 +207,7 @@ a. Drive is not detected during booting.
Support for some interfaces needing extra initialization is
provided in later 1.3.x kernels. You may need to turn on
additional kernel configuration options to get them to work;
- see Documentation/ide/ide.txt.
+ see Documentation/ide/ide.rst.
Even if support is not available for your interface, you may be
able to get it to work with the following procedure. First boot
@@ -261,7 +261,7 @@ c. System hangups.
be worked around by specifying the `serialize` option when
booting. Recent kernels should be able to detect the need for
this automatically in most cases, but the detection is not
- foolproof. See Documentation/ide/ide.txt for more information
+ foolproof. See Documentation/ide/ide.rst for more information
about the `serialize` option and the CMD640B.
- Note that many MS-DOS CDROM drivers will work with such buggy
diff --git a/Documentation/ide/changelogs.rst b/Documentation/ide/changelogs.rst
new file mode 100644
index 000000000000..fdf9d0fb8027
--- /dev/null
+++ b/Documentation/ide/changelogs.rst
@@ -0,0 +1,17 @@
+Changelog for ide cd
+--------------------
+
+ .. include:: ChangeLog.ide-cd.1994-2004
+ :literal:
+
+Changelog for ide floppy
+------------------------
+
+ .. include:: ChangeLog.ide-floppy.1996-2002
+ :literal:
+
+Changelog for ide tape
+----------------------
+
+ .. include:: ChangeLog.ide-tape.1995-2002
+ :literal:
diff --git a/Documentation/ide/ide-tape.txt b/Documentation/ide/ide-tape.rst
similarity index 83%
rename from Documentation/ide/ide-tape.txt
rename to Documentation/ide/ide-tape.rst
index 3f348a0b21d8..3e061d9c0e38 100644
--- a/Documentation/ide/ide-tape.txt
+++ b/Documentation/ide/ide-tape.rst
@@ -1,4 +1,6 @@
-IDE ATAPI streaming tape driver.
+===============================
+IDE ATAPI streaming tape driver
+===============================
This driver is a part of the Linux ide driver.
@@ -10,14 +12,14 @@ to the request-list of the block device, and waits for their completion.
The block device major and minor numbers are determined from the
tape's relative position in the ide interfaces, as explained in ide.c.
-The character device interface consists of the following devices:
+The character device interface consists of the following devices::
-ht0 major 37, minor 0 first IDE tape, rewind on close.
-ht1 major 37, minor 1 second IDE tape, rewind on close.
-...
-nht0 major 37, minor 128 first IDE tape, no rewind on close.
-nht1 major 37, minor 129 second IDE tape, no rewind on close.
-...
+ ht0 major 37, minor 0 first IDE tape, rewind on close.
+ ht1 major 37, minor 1 second IDE tape, rewind on close.
+ ...
+ nht0 major 37, minor 128 first IDE tape, no rewind on close.
+ nht1 major 37, minor 129 second IDE tape, no rewind on close.
+ ...
The general magnetic tape commands compatible interface, as defined by
include/linux/mtio.h, is accessible through the character device.
@@ -40,9 +42,10 @@ Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
Here are some words from the first releases of hd.c, which are quoted
in ide.c and apply here as well:
-| Special care is recommended. Have Fun!
+* Special care is recommended. Have Fun!
-Possible improvements:
+Possible improvements
+=====================
1. Support for the ATAPI overlap protocol.
diff --git a/Documentation/ide/ide.txt b/Documentation/ide/ide.rst
similarity index 72%
rename from Documentation/ide/ide.txt
rename to Documentation/ide/ide.rst
index 7aca987c23d9..88bdcba92f7d 100644
--- a/Documentation/ide/ide.txt
+++ b/Documentation/ide/ide.rst
@@ -1,41 +1,43 @@
-
- Information regarding the Enhanced IDE drive in Linux 2.6
-
-==============================================================================
-
+============================================
+Information regarding the Enhanced IDE drive
+============================================
The hdparm utility can be used to control various IDE features on a
running system. It is packaged separately. Please Look for it on popular
linux FTP sites.
+-------------------------------------------------------------------------------
+.. important::
-*** IMPORTANT NOTICES: BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
-*** =================
-*** PCI versions of the CMD640 and RZ1000 interfaces are now detected
-*** automatically at startup when PCI BIOS support is configured.
-***
-*** Linux disables the "prefetch" ("readahead") mode of the RZ1000
-*** to prevent data corruption possible due to hardware design flaws.
-***
-*** For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
-*** drive for which the "prefetch" mode of the CMD640 is turned on.
-*** If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
-*** used again.
-***
-*** For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
-*** for which the "prefetch" mode of the CMD640 is turned off.
-*** If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
-*** used again.
-***
-*** The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
-*** automatically detected by Linux. For safe, reliable operation with such
-*** interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
-***
-*** Use of the "serialize" option is no longer necessary.
-
-================================================================================
-Common pitfalls:
+ BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
+
+ PCI versions of the CMD640 and RZ1000 interfaces are now detected
+ automatically at startup when PCI BIOS support is configured.
+
+ Linux disables the "prefetch" ("readahead") mode of the RZ1000
+ to prevent data corruption possible due to hardware design flaws.
+
+ For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
+ drive for which the "prefetch" mode of the CMD640 is turned on.
+ If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
+ used again.
+
+ For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
+ for which the "prefetch" mode of the CMD640 is turned off.
+ If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
+ used again.
+
+ The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
+ automatically detected by Linux. For safe, reliable operation with such
+ interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
+
+ Use of the "serialize" option is no longer necessary.
+
+-------------------------------------------------------------------------------
+
+Common pitfalls
+===============
- 40-conductor IDE cables are capable of transferring data in DMA modes up to
udma2, but no faster.
@@ -49,19 +51,18 @@ Common pitfalls:
- Even better try to stick to the same vendor and device type on the same
cable.
-================================================================================
-
-This is the multiple IDE interface driver, as evolved from hd.c.
+This is the multiple IDE interface driver, as evolved from hd.c
+===============================================================
It supports up to 9 IDE interfaces per default, on one or more IRQs (usually
-14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.
+14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.::
-Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
-Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
-Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
-Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
-fifth.. ide4, usually PCI, probed
-sixth.. ide5, usually PCI, probed
+ Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
+ Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
+ Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
+ Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
+ fifth.. ide4, usually PCI, probed
+ sixth.. ide5, usually PCI, probed
To access devices on interfaces > ide0, device entries please make sure that
device files for them are present in /dev. If not, please create such
@@ -80,12 +81,15 @@ seldom occurs. Be careful, and if in doubt, don't do it!
Drives are normally found by auto-probing and/or examining the CMOS/BIOS data.
For really weird situations, the apparent (fdisk) geometry can also be specified
-on the kernel "command line" using LILO. The format of such lines is:
+on the kernel "command line" using LILO. The format of such lines is::
ide_core.chs=[interface_number.device_number]:cyls,heads,sects
-or ide_core.cdrom=[interface_number.device_number]
-For example:
+or::
+
+ ide_core.cdrom=[interface_number.device_number]
+
+For example::
ide_core.chs=1.0:1050,32,64 ide_core.cdrom=1.1
@@ -96,10 +100,12 @@ geometry for partitioning purposes (fdisk).
If the auto-probing during boot time confuses a drive (ie. the drive works
with hd.c but not with ide.c), then an command line option may be specified
for each drive for which you'd like the drive to skip the hardware
-probe/identification sequence. For example:
+probe/identification sequence. For example::
ide_core.noprobe=0.1
-or
+
+or::
+
ide_core.chs=1.0:768,16,32
ide_core.noprobe=1.0
@@ -115,22 +121,24 @@ Such drives will be identified at boot time, just like a hard disk.
If for some reason your cdrom drive is *not* found at boot time, you can force
the probe to look harder by supplying a kernel command line parameter
-via LILO, such as:
+via LILO, such as:::
ide_core.cdrom=1.0 /* "master" on second interface (hdc) */
-or
+
+or::
+
ide_core.cdrom=1.1 /* "slave" on second interface (hdd) */
For example, a GW2000 system might have a hard drive on the primary
interface (/dev/hda) and an IDE cdrom drive on the secondary interface
-(/dev/hdc). To mount a CD in the cdrom drive, one would use something like:
+(/dev/hdc). To mount a CD in the cdrom drive, one would use something like::
ln -sf /dev/hdc /dev/cdrom
mkdir /mnt/cdrom
mount /dev/cdrom /mnt/cdrom -t iso9660 -o ro
If, after doing all of the above, mount doesn't work and you see
-errors from the driver (with dmesg) complaining about `status=0xff',
+errors from the driver (with dmesg) complaining about `status=0xff`,
this means that the hardware is not responding to the driver's attempts
to read it. One of the following is probably the problem:
@@ -165,7 +173,7 @@ drivers can always be compiled as loadable modules, the chipset drivers
can only be compiled into the kernel, and the core code (ide.c) can be
compiled as a loadable module provided no chipset support is needed.
-When using ide.c as a module in combination with kmod, add:
+When using ide.c as a module in combination with kmod, add::
alias block-major-3 ide-probe
@@ -176,10 +184,8 @@ driver using the "options=" keyword to insmod, while replacing any ',' with
';'.
-================================================================================
-
Summary of ide driver parameters for kernel command line
---------------------------------------------------------
+========================================================
For legacy IDE VLB host drivers (ali14xx/dtc2278/ht6560b/qd65xx/umc8672)
you need to explicitly enable probing by using "probe" kernel parameter,
@@ -226,28 +232,31 @@ Other kernel parameters for ide_core are:
* "chs=[interface_number.device_number]" to force device as a disk (using CHS)
-================================================================================
Some Terminology
-----------------
-IDE = Integrated Drive Electronics, meaning that each drive has a built-in
-controller, which is why an "IDE interface card" is not a "controller card".
+================
-ATA = AT (the old IBM 286 computer) Attachment Interface, a draft American
-National Standard for connecting hard drives to PCs. This is the official
-name for "IDE".
+IDE
+ Integrated Drive Electronics, meaning that each drive has a built-in
+ controller, which is why an "IDE interface card" is not a "controller card".
-The latest standards define some enhancements, known as the ATA-6 spec,
-which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+ATA
+ AT (the old IBM 286 computer) Attachment Interface, a draft American
+ National Standard for connecting hard drives to PCs. This is the official
+ name for "IDE".
-ATAPI = ATA Packet Interface, a new protocol for controlling the drives,
-similar to SCSI protocols, created at the same time as the ATA2 standard.
-ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
-LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
-drives.
+ The latest standards define some enhancements, known as the ATA-6 spec,
+ which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+
+ATAPI
+ ATA Packet Interface, a new protocol for controlling the drives,
+ similar to SCSI protocols, created at the same time as the ATA2 standard.
+ ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
+ LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
+ drives.
mlord@pobox.com
---
+
Wed Apr 17 22:52:44 CEST 2002 edited by Marcin Dalecki, the current
maintainer.
diff --git a/Documentation/ide/index.rst b/Documentation/ide/index.rst
new file mode 100644
index 000000000000..45bc12d3957f
--- /dev/null
+++ b/Documentation/ide/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+==================================
+Integrated Drive Electronics (IDE)
+==================================
+
+.. toctree::
+ :maxdepth: 1
+
+ ide
+ ide-tape
+ warm-plug-howto
+
+ changelogs
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/ide/warm-plug-howto.txt b/Documentation/ide/warm-plug-howto.rst
similarity index 61%
rename from Documentation/ide/warm-plug-howto.txt
rename to Documentation/ide/warm-plug-howto.rst
index 98152bcd515a..c245242ef2f1 100644
--- a/Documentation/ide/warm-plug-howto.txt
+++ b/Documentation/ide/warm-plug-howto.rst
@@ -1,14 +1,14 @@
-
+===================
IDE warm-plug HOWTO
===================
-To warm-plug devices on a port 'idex':
+To warm-plug devices on a port 'idex'::
-# echo -n "1" > /sys/class/ide_port/idex/delete_devices
+ # echo -n "1" > /sys/class/ide_port/idex/delete_devices
-unplug old device(s) and plug new device(s)
+unplug old device(s) and plug new device(s)::
-# echo -n "1" > /sys/class/ide_port/idex/scan
+ # echo -n "1" > /sys/class/ide_port/idex/scan
done
diff --git a/arch/m68k/q40/README b/arch/m68k/q40/README
index 93f4c4cd3c45..a4991d2d8af6 100644
--- a/arch/m68k/q40/README
+++ b/arch/m68k/q40/README
@@ -31,7 +31,7 @@ drivers used by the Q40, apart from the very obvious (console etc.):
char/joystick/* # most of this should work, not
# in default config.in
block/q40ide.c # startup for ide
- ide* # see Documentation/ide/ide.txt
+ ide* # see Documentation/ide/ide.rst
floppy.c # normal PC driver, DMA emu in asm/floppy.h
# and arch/m68k/kernel/entry.S
# see drivers/block/README.fd
diff --git a/drivers/ide/Kconfig b/drivers/ide/Kconfig
index fdd2a62f9d52..9eada392df15 100644
--- a/drivers/ide/Kconfig
+++ b/drivers/ide/Kconfig
@@ -25,13 +25,13 @@ menuconfig IDE
To compile this driver as a module, choose M here: the
module will be called ide-core.
- For further information, please read <file:Documentation/ide/ide.txt>.
+ For further information, please read <file:Documentation/ide/ide.rst>.
If unsure, say N.
if IDE
-comment "Please see Documentation/ide/ide.txt for help/info on IDE drives"
+comment "Please see Documentation/ide/ide.rst for help/info on IDE drives"
config IDE_XFER_MODE
bool
@@ -163,7 +163,7 @@ config BLK_DEV_IDETAPE
along with other IDE devices, as "hdb" or "hdc", or something
similar, and will be mapped to a character device such as "ht0"
(check the boot messages with dmesg). Be sure to consult the
- <file:drivers/ide/ide-tape.c> and <file:Documentation/ide/ide.txt>
+ <file:drivers/ide/ide-tape.c> and <file:Documentation/ide/ide.rst>
files for usage information.
To compile this driver as a module, choose M here: the
@@ -251,7 +251,7 @@ config BLK_DEV_CMD640
The CMD640 chip is also used on add-in cards by Acculogic, and on
the "CSA-6400E PCI to IDE controller" that some people have. For
- details, read <file:Documentation/ide/ide.txt>.
+ details, read <file:Documentation/ide/ide.rst>.
config BLK_DEV_CMD640_ENHANCED
bool "CMD640 enhanced support"
@@ -259,7 +259,7 @@ config BLK_DEV_CMD640_ENHANCED
help
This option includes support for setting/autotuning PIO modes and
prefetch on CMD640 IDE interfaces. For details, read
- <file:Documentation/ide/ide.txt>. If you have a CMD640 IDE interface
+ <file:Documentation/ide/ide.rst>. If you have a CMD640 IDE interface
and your BIOS does not already do this for you, then say Y here.
Otherwise say N.
@@ -819,7 +819,7 @@ config BLK_DEV_ALI14XX
boot parameter. It enables support for the secondary IDE interface
of the ALI M1439/1443/1445/1487/1489 chipsets, and permits faster
I/O speeds to be set as well.
- See the files <file:Documentation/ide/ide.txt> and
+ See the files <file:Documentation/ide/ide.rst> and
<file:drivers/ide/ali14xx.c> for more info.
config BLK_DEV_DTC2278
@@ -830,7 +830,7 @@ config BLK_DEV_DTC2278
This driver is enabled at runtime using the "dtc2278.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the DTC-2278 card, and permits faster I/O speeds to be set as
- well. See the <file:Documentation/ide/ide.txt> and
+ well. See the <file:Documentation/ide/ide.rst> and
<file:drivers/ide/dtc2278.c> files for more info.
config BLK_DEV_HT6560B
@@ -841,7 +841,7 @@ config BLK_DEV_HT6560B
This driver is enabled at runtime using the "ht6560b.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the Holtek card, and permits faster I/O speeds to be set as well.
- See the <file:Documentation/ide/ide.txt> and
+ See the <file:Documentation/ide/ide.rst> and
<file:drivers/ide/ht6560b.c> files for more info.
config BLK_DEV_QD65XX
@@ -851,7 +851,7 @@ config BLK_DEV_QD65XX
help
This driver is enabled at runtime using the "qd65xx.probe" kernel
boot parameter. It permits faster I/O speeds to be set. See the
- <file:Documentation/ide/ide.txt> and <file:drivers/ide/qd65xx.c>
+ <file:Documentation/ide/ide.rst> and <file:drivers/ide/qd65xx.c>
for more info.
config BLK_DEV_UMC8672
@@ -862,7 +862,7 @@ config BLK_DEV_UMC8672
This driver is enabled at runtime using the "umc8672.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the UMC-8672, and permits faster I/O speeds to be set as well.
- See the files <file:Documentation/ide/ide.txt> and
+ See the files <file:Documentation/ide/ide.rst> and
<file:drivers/ide/umc8672.c> for more info.
endif
--
2.21.0
^ permalink raw reply related
* [PATCH v4 02/28] docs: arm64: convert docs to ReST and rename to .rst
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Catalin Marinas, Will Deacon, Harry Wei,
Alex Shi, Paolo Bonzini, Radim Krčmář,
Ard Biesheuvel, linux-arm-kernel, kvm, linux-efi
In-Reply-To: <cover.1560361364.git.mchehab+samsung@kernel.org>
The documentation is in a format that is very close to ReST format.
The conversion is actually:
- add blank lines in order to identify paragraphs;
- fixing tables markups;
- adding some lists markups;
- marking literal blocks;
- adjust some title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...object_usage.txt => acpi_object_usage.rst} | 288 ++++++++++++------
.../arm64/{arm-acpi.txt => arm-acpi.rst} | 155 +++++-----
.../arm64/{booting.txt => booting.rst} | 91 ++++--
...egisters.txt => cpu-feature-registers.rst} | 204 +++++++------
.../arm64/{elf_hwcaps.txt => elf_hwcaps.rst} | 56 +---
.../{hugetlbpage.txt => hugetlbpage.rst} | 7 +-
Documentation/arm64/index.rst | 28 ++
...structions.txt => legacy_instructions.rst} | 43 ++-
Documentation/arm64/memory.rst | 98 ++++++
Documentation/arm64/memory.txt | 97 ------
...ication.txt => pointer-authentication.rst} | 2 +
...{silicon-errata.txt => silicon-errata.rst} | 65 +++-
Documentation/arm64/{sve.txt => sve.rst} | 12 +-
...agged-pointers.txt => tagged-pointers.rst} | 6 +-
.../translations/zh_CN/arm64/booting.txt | 4 +-
.../zh_CN/arm64/legacy_instructions.txt | 4 +-
.../translations/zh_CN/arm64/memory.txt | 4 +-
.../zh_CN/arm64/silicon-errata.txt | 4 +-
.../zh_CN/arm64/tagged-pointers.txt | 4 +-
Documentation/virtual/kvm/api.txt | 2 +-
arch/arm64/include/asm/efi.h | 2 +-
arch/arm64/include/asm/image.h | 2 +-
arch/arm64/include/uapi/asm/sigcontext.h | 2 +-
arch/arm64/kernel/kexec_image.c | 2 +-
24 files changed, 703 insertions(+), 479 deletions(-)
rename Documentation/arm64/{acpi_object_usage.txt => acpi_object_usage.rst} (84%)
rename Documentation/arm64/{arm-acpi.txt => arm-acpi.rst} (86%)
rename Documentation/arm64/{booting.txt => booting.rst} (86%)
rename Documentation/arm64/{cpu-feature-registers.txt => cpu-feature-registers.rst} (65%)
rename Documentation/arm64/{elf_hwcaps.txt => elf_hwcaps.rst} (92%)
rename Documentation/arm64/{hugetlbpage.txt => hugetlbpage.rst} (86%)
create mode 100644 Documentation/arm64/index.rst
rename Documentation/arm64/{legacy_instructions.txt => legacy_instructions.rst} (73%)
create mode 100644 Documentation/arm64/memory.rst
delete mode 100644 Documentation/arm64/memory.txt
rename Documentation/arm64/{pointer-authentication.txt => pointer-authentication.rst} (99%)
rename Documentation/arm64/{silicon-errata.txt => silicon-errata.rst} (55%)
rename Documentation/arm64/{sve.txt => sve.rst} (98%)
rename Documentation/arm64/{tagged-pointers.txt => tagged-pointers.rst} (94%)
diff --git a/Documentation/arm64/acpi_object_usage.txt b/Documentation/arm64/acpi_object_usage.rst
similarity index 84%
rename from Documentation/arm64/acpi_object_usage.txt
rename to Documentation/arm64/acpi_object_usage.rst
index c77010c5c1f0..d51b69dc624d 100644
--- a/Documentation/arm64/acpi_object_usage.txt
+++ b/Documentation/arm64/acpi_object_usage.rst
@@ -1,5 +1,7 @@
+===========
ACPI Tables
------------
+===========
+
The expectations of individual ACPI tables are discussed in the list that
follows.
@@ -11,54 +13,71 @@ outside of the UEFI Forum (see Section 5.2.6 of the specification).
For ACPI on arm64, tables also fall into the following categories:
- -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
+ - Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
- -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
+ - Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
- -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
+ - Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO,
TCPA, TPM2, UEFI, XENV
- -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
+ - Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
+====== ========================================================================
Table Usage for ARMv8 Linux
------ ----------------------------------------------------------------
+====== ========================================================================
BERT Section 18.3 (signature == "BERT")
- == Boot Error Record Table ==
+
+ **Boot Error Record Table**
+
Must be supplied if RAS support is provided by the platform. It
is recommended this table be supplied.
BOOT Signature Reserved (signature == "BOOT")
- == simple BOOT flag table ==
+
+ **simple BOOT flag table**
+
Microsoft only table, will not be supported.
BGRT Section 5.2.22 (signature == "BGRT")
- == Boot Graphics Resource Table ==
+
+ **Boot Graphics Resource Table**
+
Optional, not currently supported, with no real use-case for an
ARM server.
CPEP Section 5.2.18 (signature == "CPEP")
- == Corrected Platform Error Polling table ==
+
+ **Corrected Platform Error Polling table**
+
Optional, not currently supported, and not recommended until such
time as ARM-compatible hardware is available, and the specification
suitably modified.
CSRT Signature Reserved (signature == "CSRT")
- == Core System Resources Table ==
+
+ **Core System Resources Table**
+
Optional, not currently supported.
DBG2 Signature Reserved (signature == "DBG2")
- == DeBuG port table 2 ==
+
+ **DeBuG port table 2**
+
License has changed and should be usable. Optional if used instead
of earlycon=<device> on the command line.
DBGP Signature Reserved (signature == "DBGP")
- == DeBuG Port table ==
+
+ **DeBuG Port table**
+
Microsoft only table, will not be supported.
DSDT Section 5.2.11.1 (signature == "DSDT")
- == Differentiated System Description Table ==
+
+ **Differentiated System Description Table**
+
A DSDT is required; see also SSDT.
ACPI tables contain only one DSDT but can contain one or more SSDTs,
@@ -66,22 +85,30 @@ DSDT Section 5.2.11.1 (signature == "DSDT")
but cannot modify or replace anything in the DSDT.
DMAR Signature Reserved (signature == "DMAR")
- == DMA Remapping table ==
+
+ **DMA Remapping table**
+
x86 only table, will not be supported.
DRTM Signature Reserved (signature == "DRTM")
- == Dynamic Root of Trust for Measurement table ==
+
+ **Dynamic Root of Trust for Measurement table**
+
Optional, not currently supported.
ECDT Section 5.2.16 (signature == "ECDT")
- == Embedded Controller Description Table ==
+
+ **Embedded Controller Description Table**
+
Optional, not currently supported, but could be used on ARM if and
only if one uses the GPE_BIT field to represent an IRQ number, since
there are no GPE blocks defined in hardware reduced mode. This would
need to be modified in the ACPI specification.
EINJ Section 18.6 (signature == "EINJ")
- == Error Injection table ==
+
+ **Error Injection table**
+
This table is very useful for testing platform response to error
conditions; it allows one to inject an error into the system as
if it had actually occurred. However, this table should not be
@@ -89,27 +116,35 @@ EINJ Section 18.6 (signature == "EINJ")
and executed with the ACPICA tools only during testing.
ERST Section 18.5 (signature == "ERST")
- == Error Record Serialization Table ==
+
+ **Error Record Serialization Table**
+
On a platform supports RAS, this table must be supplied if it is not
UEFI-based; if it is UEFI-based, this table may be supplied. When this
table is not present, UEFI run time service will be utilized to save
and retrieve hardware error information to and from a persistent store.
ETDT Signature Reserved (signature == "ETDT")
- == Event Timer Description Table ==
+
+ **Event Timer Description Table**
+
Obsolete table, will not be supported.
FACS Section 5.2.10 (signature == "FACS")
- == Firmware ACPI Control Structure ==
+
+ **Firmware ACPI Control Structure**
+
It is unlikely that this table will be terribly useful. If it is
provided, the Global Lock will NOT be used since it is not part of
the hardware reduced profile, and only 64-bit address fields will
be considered valid.
FADT Section 5.2.9 (signature == "FACP")
- == Fixed ACPI Description Table ==
+
+ **Fixed ACPI Description Table**
Required for arm64.
+
The HW_REDUCED_ACPI flag must be set. All of the fields that are
to be ignored when HW_REDUCED_ACPI is set are expected to be set to
zero.
@@ -118,22 +153,28 @@ FADT Section 5.2.9 (signature == "FACP")
used, not FIRMWARE_CTRL.
If PSCI is used (as is recommended), make sure that ARM_BOOT_ARCH is
- filled in properly -- that the PSCI_COMPLIANT flag is set and that
+ filled in properly - that the PSCI_COMPLIANT flag is set and that
PSCI_USE_HVC is set or unset as needed (see table 5-37).
For the DSDT that is also required, the X_DSDT field is to be used,
not the DSDT field.
FPDT Section 5.2.23 (signature == "FPDT")
- == Firmware Performance Data Table ==
+
+ **Firmware Performance Data Table**
+
Optional, not currently supported.
GTDT Section 5.2.24 (signature == "GTDT")
- == Generic Timer Description Table ==
+
+ **Generic Timer Description Table**
+
Required for arm64.
HEST Section 18.3.2 (signature == "HEST")
- == Hardware Error Source Table ==
+
+ **Hardware Error Source Table**
+
ARM-specific error sources have been defined; please use those or the
PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER
Bridge), or use type 9 (Generic Hardware Error Source). Firmware first
@@ -144,122 +185,174 @@ HEST Section 18.3.2 (signature == "HEST")
is recommended this table be supplied.
HPET Signature Reserved (signature == "HPET")
- == High Precision Event timer Table ==
+
+ **High Precision Event timer Table**
+
x86 only table, will not be supported.
IBFT Signature Reserved (signature == "IBFT")
- == iSCSI Boot Firmware Table ==
+
+ **iSCSI Boot Firmware Table**
+
Microsoft defined table, support TBD.
IORT Signature Reserved (signature == "IORT")
- == Input Output Remapping Table ==
+
+ **Input Output Remapping Table**
+
arm64 only table, required in order to describe IO topology, SMMUs,
and GIC ITSs, and how those various components are connected together,
such as identifying which components are behind which SMMUs/ITSs.
This table will only be required on certain SBSA platforms (e.g.,
- when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it
+ when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it
remains optional.
IVRS Signature Reserved (signature == "IVRS")
- == I/O Virtualization Reporting Structure ==
+
+ **I/O Virtualization Reporting Structure**
+
x86_64 (AMD) only table, will not be supported.
LPIT Signature Reserved (signature == "LPIT")
- == Low Power Idle Table ==
+
+ **Low Power Idle Table**
+
x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor
descriptions and power states on ARM platforms should use the DSDT
and define processor container devices (_HID ACPI0010, Section 8.4,
and more specifically 8.4.3 and and 8.4.4).
MADT Section 5.2.12 (signature == "APIC")
- == Multiple APIC Description Table ==
+
+ **Multiple APIC Description Table**
+
Required for arm64. Only the GIC interrupt controller structures
should be used (types 0xA - 0xF).
MCFG Signature Reserved (signature == "MCFG")
- == Memory-mapped ConFiGuration space ==
+
+ **Memory-mapped ConFiGuration space**
+
If the platform supports PCI/PCIe, an MCFG table is required.
MCHI Signature Reserved (signature == "MCHI")
- == Management Controller Host Interface table ==
+
+ **Management Controller Host Interface table**
+
Optional, not currently supported.
MPST Section 5.2.21 (signature == "MPST")
- == Memory Power State Table ==
+
+ **Memory Power State Table**
+
Optional, not currently supported.
MSCT Section 5.2.19 (signature == "MSCT")
- == Maximum System Characteristic Table ==
+
+ **Maximum System Characteristic Table**
+
Optional, not currently supported.
MSDM Signature Reserved (signature == "MSDM")
- == Microsoft Data Management table ==
+
+ **Microsoft Data Management table**
+
Microsoft only table, will not be supported.
NFIT Section 5.2.25 (signature == "NFIT")
- == NVDIMM Firmware Interface Table ==
+
+ **NVDIMM Firmware Interface Table**
+
Optional, not currently supported.
OEMx Signature of "OEMx" only
- == OEM Specific Tables ==
+
+ **OEM Specific Tables**
+
All tables starting with a signature of "OEM" are reserved for OEM
use. Since these are not meant to be of general use but are limited
to very specific end users, they are not recommended for use and are
not supported by the kernel for arm64.
PCCT Section 14.1 (signature == "PCCT)
- == Platform Communications Channel Table ==
+
+ **Platform Communications Channel Table**
+
Recommend for use on arm64; use of PCC is recommended when using CPPC
to control performance and power for platform processors.
PMTT Section 5.2.21.12 (signature == "PMTT")
- == Platform Memory Topology Table ==
+
+ **Platform Memory Topology Table**
+
Optional, not currently supported.
PSDT Section 5.2.11.3 (signature == "PSDT")
- == Persistent System Description Table ==
+
+ **Persistent System Description Table**
+
Obsolete table, will not be supported.
RASF Section 5.2.20 (signature == "RASF")
- == RAS Feature table ==
+
+ **RAS Feature table**
+
Optional, not currently supported.
RSDP Section 5.2.5 (signature == "RSD PTR")
- == Root System Description PoinTeR ==
+
+ **Root System Description PoinTeR**
+
Required for arm64.
RSDT Section 5.2.7 (signature == "RSDT")
- == Root System Description Table ==
+
+ **Root System Description Table**
+
Since this table can only provide 32-bit addresses, it is deprecated
on arm64, and will not be used. If provided, it will be ignored.
SBST Section 5.2.14 (signature == "SBST")
- == Smart Battery Subsystem Table ==
+
+ **Smart Battery Subsystem Table**
+
Optional, not currently supported.
SLIC Signature Reserved (signature == "SLIC")
- == Software LIcensing table ==
+
+ **Software LIcensing table**
+
Microsoft only table, will not be supported.
SLIT Section 5.2.17 (signature == "SLIT")
- == System Locality distance Information Table ==
+
+ **System Locality distance Information Table**
+
Optional in general, but required for NUMA systems.
SPCR Signature Reserved (signature == "SPCR")
- == Serial Port Console Redirection table ==
+
+ **Serial Port Console Redirection table**
+
Required for arm64.
SPMI Signature Reserved (signature == "SPMI")
- == Server Platform Management Interface table ==
+
+ **Server Platform Management Interface table**
+
Optional, not currently supported.
SRAT Section 5.2.16 (signature == "SRAT")
- == System Resource Affinity Table ==
+
+ **System Resource Affinity Table**
+
Optional, but if used, only the GICC Affinity structures are read.
To support arm64 NUMA, this table is required.
SSDT Section 5.2.11.2 (signature == "SSDT")
- == Secondary System Description Table ==
+
+ **Secondary System Description Table**
+
These tables are a continuation of the DSDT; these are recommended
for use with devices that can be added to a running system, but can
also serve the purpose of dividing up device descriptions into more
@@ -272,49 +365,69 @@ SSDT Section 5.2.11.2 (signature == "SSDT")
one DSDT but can contain many SSDTs.
STAO Signature Reserved (signature == "STAO")
- == _STA Override table ==
+
+ **_STA Override table**
+
Optional, but only necessary in virtualized environments in order to
hide devices from guest OSs.
TCPA Signature Reserved (signature == "TCPA")
- == Trusted Computing Platform Alliance table ==
+
+ **Trusted Computing Platform Alliance table**
+
Optional, not currently supported, and may need changes to fully
interoperate with arm64.
TPM2 Signature Reserved (signature == "TPM2")
- == Trusted Platform Module 2 table ==
+
+ **Trusted Platform Module 2 table**
+
Optional, not currently supported, and may need changes to fully
interoperate with arm64.
UEFI Signature Reserved (signature == "UEFI")
- == UEFI ACPI data table ==
+
+ **UEFI ACPI data table**
+
Optional, not currently supported. No known use case for arm64,
at present.
WAET Signature Reserved (signature == "WAET")
- == Windows ACPI Emulated devices Table ==
+
+ **Windows ACPI Emulated devices Table**
+
Microsoft only table, will not be supported.
WDAT Signature Reserved (signature == "WDAT")
- == Watch Dog Action Table ==
+
+ **Watch Dog Action Table**
+
Microsoft only table, will not be supported.
WDRT Signature Reserved (signature == "WDRT")
- == Watch Dog Resource Table ==
+
+ **Watch Dog Resource Table**
+
Microsoft only table, will not be supported.
WPBT Signature Reserved (signature == "WPBT")
- == Windows Platform Binary Table ==
+
+ **Windows Platform Binary Table**
+
Microsoft only table, will not be supported.
XENV Signature Reserved (signature == "XENV")
- == Xen project table ==
+
+ **Xen project table**
+
Optional, used only by Xen at present.
XSDT Section 5.2.8 (signature == "XSDT")
- == eXtended System Description Table ==
+
+ **eXtended System Description Table**
+
Required for arm64.
-
+====== ========================================================================
ACPI Objects
------------
@@ -323,10 +436,11 @@ shown in the list that follows; any object not explicitly mentioned below
should be used as needed for a particular platform or particular subsystem,
such as power management or PCI.
+===== ================ ========================================================
Name Section Usage for ARMv8 Linux
----- ------------ -------------------------------------------------
+===== ================ ========================================================
_CCA 6.2.17 This method must be defined for all bus masters
- on arm64 -- there are no assumptions made about
+ on arm64 - there are no assumptions made about
whether such devices are cache coherent or not.
The _CCA value is inherited by all descendants of
these devices so it does not need to be repeated.
@@ -422,8 +536,8 @@ _OSC 6.2.11 This method can be a global method in ACPI (i.e.,
by the kernel community, then register it with the
UEFI Forum.
-\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is
- concerned, _OSI is not to be used to determine what
+\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is
+ concerned, _OSI is not to be used to determine what
sort of system is being used or what functionality
is provided. The _OSC method is to be used instead.
@@ -447,7 +561,7 @@ _PSx 7.3.2-5 Use as needed; power management specific. If _PS0 is
usage, change them in these methods.
_RDI 8.4.4.4 Recommended for use with processor definitions (_HID
- ACPI0010) on arm64. This should only be used in
+ ACPI0010) on arm64. This should only be used in
conjunction with _LPI.
\_REV 5.7.4 Always returns the latest version of ACPI supported.
@@ -476,6 +590,7 @@ _SWS 7.4.3 Use as needed; power management specific; this may
_UID 6.1.12 Recommended for distinguishing devices of the same
class; define it if at all possible.
+===== ================ ========================================================
@@ -488,7 +603,7 @@ platforms, ACPI events must be signaled differently.
There are two options: GPIO-signaled interrupts (Section 5.6.5), and
interrupt-signaled events (Section 5.6.9). Interrupt-signaled events are a
-new feature in the ACPI 6.1 specification. Either -- or both -- can be used
+new feature in the ACPI 6.1 specification. Either - or both - can be used
on a given platform, and which to use may be dependent of limitations in any
given SoC. If possible, interrupt-signaled events are recommended.
@@ -564,39 +679,40 @@ supported.
The following classes of objects are not supported:
- -- Section 9.2: ambient light sensor devices
+ - Section 9.2: ambient light sensor devices
- -- Section 9.3: battery devices
+ - Section 9.3: battery devices
- -- Section 9.4: lids (e.g., laptop lids)
+ - Section 9.4: lids (e.g., laptop lids)
- -- Section 9.8.2: IDE controllers
+ - Section 9.8.2: IDE controllers
- -- Section 9.9: floppy controllers
+ - Section 9.9: floppy controllers
- -- Section 9.10: GPE block devices
+ - Section 9.10: GPE block devices
- -- Section 9.15: PC/AT RTC/CMOS devices
+ - Section 9.15: PC/AT RTC/CMOS devices
- -- Section 9.16: user presence detection devices
+ - Section 9.16: user presence detection devices
- -- Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
+ - Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
- -- Section 9.18: time and alarm devices (see 9.15)
+ - Section 9.18: time and alarm devices (see 9.15)
- -- Section 10: power source and power meter devices
+ - Section 10: power source and power meter devices
- -- Section 11: thermal management
+ - Section 11: thermal management
- -- Section 12: embedded controllers interface
+ - Section 12: embedded controllers interface
- -- Section 13: SMBus interfaces
+ - Section 13: SMBus interfaces
This also means that there is no support for the following objects:
+==== =========================== ==== ==========
Name Section Name Section
----- ------------ ---- ------------
+==== =========================== ==== ==========
_ALC 9.3.4 _FDM 9.10.3
_ALI 9.3.2 _FIX 6.2.7
_ALP 9.3.6 _GAI 10.4.5
@@ -619,4 +735,4 @@ _DCK 6.5.2 _UPD 9.16.1
_EC 12.12 _UPP 9.16.2
_FDE 9.10.1 _WPC 10.5.2
_FDI 9.10.2 _WPP 10.5.3
-
+==== =========================== ==== ==========
diff --git a/Documentation/arm64/arm-acpi.txt b/Documentation/arm64/arm-acpi.rst
similarity index 86%
rename from Documentation/arm64/arm-acpi.txt
rename to Documentation/arm64/arm-acpi.rst
index 1a74a041a443..872dbbc73d4a 100644
--- a/Documentation/arm64/arm-acpi.txt
+++ b/Documentation/arm64/arm-acpi.rst
@@ -1,5 +1,7 @@
+=====================
ACPI on ARMv8 Servers
----------------------
+=====================
+
ACPI can be used for ARMv8 general purpose servers designed to follow
the ARM SBSA (Server Base System Architecture) [0] and SBBR (Server
Base Boot Requirements) [1] specifications. Please note that the SBBR
@@ -34,28 +36,28 @@ of the summary text almost directly, to be honest.
The short form of the rationale for ACPI on ARM is:
--- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
+- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
while DT explicitly does not support this. For hardware vendors, being
able to encode behavior is a key tool used in supporting operating
system releases on new hardware.
--- ACPI’s OSPM defines a power management model that constrains what the
+- ACPI’s OSPM defines a power management model that constrains what the
platform is allowed to do into a specific model, while still providing
flexibility in hardware design.
--- In the enterprise server environment, ACPI has established bindings (such
+- In the enterprise server environment, ACPI has established bindings (such
as for RAS) which are currently used in production systems. DT does not.
Such bindings could be defined in DT at some point, but doing so means ARM
and x86 would end up using completely different code paths in both firmware
and the kernel.
--- Choosing a single interface to describe the abstraction between a platform
+- Choosing a single interface to describe the abstraction between a platform
and an OS is important. Hardware vendors would not be required to implement
both DT and ACPI if they want to support multiple operating systems. And,
agreeing on a single interface instead of being fragmented into per OS
interfaces makes for better interoperability overall.
--- The new ACPI governance process works well and Linux is now at the same
+- The new ACPI governance process works well and Linux is now at the same
table as hardware vendors and other OS vendors. In fact, there is no
longer any reason to feel that ACPI only belongs to Windows or that
Linux is in any way secondary to Microsoft in this arena. The move of
@@ -169,31 +171,31 @@ For the ACPI core to operate properly, and in turn provide the information
the kernel needs to configure devices, it expects to find the following
tables (all section numbers refer to the ACPI 6.1 specification):
- -- RSDP (Root System Description Pointer), section 5.2.5
+ - RSDP (Root System Description Pointer), section 5.2.5
- -- XSDT (eXtended System Description Table), section 5.2.8
+ - XSDT (eXtended System Description Table), section 5.2.8
- -- FADT (Fixed ACPI Description Table), section 5.2.9
+ - FADT (Fixed ACPI Description Table), section 5.2.9
- -- DSDT (Differentiated System Description Table), section
+ - DSDT (Differentiated System Description Table), section
5.2.11.1
- -- MADT (Multiple APIC Description Table), section 5.2.12
+ - MADT (Multiple APIC Description Table), section 5.2.12
- -- GTDT (Generic Timer Description Table), section 5.2.24
+ - GTDT (Generic Timer Description Table), section 5.2.24
- -- If PCI is supported, the MCFG (Memory mapped ConFiGuration
+ - If PCI is supported, the MCFG (Memory mapped ConFiGuration
Table), section 5.2.6, specifically Table 5-31.
- -- If booting without a console=<device> kernel parameter is
+ - If booting without a console=<device> kernel parameter is
supported, the SPCR (Serial Port Console Redirection table),
section 5.2.6, specifically Table 5-31.
- -- If necessary to describe the I/O topology, SMMUs and GIC ITSs,
+ - If necessary to describe the I/O topology, SMMUs and GIC ITSs,
the IORT (Input Output Remapping Table, section 5.2.6, specifically
Table 5-31).
- -- If NUMA is supported, the SRAT (System Resource Affinity Table)
+ - If NUMA is supported, the SRAT (System Resource Affinity Table)
and SLIT (System Locality distance Information Table), sections
5.2.16 and 5.2.17, respectively.
@@ -269,9 +271,9 @@ describes how to define the structure of an object returned via _DSD, and
how specific data structures are defined by specific UUIDs. Linux should
only use the _DSD Device Properties UUID [5]:
- -- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
+ - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
- -- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+ - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
The UEFI Forum provides a mechanism for registering device properties [4]
so that they may be used across all operating systems supporting ACPI.
@@ -327,10 +329,10 @@ turning a device full off.
There are two options for using those Power Resources. They can:
- -- be managed in a _PSx method which gets called on entry to power
+ - be managed in a _PSx method which gets called on entry to power
state Dx.
- -- be declared separately as power resources with their own _ON and _OFF
+ - be declared separately as power resources with their own _ON and _OFF
methods. They are then tied back to D-states for a particular device
via _PRx which specifies which power resources a device needs to be on
while in Dx. Kernel then tracks number of devices using a power resource
@@ -339,16 +341,16 @@ There are two options for using those Power Resources. They can:
The kernel ACPI code will also assume that the _PSx methods follow the normal
ACPI rules for such methods:
- -- If either _PS0 or _PS3 is implemented, then the other method must also
+ - If either _PS0 or _PS3 is implemented, then the other method must also
be implemented.
- -- If a device requires usage or setup of a power resource when on, the ASL
+ - If a device requires usage or setup of a power resource when on, the ASL
should organize that it is allocated/enabled using the _PS0 method.
- -- Resources allocated or enabled in the _PS0 method should be disabled
+ - Resources allocated or enabled in the _PS0 method should be disabled
or de-allocated in the _PS3 method.
- -- Firmware will leave the resources in a reasonable state before handing
+ - Firmware will leave the resources in a reasonable state before handing
over control to the kernel.
Such code in _PSx methods will of course be very platform specific. But,
@@ -394,52 +396,52 @@ else must be discovered by the driver probe function. Then, have the rest
of the driver operate off of the contents of that struct. Doing so should
allow most divergence between ACPI and DT functionality to be kept local to
the probe function instead of being scattered throughout the driver. For
-example:
+example::
-static int device_probe_dt(struct platform_device *pdev)
-{
- /* DT specific functionality */
- ...
-}
+ static int device_probe_dt(struct platform_device *pdev)
+ {
+ /* DT specific functionality */
+ ...
+ }
-static int device_probe_acpi(struct platform_device *pdev)
-{
- /* ACPI specific functionality */
- ...
-}
+ static int device_probe_acpi(struct platform_device *pdev)
+ {
+ /* ACPI specific functionality */
+ ...
+ }
-static int device_probe(struct platform_device *pdev)
-{
- ...
- struct device_node node = pdev->dev.of_node;
- ...
+ static int device_probe(struct platform_device *pdev)
+ {
+ ...
+ struct device_node node = pdev->dev.of_node;
+ ...
- if (node)
- ret = device_probe_dt(pdev);
- else if (ACPI_HANDLE(&pdev->dev))
- ret = device_probe_acpi(pdev);
- else
- /* other initialization */
- ...
- /* Continue with any generic probe operations */
- ...
-}
+ if (node)
+ ret = device_probe_dt(pdev);
+ else if (ACPI_HANDLE(&pdev->dev))
+ ret = device_probe_acpi(pdev);
+ else
+ /* other initialization */
+ ...
+ /* Continue with any generic probe operations */
+ ...
+ }
DO keep the MODULE_DEVICE_TABLE entries together in the driver to make it
clear the different names the driver is probed for, both from DT and from
-ACPI:
+ACPI::
-static struct of_device_id virtio_mmio_match[] = {
- { .compatible = "virtio,mmio", },
- { }
-};
-MODULE_DEVICE_TABLE(of, virtio_mmio_match);
+ static struct of_device_id virtio_mmio_match[] = {
+ { .compatible = "virtio,mmio", },
+ { }
+ };
+ MODULE_DEVICE_TABLE(of, virtio_mmio_match);
-static const struct acpi_device_id virtio_mmio_acpi_match[] = {
- { "LNRO0005", },
- { }
-};
-MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
+ static const struct acpi_device_id virtio_mmio_acpi_match[] = {
+ { "LNRO0005", },
+ { }
+ };
+ MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
ASWG
@@ -471,7 +473,8 @@ Linux Code
Individual items specific to Linux on ARM, contained in the the Linux
source code, are in the list that follows:
-ACPI_OS_NAME This macro defines the string to be returned when
+ACPI_OS_NAME
+ This macro defines the string to be returned when
an ACPI method invokes the _OS method. On ARM64
systems, this macro will be "Linux" by default.
The command line parameter acpi_os=<string>
@@ -482,38 +485,44 @@ ACPI_OS_NAME This macro defines the string to be returned when
ACPI Objects
------------
Detailed expectations for ACPI tables and object are listed in the file
-Documentation/arm64/acpi_object_usage.txt.
+Documentation/arm64/acpi_object_usage.rst.
References
----------
-[0] http://silver.arm.com -- document ARM-DEN-0029, or newer
+[0] http://silver.arm.com
+ document ARM-DEN-0029, or newer:
"Server Base System Architecture", version 2.3, dated 27 Mar 2014
[1] http://infocenter.arm.com/help/topic/com.arm.doc.den0044a/Server_Base_Boot_Requirements.pdf
Document ARM-DEN-0044A, or newer: "Server Base Boot Requirements, System
Software on ARM Platforms", dated 16 Aug 2014
-[2] http://www.secretlab.ca/archives/151, 10 Jan 2015, Copyright (c) 2015,
+[2] http://www.secretlab.ca/archives/151,
+ 10 Jan 2015, Copyright (c) 2015,
Linaro Ltd., written by Grant Likely.
-[3] AMD ACPI for Seattle platform documentation:
+[3] AMD ACPI for Seattle platform documentation
http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf
-[4] http://www.uefi.org/acpi -- please see the link for the "ACPI _DSD Device
+
+[4] http://www.uefi.org/acpi
+ please see the link for the "ACPI _DSD Device
Property Registry Instructions"
-[5] http://www.uefi.org/acpi -- please see the link for the "_DSD (Device
+[5] http://www.uefi.org/acpi
+ please see the link for the "_DSD (Device
Specific Data) Implementation Guide"
-[6] Kernel code for the unified device property interface can be found in
+[6] Kernel code for the unified device
+ property interface can be found in
include/linux/property.h and drivers/base/property.c.
Authors
-------
-Al Stone <al.stone@linaro.org>
-Graeme Gregory <graeme.gregory@linaro.org>
-Hanjun Guo <hanjun.guo@linaro.org>
+- Al Stone <al.stone@linaro.org>
+- Graeme Gregory <graeme.gregory@linaro.org>
+- Hanjun Guo <hanjun.guo@linaro.org>
-Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
+- Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
diff --git a/Documentation/arm64/booting.txt b/Documentation/arm64/booting.rst
similarity index 86%
rename from Documentation/arm64/booting.txt
rename to Documentation/arm64/booting.rst
index fbab7e21d116..3d041d0d16e8 100644
--- a/Documentation/arm64/booting.txt
+++ b/Documentation/arm64/booting.rst
@@ -1,7 +1,9 @@
- Booting AArch64 Linux
- =====================
+=====================
+Booting AArch64 Linux
+=====================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 07 September 2012
This document is based on the ARM booting document by Russell King and
@@ -12,7 +14,7 @@ The AArch64 exception model is made up of a number of exception levels
counterpart. EL2 is the hypervisor level and exists only in non-secure
mode. EL3 is the highest priority level and exists only in secure mode.
-For the purposes of this document, we will use the term `boot loader'
+For the purposes of this document, we will use the term `boot loader`
simply to define all software that executes on the CPU(s) before control
is passed to the Linux kernel. This may include secure monitor and
hypervisor code, or it may just be a handful of instructions for
@@ -70,7 +72,7 @@ Image target is available instead.
Requirement: MANDATORY
-The decompressed kernel image contains a 64-byte header as follows:
+The decompressed kernel image contains a 64-byte header as follows::
u32 code0; /* Executable code */
u32 code1; /* Executable code */
@@ -103,19 +105,26 @@ Header notes:
- The flags field (introduced in v3.17) is a little-endian 64-bit field
composed as follows:
- Bit 0: Kernel endianness. 1 if BE, 0 if LE.
- Bit 1-2: Kernel Page size.
- 0 - Unspecified.
- 1 - 4K
- 2 - 16K
- 3 - 64K
- Bit 3: Kernel physical placement
- 0 - 2MB aligned base should be as close as possible
- to the base of DRAM, since memory below it is not
- accessible via the linear mapping
- 1 - 2MB aligned base may be anywhere in physical
- memory
- Bits 4-63: Reserved.
+
+ ============= ===============================================================
+ Bit 0 Kernel endianness. 1 if BE, 0 if LE.
+ Bit 1-2 Kernel Page size.
+
+ * 0 - Unspecified.
+ * 1 - 4K
+ * 2 - 16K
+ * 3 - 64K
+ Bit 3 Kernel physical placement
+
+ 0
+ 2MB aligned base should be as close as possible
+ to the base of DRAM, since memory below it is not
+ accessible via the linear mapping
+ 1
+ 2MB aligned base may be anywhere in physical
+ memory
+ Bits 4-63 Reserved.
+ ============= ===============================================================
- When image_size is zero, a bootloader should attempt to keep as much
memory as possible free for use by the kernel immediately after the
@@ -147,19 +156,22 @@ Before jumping into the kernel, the following conditions must be met:
corrupted by bogus network packets or disk data. This will save
you many hours of debug.
-- Primary CPU general-purpose register settings
- x0 = physical address of device tree blob (dtb) in system RAM.
- x1 = 0 (reserved for future use)
- x2 = 0 (reserved for future use)
- x3 = 0 (reserved for future use)
+- Primary CPU general-purpose register settings:
+
+ - x0 = physical address of device tree blob (dtb) in system RAM.
+ - x1 = 0 (reserved for future use)
+ - x2 = 0 (reserved for future use)
+ - x3 = 0 (reserved for future use)
- CPU mode
+
All forms of interrupts must be masked in PSTATE.DAIF (Debug, SError,
IRQ and FIQ).
The CPU must be in either EL2 (RECOMMENDED in order to have access to
the virtualisation extensions) or non-secure EL1.
- Caches, MMUs
+
The MMU must be off.
Instruction cache may be on or off.
The address range corresponding to the loaded kernel image must be
@@ -172,18 +184,21 @@ Before jumping into the kernel, the following conditions must be met:
operations (not recommended) must be configured and disabled.
- Architected timers
+
CNTFRQ must be programmed with the timer frequency and CNTVOFF must
be programmed with a consistent value on all CPUs. If entering the
kernel at EL1, CNTHCTL_EL2 must have EL1PCTEN (bit 0) set where
available.
- Coherency
+
All CPUs to be booted by the kernel must be part of the same coherency
domain on entry to the kernel. This may require IMPLEMENTATION DEFINED
initialisation to enable the receiving of maintenance operations on
each CPU.
- System registers
+
All writable architected system registers at the exception level where
the kernel image will be entered must be initialised by software at a
higher exception level to prevent execution in an UNKNOWN state.
@@ -195,28 +210,40 @@ Before jumping into the kernel, the following conditions must be met:
For systems with a GICv3 interrupt controller to be used in v3 mode:
- If EL3 is present:
- ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
- ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
+ - ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1.
+ - ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1.
+
- If the kernel is entered at EL1:
- ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
- ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
+ - ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1
+ - ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1.
+
- The DT or ACPI tables must describe a GICv3 interrupt controller.
For systems with a GICv3 interrupt controller to be used in
compatibility (v2) mode:
+
- If EL3 is present:
- ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
+ ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0.
+
- If the kernel is entered at EL1:
- ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
+ ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0.
+
- The DT or ACPI tables must describe a GICv2 interrupt controller.
For CPUs with pointer authentication functionality:
- If EL3 is present:
- SCR_EL3.APK (bit 16) must be initialised to 0b1
- SCR_EL3.API (bit 17) must be initialised to 0b1
+
+ - SCR_EL3.APK (bit 16) must be initialised to 0b1
+ - SCR_EL3.API (bit 17) must be initialised to 0b1
+
- If the kernel is entered at EL1:
- HCR_EL2.APK (bit 40) must be initialised to 0b1
- HCR_EL2.API (bit 41) must be initialised to 0b1
+
+ - HCR_EL2.APK (bit 40) must be initialised to 0b1
+ - HCR_EL2.API (bit 41) must be initialised to 0b1
The requirements described above for CPU mode, caches, MMUs, architected
timers, coherency and system registers apply to all CPUs. All CPUs must
diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.rst
similarity index 65%
rename from Documentation/arm64/cpu-feature-registers.txt
rename to Documentation/arm64/cpu-feature-registers.rst
index 684a0da39378..2955287e9acc 100644
--- a/Documentation/arm64/cpu-feature-registers.txt
+++ b/Documentation/arm64/cpu-feature-registers.rst
@@ -1,5 +1,6 @@
- ARM64 CPU Feature Registers
- ===========================
+===========================
+ARM64 CPU Feature Registers
+===========================
Author: Suzuki K Poulose <suzuki.poulose@arm.com>
@@ -9,7 +10,7 @@ registers to userspace. The availability of this ABI is advertised
via the HWCAP_CPUID in HWCAPs.
1. Motivation
----------------
+-------------
The ARM architecture defines a set of feature registers, which describe
the capabilities of the CPU/system. Access to these system registers is
@@ -33,9 +34,10 @@ there are some issues with their usage.
2. Requirements
------------------
+---------------
+
+ a) Safety:
- a) Safety :
Applications should be able to use the information provided by the
infrastructure to run safely across the system. This has greater
implications on a system with heterogeneous CPUs.
@@ -47,7 +49,8 @@ there are some issues with their usage.
Otherwise an application could crash when scheduled on the CPU
which doesn't support CRC32.
- b) Security :
+ b) Security:
+
Applications should only be able to receive information that is
relevant to the normal operation in userspace. Hence, some of the
fields are masked out(i.e, made invisible) and their values are set to
@@ -58,10 +61,12 @@ there are some issues with their usage.
(even when the CPU provides it).
c) Implementation Defined Features
+
The infrastructure doesn't expose any register which is
IMPLEMENTATION DEFINED as per ARMv8-A Architecture.
- d) CPU Identification :
+ d) CPU Identification:
+
MIDR_EL1 is exposed to help identify the processor. On a
heterogeneous system, this could be racy (just like getcpu()). The
process could be migrated to another CPU by the time it uses the
@@ -70,7 +75,7 @@ there are some issues with their usage.
currently executing on. The REVIDR is not exposed due to this
constraint, as REVIDR makes sense only in conjunction with the
MIDR. Alternately, MIDR_EL1 and REVIDR_EL1 are exposed via sysfs
- at:
+ at::
/sys/devices/system/cpu/cpu$ID/regs/identification/
\- midr
@@ -85,7 +90,8 @@ exception and ends up in SIGILL being delivered to the process.
The infrastructure hooks into the exception handler and emulates the
operation if the source belongs to the supported system register space.
-The infrastructure emulates only the following system register space:
+The infrastructure emulates only the following system register space::
+
Op0=3, Op1=0, CRn=0, CRm=0,4,5,6,7
(See Table C5-6 'System instruction encodings for non-Debug System
@@ -107,73 +113,76 @@ infrastructure:
-------------------------------------------
1) ID_AA64ISAR0_EL1 - Instruction Set Attribute Register 0
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| TS | [55-52] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FHM | [51-48] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DP | [47-44] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM4 | [43-40] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM3 | [39-36] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA3 | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| RDM | [31-28] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| ATOMICS | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| CRC32 | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA2 | [15-12] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA1 | [11-8] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AES | [7-4] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
2) ID_AA64PFR0_EL1 - Processor Feature Register 0
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DIT | [51-48] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SVE | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GIC | [27-24] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AdvSIMD | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FP | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL3 | [15-12] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL2 | [11-8] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL1 | [7-4] | n |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| EL0 | [3-0] | n |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
3) MIDR_EL1 - Main ID Register
- x--------------------------------------------------x
+
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Implementer | [31-24] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Variant | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Architecture | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| PartNum | [15-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| Revision | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
NOTE: The 'visible' fields of MIDR_EL1 will contain the value
as available on the CPU where it is fetched and is not a system
@@ -181,90 +190,92 @@ infrastructure:
4) ID_AA64ISAR1_EL1 - Instruction set attribute register 1
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GPI | [31-28] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| GPA | [27-24] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| LRCPC | [23-20] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| FCMA | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| JSCVT | [15-12] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| API | [11-8] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| APA | [7-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| DPB | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
5) ID_AA64MMFR2_EL1 - Memory model feature register 2
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AT | [35-32] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
6) ID_AA64ZFR0_EL1 - SVE feature ID register 0
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
| Name | bits | visible |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SM4 | [43-40] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SHA3 | [35-32] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| BitPerm | [19-16] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| AES | [7-4] | y |
- |--------------------------------------------------|
+ +------------------------------+---------+---------+
| SVEVer | [3-0] | y |
- x--------------------------------------------------x
+ +------------------------------+---------+---------+
Appendix I: Example
----------------------------
+-------------------
-/*
- * Sample program to demonstrate the MRS emulation ABI.
- *
- * Copyright (C) 2015-2016, ARM Ltd
- *
- * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- */
+::
-#include <asm/hwcap.h>
-#include <stdio.h>
-#include <sys/auxv.h>
+ /*
+ * Sample program to demonstrate the MRS emulation ABI.
+ *
+ * Copyright (C) 2015-2016, ARM Ltd
+ *
+ * Author: Suzuki K Poulose <suzuki.poulose@arm.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ */
-#define get_cpu_ftr(id) ({ \
+ #include <asm/hwcap.h>
+ #include <stdio.h>
+ #include <sys/auxv.h>
+
+ #define get_cpu_ftr(id) ({ \
unsigned long __val; \
asm("mrs %0, "#id : "=r" (__val)); \
printf("%-20s: 0x%016lx\n", #id, __val); \
})
-int main(void)
-{
+ int main(void)
+ {
if (!(getauxval(AT_HWCAP) & HWCAP_CPUID)) {
fputs("CPUID registers unavailable\n", stderr);
@@ -284,13 +295,10 @@ int main(void)
get_cpu_ftr(MPIDR_EL1);
get_cpu_ftr(REVIDR_EL1);
-#if 0
+ #if 0
/* Unexposed register access causes SIGILL */
get_cpu_ftr(ID_MMFR0_EL1);
-#endif
+ #endif
return 0;
-}
-
-
-
+ }
diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.rst
similarity index 92%
rename from Documentation/arm64/elf_hwcaps.txt
rename to Documentation/arm64/elf_hwcaps.rst
index b73a2519ecf2..c7cbf4b571c0 100644
--- a/Documentation/arm64/elf_hwcaps.txt
+++ b/Documentation/arm64/elf_hwcaps.rst
@@ -1,3 +1,4 @@
+================
ARM64 ELF hwcaps
================
@@ -15,16 +16,16 @@ of flags called hwcaps, exposed in the auxilliary vector.
Userspace software can test for features by acquiring the AT_HWCAP or
AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
-flags are set, e.g.
+flags are set, e.g.::
-bool floating_point_is_present(void)
-{
- unsigned long hwcaps = getauxval(AT_HWCAP);
- if (hwcaps & HWCAP_FP)
- return true;
+ bool floating_point_is_present(void)
+ {
+ unsigned long hwcaps = getauxval(AT_HWCAP);
+ if (hwcaps & HWCAP_FP)
+ return true;
- return false;
-}
+ return false;
+ }
Where software relies on a feature described by a hwcap, it should check
the relevant hwcap flag to verify that the feature is present before
@@ -45,7 +46,7 @@ userspace code at EL0. These hwcaps are defined in terms of ID register
fields, and should be interpreted with reference to the definition of
these fields in the ARM Architecture Reference Manual (ARM ARM).
-Such hwcaps are described below in the form:
+Such hwcaps are described below in the form::
Functionality implied by idreg.field == val.
@@ -64,75 +65,58 @@ reference to ID registers, and may refer to other documentation.
---------------------------------
HWCAP_FP
-
Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
HWCAP_ASIMD
-
Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
HWCAP_EVTSTRM
-
The generic timer is configured to generate events at a frequency of
approximately 100KHz.
HWCAP_AES
-
Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
HWCAP_PMULL
-
Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
HWCAP_SHA1
-
Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
HWCAP_SHA2
-
Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
HWCAP_CRC32
-
Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
HWCAP_ATOMICS
-
Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
HWCAP_FPHP
-
Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
HWCAP_ASIMDHP
-
Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
HWCAP_CPUID
-
EL0 access to certain ID registers is available, to the extent
- described by Documentation/arm64/cpu-feature-registers.txt.
+ described by Documentation/arm64/cpu-feature-registers.rst.
These ID registers may imply the availability of features.
HWCAP_ASIMDRDM
-
Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
HWCAP_JSCVT
-
Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
HWCAP_FCMA
-
Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
HWCAP_LRCPC
-
Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
HWCAP_DCPOP
-
Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
HWCAP2_DCPODP
@@ -140,27 +124,21 @@ HWCAP2_DCPODP
Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
HWCAP_SHA3
-
Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
HWCAP_SM3
-
Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
HWCAP_SM4
-
Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
HWCAP_ASIMDDP
-
Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
HWCAP_SHA512
-
Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
HWCAP_SVE
-
Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
HWCAP2_SVE2
@@ -188,40 +166,32 @@ HWCAP2_SVESM4
Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
HWCAP_ASIMDFHM
-
Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
HWCAP_DIT
-
Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
HWCAP_USCAT
-
Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
HWCAP_ILRCPC
-
Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
HWCAP_FLAGM
-
Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
HWCAP_SSBS
-
Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
HWCAP_PACA
-
Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
ID_AA64ISAR1_EL1.API == 0b0001, as described by
- Documentation/arm64/pointer-authentication.txt.
+ Documentation/arm64/pointer-authentication.rst.
HWCAP_PACG
-
Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
- Documentation/arm64/pointer-authentication.txt.
+ Documentation/arm64/pointer-authentication.rst.
4. Unused AT_HWCAP bits
diff --git a/Documentation/arm64/hugetlbpage.txt b/Documentation/arm64/hugetlbpage.rst
similarity index 86%
rename from Documentation/arm64/hugetlbpage.txt
rename to Documentation/arm64/hugetlbpage.rst
index cfae87dc653b..b44f939e5210 100644
--- a/Documentation/arm64/hugetlbpage.txt
+++ b/Documentation/arm64/hugetlbpage.rst
@@ -1,3 +1,4 @@
+====================
HugeTLBpage on ARM64
====================
@@ -31,8 +32,10 @@ and level of the page table.
The following hugepage sizes are supported -
- CONT PTE PMD CONT PMD PUD
- -------- --- -------- ---
+ ====== ======== ==== ======== ===
+ - CONT PTE PMD CONT PMD PUD
+ ====== ======== ==== ======== ===
4K: 64K 2M 32M 1G
16K: 2M 32M 1G
64K: 2M 512M 16G
+ ====== ======== ==== ======== ===
diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst
new file mode 100644
index 000000000000..018b7836ecb7
--- /dev/null
+++ b/Documentation/arm64/index.rst
@@ -0,0 +1,28 @@
+:orphan:
+
+==================
+ARM64 Architecture
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ acpi_object_usage
+ arm-acpi
+ booting
+ cpu-feature-registers
+ elf_hwcaps
+ hugetlbpage
+ legacy_instructions
+ memory
+ pointer-authentication
+ silicon-errata
+ sve
+ tagged-pointers
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/arm64/legacy_instructions.txt b/Documentation/arm64/legacy_instructions.rst
similarity index 73%
rename from Documentation/arm64/legacy_instructions.txt
rename to Documentation/arm64/legacy_instructions.rst
index 01bf3d9fac85..54401b22cb8f 100644
--- a/Documentation/arm64/legacy_instructions.txt
+++ b/Documentation/arm64/legacy_instructions.rst
@@ -1,3 +1,7 @@
+===================
+Legacy instructions
+===================
+
The arm64 port of the Linux kernel provides infrastructure to support
emulation of instructions which have been deprecated, or obsoleted in
the architecture. The infrastructure code uses undefined instruction
@@ -9,19 +13,22 @@ The emulation mode can be controlled by writing to sysctl nodes
behaviours and the corresponding values of the sysctl nodes -
* Undef
- Value: 0
+ Value: 0
+
Generates undefined instruction abort. Default for instructions that
have been obsoleted in the architecture, e.g., SWP
* Emulate
- Value: 1
+ Value: 1
+
Uses software emulation. To aid migration of software, in this mode
usage of emulated instruction is traced as well as rate limited
warnings are issued. This is the default for deprecated
instructions, .e.g., CP15 barriers
* Hardware Execution
- Value: 2
+ Value: 2
+
Although marked as deprecated, some implementations may support the
enabling/disabling of hardware support for the execution of these
instructions. Using hardware execution generally provides better
@@ -38,20 +45,24 @@ individual instruction notes for further information.
Supported legacy instructions
-----------------------------
* SWP{B}
-Node: /proc/sys/abi/swp
-Status: Obsolete
-Default: Undef (0)
+
+:Node: /proc/sys/abi/swp
+:Status: Obsolete
+:Default: Undef (0)
* CP15 Barriers
-Node: /proc/sys/abi/cp15_barrier
-Status: Deprecated
-Default: Emulate (1)
+
+:Node: /proc/sys/abi/cp15_barrier
+:Status: Deprecated
+:Default: Emulate (1)
* SETEND
-Node: /proc/sys/abi/setend
-Status: Deprecated
-Default: Emulate (1)*
-Note: All the cpus on the system must have mixed endian support at EL0
-for this feature to be enabled. If a new CPU - which doesn't support mixed
-endian - is hotplugged in after this feature has been enabled, there could
-be unexpected results in the application.
+
+:Node: /proc/sys/abi/setend
+:Status: Deprecated
+:Default: Emulate (1)*
+
+ Note: All the cpus on the system must have mixed endian support at EL0
+ for this feature to be enabled. If a new CPU - which doesn't support mixed
+ endian - is hotplugged in after this feature has been enabled, there could
+ be unexpected results in the application.
diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst
new file mode 100644
index 000000000000..464b880fc4b7
--- /dev/null
+++ b/Documentation/arm64/memory.rst
@@ -0,0 +1,98 @@
+==============================
+Memory Layout on AArch64 Linux
+==============================
+
+Author: Catalin Marinas <catalin.marinas@arm.com>
+
+This document describes the virtual memory layout used by the AArch64
+Linux kernel. The architecture allows up to 4 levels of translation
+tables with a 4KB page size and up to 3 levels with a 64KB page size.
+
+AArch64 Linux uses either 3 levels or 4 levels of translation tables
+with the 4KB page configuration, allowing 39-bit (512GB) or 48-bit
+(256TB) virtual addresses, respectively, for both user and kernel. With
+64KB pages, only 2 levels of translation tables, allowing 42-bit (4TB)
+virtual address, are used but the memory layout is the same.
+
+User addresses have bits 63:48 set to 0 while the kernel addresses have
+the same bits set to 1. TTBRx selection is given by bit 63 of the
+virtual address. The swapper_pg_dir contains only kernel (global)
+mappings while the user pgd contains only user (non-global) mappings.
+The swapper_pg_dir address is written to TTBR1 and never written to
+TTBR0.
+
+
+AArch64 Linux memory layout with 4KB pages + 3 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000007fffffffff 512GB user
+ ffffff8000000000 ffffffffffffffff 512GB kernel
+
+
+AArch64 Linux memory layout with 4KB pages + 4 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000ffffffffffff 256TB user
+ ffff000000000000 ffffffffffffffff 256TB kernel
+
+
+AArch64 Linux memory layout with 64KB pages + 2 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 000003ffffffffff 4TB user
+ fffffc0000000000 ffffffffffffffff 4TB kernel
+
+
+AArch64 Linux memory layout with 64KB pages + 3 levels::
+
+ Start End Size Use
+ -----------------------------------------------------------------------
+ 0000000000000000 0000ffffffffffff 256TB user
+ ffff000000000000 ffffffffffffffff 256TB kernel
+
+
+For details of the virtual kernel memory layout please see the kernel
+booting log.
+
+
+Translation table lookup with 4KB pages::
+
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ | | | | | |
+ | | | | | v
+ | | | | | [11:0] in-page offset
+ | | | | +-> [20:12] L3 index
+ | | | +-----------> [29:21] L2 index
+ | | +---------------------> [38:30] L1 index
+ | +-------------------------------> [47:39] L0 index
+ +-------------------------------------------------> [63] TTBR0/1
+
+
+Translation table lookup with 64KB pages::
+
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
+ +--------+--------+--------+--------+--------+--------+--------+--------+
+ | | | | |
+ | | | | v
+ | | | | [15:0] in-page offset
+ | | | +----------> [28:16] L3 index
+ | | +--------------------------> [41:29] L2 index
+ | +-------------------------------> [47:42] L1 index
+ +-------------------------------------------------> [63] TTBR0/1
+
+
+When using KVM without the Virtualization Host Extensions, the
+hypervisor maps kernel pages in EL2 at a fixed (and potentially
+random) offset from the linear mapping. See the kern_hyp_va macro and
+kvm_update_va_mask function for more details. MMIO devices such as
+GICv2 gets mapped next to the HYP idmap page, as do vectors when
+ARM64_HARDEN_EL2_VECTORS is selected for particular CPUs.
+
+When using KVM with the Virtualization Host Extensions, no additional
+mappings are created, since the host kernel runs directly in EL2.
diff --git a/Documentation/arm64/memory.txt b/Documentation/arm64/memory.txt
deleted file mode 100644
index c5dab30d3389..000000000000
--- a/Documentation/arm64/memory.txt
+++ /dev/null
@@ -1,97 +0,0 @@
- Memory Layout on AArch64 Linux
- ==============================
-
-Author: Catalin Marinas <catalin.marinas@arm.com>
-
-This document describes the virtual memory layout used by the AArch64
-Linux kernel. The architecture allows up to 4 levels of translation
-tables with a 4KB page size and up to 3 levels with a 64KB page size.
-
-AArch64 Linux uses either 3 levels or 4 levels of translation tables
-with the 4KB page configuration, allowing 39-bit (512GB) or 48-bit
-(256TB) virtual addresses, respectively, for both user and kernel. With
-64KB pages, only 2 levels of translation tables, allowing 42-bit (4TB)
-virtual address, are used but the memory layout is the same.
-
-User addresses have bits 63:48 set to 0 while the kernel addresses have
-the same bits set to 1. TTBRx selection is given by bit 63 of the
-virtual address. The swapper_pg_dir contains only kernel (global)
-mappings while the user pgd contains only user (non-global) mappings.
-The swapper_pg_dir address is written to TTBR1 and never written to
-TTBR0.
-
-
-AArch64 Linux memory layout with 4KB pages + 3 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000007fffffffff 512GB user
-ffffff8000000000 ffffffffffffffff 512GB kernel
-
-
-AArch64 Linux memory layout with 4KB pages + 4 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
-
-
-AArch64 Linux memory layout with 64KB pages + 2 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 000003ffffffffff 4TB user
-fffffc0000000000 ffffffffffffffff 4TB kernel
-
-
-AArch64 Linux memory layout with 64KB pages + 3 levels:
-
-Start End Size Use
------------------------------------------------------------------------
-0000000000000000 0000ffffffffffff 256TB user
-ffff000000000000 ffffffffffffffff 256TB kernel
-
-
-For details of the virtual kernel memory layout please see the kernel
-booting log.
-
-
-Translation table lookup with 4KB pages:
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- | | | | | |
- | | | | | v
- | | | | | [11:0] in-page offset
- | | | | +-> [20:12] L3 index
- | | | +-----------> [29:21] L2 index
- | | +---------------------> [38:30] L1 index
- | +-------------------------------> [47:39] L0 index
- +-------------------------------------------------> [63] TTBR0/1
-
-
-Translation table lookup with 64KB pages:
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- | | | | |
- | | | | v
- | | | | [15:0] in-page offset
- | | | +----------> [28:16] L3 index
- | | +--------------------------> [41:29] L2 index
- | +-------------------------------> [47:42] L1 index
- +-------------------------------------------------> [63] TTBR0/1
-
-
-When using KVM without the Virtualization Host Extensions, the
-hypervisor maps kernel pages in EL2 at a fixed (and potentially
-random) offset from the linear mapping. See the kern_hyp_va macro and
-kvm_update_va_mask function for more details. MMIO devices such as
-GICv2 gets mapped next to the HYP idmap page, as do vectors when
-ARM64_HARDEN_EL2_VECTORS is selected for particular CPUs.
-
-When using KVM with the Virtualization Host Extensions, no additional
-mappings are created, since the host kernel runs directly in EL2.
diff --git a/Documentation/arm64/pointer-authentication.txt b/Documentation/arm64/pointer-authentication.rst
similarity index 99%
rename from Documentation/arm64/pointer-authentication.txt
rename to Documentation/arm64/pointer-authentication.rst
index fc71b33de87e..30b2ab06526b 100644
--- a/Documentation/arm64/pointer-authentication.txt
+++ b/Documentation/arm64/pointer-authentication.rst
@@ -1,7 +1,9 @@
+=======================================
Pointer authentication in AArch64 Linux
=======================================
Author: Mark Rutland <mark.rutland@arm.com>
+
Date: 2017-07-19
This document briefly describes the provision of pointer authentication
diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.rst
similarity index 55%
rename from Documentation/arm64/silicon-errata.txt
rename to Documentation/arm64/silicon-errata.rst
index 2735462d5958..c792774be59e 100644
--- a/Documentation/arm64/silicon-errata.txt
+++ b/Documentation/arm64/silicon-errata.rst
@@ -1,7 +1,9 @@
- Silicon Errata and Software Workarounds
- =======================================
+=======================================
+Silicon Errata and Software Workarounds
+=======================================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 27 November 2015
It is an unfortunate fact of life that hardware is often produced with
@@ -9,11 +11,13 @@ so-called "errata", which can cause it to deviate from the architecture
under specific circumstances. For hardware produced by ARM, these
errata are broadly classified into the following categories:
- Category A: A critical error without a viable workaround.
- Category B: A significant or critical error with an acceptable
+ ========== ========================================================
+ Category A A critical error without a viable workaround.
+ Category B A significant or critical error with an acceptable
workaround.
- Category C: A minor error that is not expected to occur under normal
+ Category C A minor error that is not expected to occur under normal
operation.
+ ========== ========================================================
For more information, consult one of the "Software Developers Errata
Notice" documents available on infocenter.arm.com (registration
@@ -42,47 +46,86 @@ file acts as a registry of software workarounds in the Linux Kernel and
will be updated when new workarounds are committed and backported to
stable kernels.
++----------------+-----------------+-----------------+-----------------------------+
| Implementor | Component | Erratum ID | Kconfig |
-+----------------+-----------------+-----------------+-----------------------------+
++================+=================+=================+=============================+
| Allwinner | A64/R18 | UNKNOWN1 | SUN50I_ERRATUM_UNKNOWN1 |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #852523 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A72 | #853709 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A73 | #858921 | ARM64_ERRATUM_858921 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A55 | #1024718 | ARM64_ERRATUM_1024718 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1188873,1418040| ARM64_ERRATUM_1418040 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1165522 | ARM64_ERRATUM_1165522 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1286807 | ARM64_ERRATUM_1286807 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Cortex-A76 | #1463225 | ARM64_ERRATUM_1463225 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | Neoverse-N1 | #1188873,1418040| ARM64_ERRATUM_1418040 |
++----------------+-----------------+-----------------+-----------------------------+
| ARM | MMU-500 | #841119,826419 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX ITS | #22375,24313 | CAVIUM_ERRATUM_22375 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX ITS | #23144 | CAVIUM_ERRATUM_23144 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX Core | #27456 | CAVIUM_ERRATUM_27456 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX Core | #30115 | CAVIUM_ERRATUM_30115 |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX SMMUv2 | #27704 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX2 SMMUv3| #74 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Cavium | ThunderX2 SMMUv3| #126 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip0{5,6,7} | #161010101 | HISILICON_ERRATUM_161010101 |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip0{6,7} | #161010701 | N/A |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip07 | #161600802 | HISILICON_ERRATUM_161600802 |
++----------------+-----------------+-----------------+-----------------------------+
| Hisilicon | Hip08 SMMU PMCG | #162001800 | N/A |
-| | | | |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Kryo/Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Falkor v1 | E1009 | QCOM_FALKOR_ERRATUM_1009 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | QDF2400 ITS | E0065 | QCOM_QDF2400_ERRATUM_0065 |
++----------------+-----------------+-----------------+-----------------------------+
| Qualcomm Tech. | Falkor v{1,2} | E1041 | QCOM_FALKOR_ERRATUM_1041 |
++----------------+-----------------+-----------------+-----------------------------+
++----------------+-----------------+-----------------+-----------------------------+
| Fujitsu | A64FX | E#010001 | FUJITSU_ERRATUM_010001 |
++----------------+-----------------+-----------------+-----------------------------+
diff --git a/Documentation/arm64/sve.txt b/Documentation/arm64/sve.rst
similarity index 98%
rename from Documentation/arm64/sve.txt
rename to Documentation/arm64/sve.rst
index 9940e924a47e..38422ab249dd 100644
--- a/Documentation/arm64/sve.txt
+++ b/Documentation/arm64/sve.rst
@@ -1,7 +1,9 @@
- Scalable Vector Extension support for AArch64 Linux
- ===================================================
+===================================================
+Scalable Vector Extension support for AArch64 Linux
+===================================================
Author: Dave Martin <Dave.Martin@arm.com>
+
Date: 4 August 2017
This document outlines briefly the interface provided to userspace by Linux in
@@ -426,7 +428,7 @@ In A64 state, SVE adds the following:
* FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point
operations in a similar way to the way in which they interact with ARMv8
- floating-point operations.
+ floating-point operations::
8VL-1 128 0 bit index
+---- //// -----------------+
@@ -483,6 +485,8 @@ ARMv8-A defines the following floating-point / SIMD register state:
* 32 128-bit vector registers V0..V31
* 2 32-bit status/control registers FPSR, FPCR
+::
+
127 0 bit index
+---------------+
V0 | |
@@ -517,7 +521,7 @@ References
[2] arch/arm64/include/uapi/asm/ptrace.h
AArch64 Linux ptrace ABI definitions
-[3] Documentation/arm64/cpu-feature-registers.txt
+[3] Documentation/arm64/cpu-feature-registers.rst
[4] ARM IHI0055C
http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf
diff --git a/Documentation/arm64/tagged-pointers.txt b/Documentation/arm64/tagged-pointers.rst
similarity index 94%
rename from Documentation/arm64/tagged-pointers.txt
rename to Documentation/arm64/tagged-pointers.rst
index a25a99e82bb1..2acdec3ebbeb 100644
--- a/Documentation/arm64/tagged-pointers.txt
+++ b/Documentation/arm64/tagged-pointers.rst
@@ -1,7 +1,9 @@
- Tagged virtual addresses in AArch64 Linux
- =========================================
+=========================================
+Tagged virtual addresses in AArch64 Linux
+=========================================
Author: Will Deacon <will.deacon@arm.com>
+
Date : 12 June 2013
This document briefly describes the provision of tagged virtual
diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt
index c1dd968c5ee9..3bfbf66e5a5e 100644
--- a/Documentation/translations/zh_CN/arm64/booting.txt
+++ b/Documentation/translations/zh_CN/arm64/booting.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/booting.txt
+Chinese translated version of Documentation/arm64/booting.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -10,7 +10,7 @@ M: Will Deacon <will.deacon@arm.com>
zh_CN: Fu Wei <wefu@redhat.com>
C: 55f058e7574c3615dea4615573a19bdb258696c6
---------------------------------------------------------------------
-Documentation/arm64/booting.txt 的中文翻译
+Documentation/arm64/booting.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
index 68362a1ab717..e295cf75f606 100644
--- a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
+++ b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/legacy_instructions.txt
+Chinese translated version of Documentation/arm64/legacy_instructions.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -10,7 +10,7 @@ Maintainer: Punit Agrawal <punit.agrawal@arm.com>
Suzuki K. Poulose <suzuki.poulose@arm.com>
Chinese maintainer: Fu Wei <wefu@redhat.com>
---------------------------------------------------------------------
-Documentation/arm64/legacy_instructions.txt 的中文翻译
+Documentation/arm64/legacy_instructions.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/memory.txt b/Documentation/translations/zh_CN/arm64/memory.txt
index 19b3a52d5d94..be20f8228b91 100644
--- a/Documentation/translations/zh_CN/arm64/memory.txt
+++ b/Documentation/translations/zh_CN/arm64/memory.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/memory.txt
+Chinese translated version of Documentation/arm64/memory.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
Maintainer: Catalin Marinas <catalin.marinas@arm.com>
Chinese maintainer: Fu Wei <wefu@redhat.com>
---------------------------------------------------------------------
-Documentation/arm64/memory.txt 的中文翻译
+Documentation/arm64/memory.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/silicon-errata.txt b/Documentation/translations/zh_CN/arm64/silicon-errata.txt
index 39477c75c4a4..440c59ac7dce 100644
--- a/Documentation/translations/zh_CN/arm64/silicon-errata.txt
+++ b/Documentation/translations/zh_CN/arm64/silicon-errata.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/silicon-errata.txt
+Chinese translated version of Documentation/arm64/silicon-errata.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -10,7 +10,7 @@ M: Will Deacon <will.deacon@arm.com>
zh_CN: Fu Wei <wefu@redhat.com>
C: 1926e54f115725a9248d0c4c65c22acaf94de4c4
---------------------------------------------------------------------
-Documentation/arm64/silicon-errata.txt 的中文翻译
+Documentation/arm64/silicon-errata.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
index 2664d1bd5a1c..77ac3548a16d 100644
--- a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
+++ b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm64/tagged-pointers.txt
+Chinese translated version of Documentation/arm64/tagged-pointers.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
Maintainer: Will Deacon <will.deacon@arm.com>
Chinese maintainer: Fu Wei <wefu@redhat.com>
---------------------------------------------------------------------
-Documentation/arm64/tagged-pointers.txt 的中文翻译
+Documentation/arm64/tagged-pointers.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index ba6c42c576dd..68984c284c40 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -2205,7 +2205,7 @@ max_vq. This is the maximum vector length available to the guest on
this vcpu, and determines which register slices are visible through
this ioctl interface.
-(See Documentation/arm64/sve.txt for an explanation of the "vq"
+(See Documentation/arm64/sve.rst for an explanation of the "vq"
nomenclature.)
KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT.
diff --git a/arch/arm64/include/asm/efi.h b/arch/arm64/include/asm/efi.h
index c9e9a6978e73..8e79ce9c3f5c 100644
--- a/arch/arm64/include/asm/efi.h
+++ b/arch/arm64/include/asm/efi.h
@@ -83,7 +83,7 @@ static inline unsigned long efi_get_max_fdt_addr(unsigned long dram_base)
* guaranteed to cover the kernel Image.
*
* Since the EFI stub is part of the kernel Image, we can relax the
- * usual requirements in Documentation/arm64/booting.txt, which still
+ * usual requirements in Documentation/arm64/booting.rst, which still
* apply to other bootloaders, and are required for some kernel
* configurations.
*/
diff --git a/arch/arm64/include/asm/image.h b/arch/arm64/include/asm/image.h
index e2c27a2278e9..c2b13213c720 100644
--- a/arch/arm64/include/asm/image.h
+++ b/arch/arm64/include/asm/image.h
@@ -27,7 +27,7 @@
/*
* struct arm64_image_header - arm64 kernel image header
- * See Documentation/arm64/booting.txt for details
+ * See Documentation/arm64/booting.rst for details
*
* @code0: Executable code, or
* @mz_header alternatively used for part of MZ header
diff --git a/arch/arm64/include/uapi/asm/sigcontext.h b/arch/arm64/include/uapi/asm/sigcontext.h
index 5f3c0cec5af9..a61f89ddbf34 100644
--- a/arch/arm64/include/uapi/asm/sigcontext.h
+++ b/arch/arm64/include/uapi/asm/sigcontext.h
@@ -137,7 +137,7 @@ struct sve_context {
* vector length beyond its initial architectural limit of 2048 bits
* (16 quadwords).
*
- * See linux/Documentation/arm64/sve.txt for a description of the VL/VQ
+ * See linux/Documentation/arm64/sve.rst for a description of the VL/VQ
* terminology.
*/
#define SVE_VQ_BYTES __SVE_VQ_BYTES /* bytes per quadword */
diff --git a/arch/arm64/kernel/kexec_image.c b/arch/arm64/kernel/kexec_image.c
index 31cc2f423aa8..2514fd6f12cb 100644
--- a/arch/arm64/kernel/kexec_image.c
+++ b/arch/arm64/kernel/kexec_image.c
@@ -53,7 +53,7 @@ static void *image_load(struct kimage *image,
/*
* We require a kernel with an unambiguous Image header. Per
- * Documentation/arm64/booting.txt, this is the case when image_size
+ * Documentation/arm64/booting.rst, this is the case when image_size
* is non-zero (practically speaking, since v3.17).
*/
h = (struct arm64_image_header *)kernel;
--
2.21.0
^ permalink raw reply related
* [PATCH v4 08/28] docs: fault-injection: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Akinobu Mita, Federico Vaga, Harry Wei, Alex Shi,
Kees Cook, Arnd Bergmann, Greg Kroah-Hartman
In-Reply-To: <cover.1560361364.git.mchehab+samsung@kernel.org>
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
...ault-injection.txt => fault-injection.rst} | 265 +++++++++---------
Documentation/fault-injection/index.rst | 20 ++
...r-inject.txt => notifier-error-inject.rst} | 18 +-
.../fault-injection/nvme-fault-injection.rst | 120 ++++++++
.../fault-injection/nvme-fault-injection.txt | 116 --------
.../fault-injection/provoke-crashes.rst | 48 ++++
.../fault-injection/provoke-crashes.txt | 38 ---
Documentation/process/4.Coding.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
include/linux/fault-inject.h | 2 +-
lib/Kconfig.debug | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
14 files changed, 344 insertions(+), 295 deletions(-)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
create mode 100644 Documentation/fault-injection/nvme-fault-injection.rst
delete mode 100644 Documentation/fault-injection/nvme-fault-injection.txt
create mode 100644 Documentation/fault-injection/provoke-crashes.rst
delete mode 100644 Documentation/fault-injection/provoke-crashes.txt
diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.rst
similarity index 68%
rename from Documentation/fault-injection/fault-injection.txt
rename to Documentation/fault-injection/fault-injection.rst
index a17517a083c3..f51bb21d20e4 100644
--- a/Documentation/fault-injection/fault-injection.txt
+++ b/Documentation/fault-injection/fault-injection.rst
@@ -1,3 +1,4 @@
+===========================================
Fault injection capabilities infrastructure
===========================================
@@ -7,36 +8,36 @@ See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug.
Available fault injection capabilities
--------------------------------------
-o failslab
+- failslab
injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
-o fail_page_alloc
+- fail_page_alloc
injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
-o fail_futex
+- fail_futex
injects futex deadlock and uaddr fault errors.
-o fail_make_request
+- fail_make_request
injects disk IO errors on devices permitted by setting
/sys/block/<device>/make-it-fail or
/sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
-o fail_mmc_request
+- fail_mmc_request
injects MMC data errors on devices permitted by setting
debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
-o fail_function
+- fail_function
injects error return on specific functions, which are marked by
ALLOW_ERROR_INJECTION() macro, by setting debugfs entries
under /sys/kernel/debug/fail_function. No boot option supported.
-o NVMe fault injection
+- NVMe fault injection
inject NVMe status code and retry flag on devices permitted by setting
debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default
@@ -47,7 +48,8 @@ o NVMe fault injection
Configure fault-injection capabilities behavior
-----------------------------------------------
-o debugfs entries
+debugfs entries
+^^^^^^^^^^^^^^^
fault-inject-debugfs kernel module provides some debugfs entries for runtime
configuration of fault-injection capabilities.
@@ -55,6 +57,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/probability:
likelihood of failure injection, in percent.
+
Format: <percent>
Note that one-failure-per-hundred is a very high error rate
@@ -83,6 +86,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/verbose
Format: { 0 | 1 | 2 }
+
specifies the verbosity of the messages when failure is
injected. '0' means no messages; '1' will print only a single
log line per failure; '2' will print a call trace too -- useful
@@ -91,14 +95,15 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/task-filter:
Format: { 'Y' | 'N' }
+
A value of 'N' disables filtering by process (default).
Any positive value limits failures to only processes indicated by
/proc/<pid>/make-it-fail==1.
-- /sys/kernel/debug/fail*/require-start:
-- /sys/kernel/debug/fail*/require-end:
-- /sys/kernel/debug/fail*/reject-start:
-- /sys/kernel/debug/fail*/reject-end:
+- /sys/kernel/debug/fail*/require-start,
+ /sys/kernel/debug/fail*/require-end,
+ /sys/kernel/debug/fail*/reject-start,
+ /sys/kernel/debug/fail*/reject-end:
specifies the range of virtual addresses tested during
stacktrace walking. Failure is injected only if some caller
@@ -116,6 +121,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' won't inject failures into
highmem/user allocations.
@@ -123,6 +129,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will inject failures
only into non-sleep allocations (GFP_ATOMIC allocations).
@@ -134,12 +141,14 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_futex/ignore-private:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will disable failure injections
when dealing with private (address space) futexes.
- /sys/kernel/debug/fail_function/inject:
Format: { 'function-name' | '!function-name' | '' }
+
specifies the target function of error injection by name.
If the function name leads '!' prefix, given function is
removed from injection list. If nothing specified ('')
@@ -160,10 +169,11 @@ configuration of fault-injection capabilities.
function for given function. This will be created when
user specifies new injection entry.
-o Boot option
+Boot option
+^^^^^^^^^^^
In order to inject faults while debugfs is not available (early boot time),
-use the boot option:
+use the boot option::
failslab=
fail_page_alloc=
@@ -171,10 +181,11 @@ use the boot option:
fail_futex=
mmc_core.fail_request=<interval>,<probability>,<space>,<times>
-o proc entries
+proc entries
+^^^^^^^^^^^^
-- /proc/<pid>/fail-nth:
-- /proc/self/task/<tid>/fail-nth:
+- /proc/<pid>/fail-nth,
+ /proc/self/task/<tid>/fail-nth:
Write to this file of integer N makes N-th call in the task fail.
Read from this file returns a integer value. A value of '0' indicates
@@ -191,16 +202,16 @@ o proc entries
How to add new fault injection capability
-----------------------------------------
-o #include <linux/fault-inject.h>
+- #include <linux/fault-inject.h>
-o define the fault attributes
+- define the fault attributes
DECLARE_FAULT_ATTR(name);
Please see the definition of struct fault_attr in fault-inject.h
for details.
-o provide a way to configure fault attributes
+- provide a way to configure fault attributes
- boot option
@@ -222,126 +233,126 @@ o provide a way to configure fault attributes
single kernel module, it is better to provide module parameters to
configure the fault attributes.
-o add a hook to insert failures
+- add a hook to insert failures
- Upon should_fail() returning true, client code should inject a failure.
+ Upon should_fail() returning true, client code should inject a failure:
should_fail(attr, size);
Application Examples
--------------------
-o Inject slab allocation failures into module init/exit code
+- Inject slab allocation failures into module init/exit code::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=failslab
-echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ FAILTYPE=failslab
+ echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-faulty_system()
-{
+ faulty_system()
+ {
bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
-}
+ }
-if [ $# -eq 0 ]
-then
+ if [ $# -eq 0 ]
+ then
echo "Usage: $0 modulename [ modulename ... ]"
exit 1
-fi
+ fi
-for m in $*
-do
+ for m in $*
+ do
echo inserting $m...
faulty_system modprobe $m
echo removing $m...
faulty_system modprobe -r $m
-done
+ done
------------------------------------------------------------------------------
-o Inject page allocation failures only for a specific module
+- Inject page allocation failures only for a specific module::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=fail_page_alloc
-module=$1
+ FAILTYPE=fail_page_alloc
+ module=$1
-if [ -z $module ]
-then
+ if [ -z $module ]
+ then
echo "Usage: $0 <modulename>"
exit 1
-fi
+ fi
-modprobe $module
+ modprobe $module
-if [ ! -d /sys/module/$module/sections ]
-then
+ if [ ! -d /sys/module/$module/sections ]
+ then
echo Module $module is not loaded
exit 1
-fi
+ fi
-cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
-cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
+ cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
+ cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
-echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
+ echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
-trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
+ trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
-echo "Injecting errors into the module $module... (interrupt to stop)"
-sleep 1000000
+ echo "Injecting errors into the module $module... (interrupt to stop)"
+ sleep 1000000
------------------------------------------------------------------------------
-o Inject open_ctree error while btrfs mount
+- Inject open_ctree error while btrfs mount::
-#!/bin/bash
+ #!/bin/bash
-rm -f testfile.img
-dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
-DEVICE=$(losetup --show -f testfile.img)
-mkfs.btrfs -f $DEVICE
-mkdir -p tmpmnt
+ rm -f testfile.img
+ dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
+ DEVICE=$(losetup --show -f testfile.img)
+ mkfs.btrfs -f $DEVICE
+ mkdir -p tmpmnt
-FAILTYPE=fail_function
-FAILFUNC=open_ctree
-echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
-echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 100 > /sys/kernel/debug/$FAILTYPE/probability
-echo 0 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
+ FAILTYPE=fail_function
+ FAILFUNC=open_ctree
+ echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
+ echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 100 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 0 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
-mount -t btrfs $DEVICE tmpmnt
-if [ $? -ne 0 ]
-then
+ mount -t btrfs $DEVICE tmpmnt
+ if [ $? -ne 0 ]
+ then
echo "SUCCESS!"
-else
+ else
echo "FAILED!"
umount tmpmnt
-fi
+ fi
-echo > /sys/kernel/debug/$FAILTYPE/inject
+ echo > /sys/kernel/debug/$FAILTYPE/inject
-rmdir tmpmnt
-losetup -d $DEVICE
-rm testfile.img
+ rmdir tmpmnt
+ losetup -d $DEVICE
+ rm testfile.img
Tool to run command with failslab or fail_page_alloc
@@ -354,43 +365,43 @@ see the following examples.
Examples:
Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
-allocation failure.
+allocation failure::
# ./tools/testing/fault-injection/failcmd.sh \
-- make -C tools/testing/selftests/ run_tests
Same as above except to specify 100 times failures at most instead of one time
-at most by default.
+at most by default::
# ./tools/testing/fault-injection/failcmd.sh --times=100 \
-- make -C tools/testing/selftests/ run_tests
Same as above except to inject page allocation failure instead of slab
-allocation failure.
+allocation failure::
# env FAILCMD_TYPE=fail_page_alloc \
./tools/testing/fault-injection/failcmd.sh --times=100 \
- -- make -C tools/testing/selftests/ run_tests
+ -- make -C tools/testing/selftests/ run_tests
Systematic faults using fail-nth
---------------------------------
The following code systematically faults 0-th, 1-st, 2-nd and so on
-capabilities in the socketpair() system call.
+capabilities in the socketpair() system call::
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/socket.h>
-#include <sys/syscall.h>
-#include <fcntl.h>
-#include <unistd.h>
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-#include <errno.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <sys/socket.h>
+ #include <sys/syscall.h>
+ #include <fcntl.h>
+ #include <unistd.h>
+ #include <string.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <errno.h>
-int main()
-{
+ int main()
+ {
int i, err, res, fail_nth, fds[2];
char buf[128];
@@ -413,23 +424,23 @@ int main()
break;
}
return 0;
-}
+ }
-An example output:
+An example output::
-1-th fault Y: res=-1/23
-2-th fault Y: res=-1/23
-3-th fault Y: res=-1/12
-4-th fault Y: res=-1/12
-5-th fault Y: res=-1/23
-6-th fault Y: res=-1/23
-7-th fault Y: res=-1/23
-8-th fault Y: res=-1/12
-9-th fault Y: res=-1/12
-10-th fault Y: res=-1/12
-11-th fault Y: res=-1/12
-12-th fault Y: res=-1/12
-13-th fault Y: res=-1/12
-14-th fault Y: res=-1/12
-15-th fault Y: res=-1/12
-16-th fault N: res=0/12
+ 1-th fault Y: res=-1/23
+ 2-th fault Y: res=-1/23
+ 3-th fault Y: res=-1/12
+ 4-th fault Y: res=-1/12
+ 5-th fault Y: res=-1/23
+ 6-th fault Y: res=-1/23
+ 7-th fault Y: res=-1/23
+ 8-th fault Y: res=-1/12
+ 9-th fault Y: res=-1/12
+ 10-th fault Y: res=-1/12
+ 11-th fault Y: res=-1/12
+ 12-th fault Y: res=-1/12
+ 13-th fault Y: res=-1/12
+ 14-th fault Y: res=-1/12
+ 15-th fault Y: res=-1/12
+ 16-th fault N: res=0/12
diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst
new file mode 100644
index 000000000000..92b5639ed07a
--- /dev/null
+++ b/Documentation/fault-injection/index.rst
@@ -0,0 +1,20 @@
+:orphan:
+
+===============
+fault-injection
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ fault-injection
+ notifier-error-inject
+ nvme-fault-injection
+ provoke-crashes
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/fault-injection/notifier-error-inject.txt b/Documentation/fault-injection/notifier-error-inject.rst
similarity index 83%
rename from Documentation/fault-injection/notifier-error-inject.txt
rename to Documentation/fault-injection/notifier-error-inject.rst
index e861d761de24..1668b6e48d3a 100644
--- a/Documentation/fault-injection/notifier-error-inject.txt
+++ b/Documentation/fault-injection/notifier-error-inject.rst
@@ -14,7 +14,8 @@ modules that can be used to test the following notifiers.
PM notifier error injection module
----------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
Possible PM notifier events to be failed are:
@@ -22,7 +23,7 @@ Possible PM notifier events to be failed are:
* PM_SUSPEND_PREPARE
* PM_RESTORE_PREPARE
-Example: Inject PM suspend error (-12 = -ENOMEM)
+Example: Inject PM suspend error (-12 = -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/pm/
# echo -12 > actions/PM_SUSPEND_PREPARE/error
@@ -32,14 +33,15 @@ Example: Inject PM suspend error (-12 = -ENOMEM)
Memory hotplug notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
Possible memory notifier events to be failed are:
* MEM_GOING_ONLINE
* MEM_GOING_OFFLINE
-Example: Inject memory hotplug offline error (-12 == -ENOMEM)
+Example: Inject memory hotplug offline error (-12 == -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/memory
# echo -12 > actions/MEM_GOING_OFFLINE/error
@@ -49,7 +51,8 @@ Example: Inject memory hotplug offline error (-12 == -ENOMEM)
powerpc pSeries reconfig notifier error injection module
--------------------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
Possible pSeries reconfig notifier events to be failed are:
@@ -61,7 +64,8 @@ Possible pSeries reconfig notifier events to be failed are:
Netdevice notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
Netdevice notifier events which can be failed are:
@@ -75,7 +79,7 @@ Netdevice notifier events which can be failed are:
* NETDEV_PRECHANGEUPPER
* NETDEV_CHANGEUPPER
-Example: Inject netdevice mtu change error (-22 == -EINVAL)
+Example: Inject netdevice mtu change error (-22 == -EINVAL)::
# cd /sys/kernel/debug/notifier-error-inject/netdev
# echo -22 > actions/NETDEV_CHANGEMTU/error
diff --git a/Documentation/fault-injection/nvme-fault-injection.rst b/Documentation/fault-injection/nvme-fault-injection.rst
new file mode 100644
index 000000000000..bbb1bf3e8650
--- /dev/null
+++ b/Documentation/fault-injection/nvme-fault-injection.rst
@@ -0,0 +1,120 @@
+NVMe Fault Injection
+====================
+Linux's fault injection framework provides a systematic way to support
+error injection via debugfs in the /sys/kernel/debug directory. When
+enabled, the default NVME_SC_INVALID_OPCODE with no retry will be
+injected into the nvme_end_request. Users can change the default status
+code and no retry flag via the debugfs. The list of Generic Command
+Status can be found in include/linux/nvme.h
+
+Following examples show how to inject an error into the nvme.
+
+First, enable CONFIG_FAULT_INJECTION_DEBUG_FS kernel config,
+recompile the kernel. After booting up the kernel, do the
+following.
+
+Example 1: Inject default status code with no retry
+---------------------------------------------------
+
+::
+
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ cp a.file /mnt
+
+Expected Result::
+
+ cp: cannot stat ‘/mnt/a.file’: Input/output error
+
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
+ Hardware name: innotek GmbH VirtualBox/VirtualBox,
+ BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x2f/0x50 [nvme_core]
+ nvme_process_cq+0xe7/0x1d0 [nvme]
+ nvme_irq+0x1e/0x40 [nvme]
+ __handle_irq_event_percpu+0x3a/0x190
+ handle_irq_event_percpu+0x30/0x70
+ handle_irq_event+0x36/0x60
+ handle_fasteoi_irq+0x78/0x120
+ handle_irq+0xa7/0x130
+ ? tick_irq_enter+0xa8/0xc0
+ do_IRQ+0x43/0xc0
+ common_interrupt+0xa2/0xa2
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
+ RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
+ R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_kernel+0x4c4/0x4e4
+ ? set_init_arg+0x55/0x55
+ secondary_startup_64+0xa5/0xb0
+ print_req_error: I/O error, dev nvme0n1, sector 9240
+ EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
+ inode #2: comm cp: reading directory lblock 0
+
+Example 2: Inject default status code with retry
+------------------------------------------------
+
+::
+
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
+ echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
+
+ cp a.file /mnt
+
+Expected Result::
+
+ command success without error
+
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
+ Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x30/0x60 [nvme_core]
+ nvme_loop_queue_response+0x84/0x110 [nvme_loop]
+ nvmet_req_complete+0x11/0x40 [nvmet]
+ nvmet_bio_done+0x28/0x40 [nvmet]
+ blk_update_request+0xb0/0x310
+ blk_mq_end_request+0x18/0x60
+ flush_smp_call_function_queue+0x3d/0xf0
+ smp_call_function_single_interrupt+0x2c/0xc0
+ call_function_single_interrupt+0xa2/0xb0
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
+ RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
+ R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_secondary+0x187/0x1e0
+ secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/nvme-fault-injection.txt b/Documentation/fault-injection/nvme-fault-injection.txt
deleted file mode 100644
index 8fbf3bf60b62..000000000000
--- a/Documentation/fault-injection/nvme-fault-injection.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-NVMe Fault Injection
-====================
-Linux's fault injection framework provides a systematic way to support
-error injection via debugfs in the /sys/kernel/debug directory. When
-enabled, the default NVME_SC_INVALID_OPCODE with no retry will be
-injected into the nvme_end_request. Users can change the default status
-code and no retry flag via the debugfs. The list of Generic Command
-Status can be found in include/linux/nvme.h
-
-Following examples show how to inject an error into the nvme.
-
-First, enable CONFIG_FAULT_INJECTION_DEBUG_FS kernel config,
-recompile the kernel. After booting up the kernel, do the
-following.
-
-Example 1: Inject default status code with no retry
----------------------------------------------------
-
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-cp a.file /mnt
-
-Expected Result:
-
-cp: cannot stat ‘/mnt/a.file’: Input/output error
-
-Message from dmesg:
-
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
-Hardware name: innotek GmbH VirtualBox/VirtualBox,
-BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x2f/0x50 [nvme_core]
- nvme_process_cq+0xe7/0x1d0 [nvme]
- nvme_irq+0x1e/0x40 [nvme]
- __handle_irq_event_percpu+0x3a/0x190
- handle_irq_event_percpu+0x30/0x70
- handle_irq_event+0x36/0x60
- handle_fasteoi_irq+0x78/0x120
- handle_irq+0xa7/0x130
- ? tick_irq_enter+0xa8/0xc0
- do_IRQ+0x43/0xc0
- common_interrupt+0xa2/0xa2
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
-RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
-R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_kernel+0x4c4/0x4e4
- ? set_init_arg+0x55/0x55
- secondary_startup_64+0xa5/0xb0
- print_req_error: I/O error, dev nvme0n1, sector 9240
-EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
-inode #2: comm cp: reading directory lblock 0
-
-Example 2: Inject default status code with retry
-------------------------------------------------
-
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
-echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
-
-cp a.file /mnt
-
-Expected Result:
-
-command success without error
-
-Message from dmesg:
-
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
-Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x30/0x60 [nvme_core]
- nvme_loop_queue_response+0x84/0x110 [nvme_loop]
- nvmet_req_complete+0x11/0x40 [nvmet]
- nvmet_bio_done+0x28/0x40 [nvmet]
- blk_update_request+0xb0/0x310
- blk_mq_end_request+0x18/0x60
- flush_smp_call_function_queue+0x3d/0xf0
- smp_call_function_single_interrupt+0x2c/0xc0
- call_function_single_interrupt+0xa2/0xb0
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
-RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
-R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_secondary+0x187/0x1e0
- secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/provoke-crashes.rst b/Documentation/fault-injection/provoke-crashes.rst
new file mode 100644
index 000000000000..9279a3e12278
--- /dev/null
+++ b/Documentation/fault-injection/provoke-crashes.rst
@@ -0,0 +1,48 @@
+===============
+Provoke crashes
+===============
+
+The lkdtm module provides an interface to crash or injure the kernel at
+predefined crashpoints to evaluate the reliability of crash dumps obtained
+using different dumping solutions. The module uses KPROBEs to instrument
+crashing points, but can also crash the kernel directly without KRPOBE
+support.
+
+
+You can provide the way either through module arguments when inserting
+the module, or through a debugfs interface.
+
+Usage::
+
+ insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
+ [cpoint_count={>0}]
+
+recur_count
+ Recursion level for the stack overflow test. Default is 10.
+
+cpoint_name
+ Crash point where the kernel is to be crashed. It can be
+ one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
+ FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
+ IDE_CORE_CP, DIRECT
+
+cpoint_type
+ Indicates the action to be taken on hitting the crash point.
+ It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
+ CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
+ WRITE_AFTER_FREE,
+
+cpoint_count
+ Indicates the number of times the crash point is to be hit
+ to trigger an action. The default is 10.
+
+You can also induce failures by mounting debugfs and writing the type to
+<mountpoint>/provoke-crash/<crashpoint>. E.g.::
+
+ mount -t debugfs debugfs /mnt
+ echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
+
+
+A special file is `DIRECT` which will induce the crash directly without
+KPROBE instrumentation. This mode is the only one available when the module
+is built on a kernel without KPROBEs support.
diff --git a/Documentation/fault-injection/provoke-crashes.txt b/Documentation/fault-injection/provoke-crashes.txt
deleted file mode 100644
index 7a9d3d81525b..000000000000
--- a/Documentation/fault-injection/provoke-crashes.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-The lkdtm module provides an interface to crash or injure the kernel at
-predefined crashpoints to evaluate the reliability of crash dumps obtained
-using different dumping solutions. The module uses KPROBEs to instrument
-crashing points, but can also crash the kernel directly without KRPOBE
-support.
-
-
-You can provide the way either through module arguments when inserting
-the module, or through a debugfs interface.
-
-Usage: insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
- [cpoint_count={>0}]
-
- recur_count : Recursion level for the stack overflow test. Default is 10.
-
- cpoint_name : Crash point where the kernel is to be crashed. It can be
- one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
- FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
- IDE_CORE_CP, DIRECT
-
- cpoint_type : Indicates the action to be taken on hitting the crash point.
- It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
- CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
- WRITE_AFTER_FREE,
-
- cpoint_count : Indicates the number of times the crash point is to be hit
- to trigger an action. The default is 10.
-
-You can also induce failures by mounting debugfs and writing the type to
-<mountpoint>/provoke-crash/<crashpoint>. E.g.,
-
- mount -t debugfs debugfs /mnt
- echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
-
-
-A special file is `DIRECT' which will induce the crash directly without
-KPROBE instrumentation. This mode is the only one available when the module
-is built on a kernel without KPROBEs support.
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 4b7a5ab3cec1..13dd893c9f88 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -298,7 +298,7 @@ enabled, a configurable percentage of memory allocations will be made to
fail; these failures can be restricted to a specific range of code.
Running with fault injection enabled allows the programmer to see how the
code responds when things go badly. See
-Documentation/fault-injection/fault-injection.txt for more information on
+Documentation/fault-injection/fault-injection.rst for more information on
how to use this facility.
Other kinds of errors can be found with the "sparse" static analysis tool.
diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst
index c05b89e616dd..a5e36aa60448 100644
--- a/Documentation/translations/it_IT/process/4.Coding.rst
+++ b/Documentation/translations/it_IT/process/4.Coding.rst
@@ -314,7 +314,7 @@ di allocazione di memoria sarà destinata al fallimento; questi fallimenti
possono essere ridotti ad uno specifico pezzo di codice. Procedere con
l'inserimento dei fallimenti attivo permette al programmatore di verificare
come il codice risponde quando le cose vanno male. Consultate:
-Documentation/fault-injection/fault-injection.txt per avere maggiori
+Documentation/fault-injection/fault-injection.rst per avere maggiori
informazioni su come utilizzare questo strumento.
Altre tipologie di errori possono essere riscontrati con lo strumento di
diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
index 8bb777941394..b82b1dde3122 100644
--- a/Documentation/translations/zh_CN/process/4.Coding.rst
+++ b/Documentation/translations/zh_CN/process/4.Coding.rst
@@ -205,7 +205,7 @@ Linus对这个问题给出了最佳答案:
启用故障注入后，内存分配的可配置百分比将失败；这些失败可以限制在特定的代码
范围内。在启用了故障注入的情况下运行，程序员可以看到当情况恶化时代码如何响
应。有关如何使用此工具的详细信息，请参阅
-Documentation/fault-injection/fault-injection.txt。
+Documentation/fault-injection/fault-injection.rst。
使用“sparse”静态分析工具可以发现其他类型的错误。对于sparse，可以警告程序员
用户空间和内核空间地址之间的混淆、big endian和small endian数量的混合、在需
diff --git a/drivers/misc/lkdtm/core.c b/drivers/misc/lkdtm/core.c
index df9429e3fd3a..c7a507482051 100644
--- a/drivers/misc/lkdtm/core.c
+++ b/drivers/misc/lkdtm/core.c
@@ -15,7 +15,7 @@
*
* Debugfs support added by Simon Kagstrom <simon.kagstrom@netinsight.net>
*
- * See Documentation/fault-injection/provoke-crashes.txt for instructions
+ * See Documentation/fault-injection/provoke-crashes.rst for instructions
*/
#include "lkdtm.h"
#include <linux/fs.h>
diff --git a/include/linux/fault-inject.h b/include/linux/fault-inject.h
index 7e6c77740413..e525f6957c49 100644
--- a/include/linux/fault-inject.h
+++ b/include/linux/fault-inject.h
@@ -11,7 +11,7 @@
/*
* For explanation of the elements of this struct, see
- * Documentation/fault-injection/fault-injection.txt
+ * Documentation/fault-injection/fault-injection.rst
*/
struct fault_attr {
unsigned long probability;
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index d08f5848958e..3a3554e8ca0f 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1701,7 +1701,7 @@ config LKDTM
called lkdtm.
Documentation on how to use the module can be found in
- Documentation/fault-injection/provoke-crashes.txt
+ Documentation/fault-injection/provoke-crashes.rst
config TEST_LIST_SORT
tristate "Linked list sorting test"
diff --git a/tools/testing/fault-injection/failcmd.sh b/tools/testing/fault-injection/failcmd.sh
index 29a6c63c5a15..78dac34264be 100644
--- a/tools/testing/fault-injection/failcmd.sh
+++ b/tools/testing/fault-injection/failcmd.sh
@@ -42,7 +42,7 @@ OPTIONS
--interval=value, --space=value, --verbose=value, --task-filter=value,
--stacktrace-depth=value, --require-start=value, --require-end=value,
--reject-start=value, --reject-end=value, --ignore-gfp-wait=value
- See Documentation/fault-injection/fault-injection.txt for more
+ See Documentation/fault-injection/fault-injection.rst for more
information
failslab options:
--
2.21.0
^ permalink raw reply related
* [PATCH v4 23/28] docs: target: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Martin K. Petersen, linux-scsi, target-devel
In-Reply-To: <cover.1560361364.git.mchehab+samsung@kernel.org>
Convert the TCM docs to ReST format and add them to the
bookset.
This has a mix of userspace-faced and Kernelspace faced
docs. Still, it sounds a better candidate to be added at
the kernel API set of docs.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/target/index.rst | 19 ++
Documentation/target/scripts.rst | 11 +
Documentation/target/tcm_mod_builder.rst | 149 ++++++++++
Documentation/target/tcm_mod_builder.txt | 145 ----------
.../{tcmu-design.txt => tcmu-design.rst} | 268 ++++++++++--------
scripts/documentation-file-ref-check | 2 +-
6 files changed, 326 insertions(+), 268 deletions(-)
create mode 100644 Documentation/target/index.rst
create mode 100644 Documentation/target/scripts.rst
create mode 100644 Documentation/target/tcm_mod_builder.rst
delete mode 100644 Documentation/target/tcm_mod_builder.txt
rename Documentation/target/{tcmu-design.txt => tcmu-design.rst} (69%)
diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst
new file mode 100644
index 000000000000..b68f48982392
--- /dev/null
+++ b/Documentation/target/index.rst
@@ -0,0 +1,19 @@
+:orphan:
+
+==================
+TCM Virtual Device
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ tcmu-design
+ tcm_mod_builder
+ scripts
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/target/scripts.rst b/Documentation/target/scripts.rst
new file mode 100644
index 000000000000..172d42b522e4
--- /dev/null
+++ b/Documentation/target/scripts.rst
@@ -0,0 +1,11 @@
+TCM mod builder script
+----------------------
+
+.. literalinclude:: tcm_mod_builder.py
+ :language: perl
+
+Target export device script
+---------------------------
+
+.. literalinclude:: target-export-device
+ :language: shell
diff --git a/Documentation/target/tcm_mod_builder.rst b/Documentation/target/tcm_mod_builder.rst
new file mode 100644
index 000000000000..9bfc9822e2bd
--- /dev/null
+++ b/Documentation/target/tcm_mod_builder.rst
@@ -0,0 +1,149 @@
+=========================================
+The TCM v4 fabric module script generator
+=========================================
+
+Greetings all,
+
+This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
+script to generate a brand new functional TCM v4 fabric .ko module of your very own,
+that once built can be immediately be loaded to start access the new TCM/ConfigFS
+fabric skeleton, by simply using::
+
+ modprobe $TCM_NEW_MOD
+ mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
+
+This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
+
+ 1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
+ ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
+ into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
+ 2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
+ using a skeleton struct target_core_fabric_ops API template.
+ 3) Based on user defined T10 Proto_Ident for the new fabric module being built,
+ the TransportID / Initiator and Target WWPN related handlers for
+ SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
+ using drivers/target/target_core_fabric_lib.c logic.
+ 4) NOP API calls for all other Data I/O path and fabric dependent attribute logic
+ in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
+
+tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
+$FABRIC_MOD_name' parameters, and actually running the script looks like::
+
+ target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
+ tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
+ Set fabric_mod_name: tcm_nab5000
+ Set fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Using proto_ident: iSCSI
+ Creating fabric_mod_dir:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
+ Using tcm_mod_scan_fabric_ops:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
+ Writing file:
+ /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
+ Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
+ Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
+
+At the end of tcm_mod_builder.py. the script will ask to add the following
+line to drivers/target/Kbuild::
+
+ obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
+
+and the same for drivers/target/Kconfig::
+
+ source "drivers/target/tcm_nab5000/Kconfig"
+
+#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item::
+
+ <M> TCM_NAB5000 fabric module
+
+#) Build using 'make modules', once completed you will have::
+
+ target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
+ total 1348
+ drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
+ drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
+ -rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
+ -rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
+ -rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
+ -rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
+ -rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
+ -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
+ -rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
+ -rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
+ -rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
+ -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
+ -rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
+ -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
+ -rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
+ -rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
+ -rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
+ -rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
+ -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
+ -rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
+
+#) Load the new module, create a lun_0 configfs group, and add new TCM Core
+ IBLOCK backstore symlink to port::
+
+ target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
+ target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
+ target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
+
+ target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
+ target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
+ /sys/kernel/config/target/nab5000/
+ |-- discovery_auth
+ |-- iqn.foo
+ | `-- tpgt_1
+ | |-- acls
+ | |-- attrib
+ | |-- lun
+ | | `-- lun_0
+ | | |-- alua_tg_pt_gp
+ | | |-- alua_tg_pt_offline
+ | | |-- alua_tg_pt_status
+ | | |-- alua_tg_pt_write_md
+ | | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
+ | |-- np
+ | `-- param
+ `-- version
+
+ target:/mnt/sdb/lio-core-2.6.git# lsmod
+ Module Size Used by
+ tcm_nab5000 3935 4
+ iscsi_target_mod 193211 0
+ target_core_stgt 8090 0
+ target_core_pscsi 11122 1
+ target_core_file 9172 2
+ target_core_iblock 9280 1
+ target_core_mod 228575 31
+ tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
+ libfc 73681 0
+ scsi_debug 56265 0
+ scsi_tgt 8666 1 target_core_stgt
+ configfs 20644 2 target_core_mod
+
+----------------------------------------------------------------------
+
+Future TODO items
+=================
+
+ 1) Add more T10 proto_idents
+ 2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
+ defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
+ structure members.
+
+October 5th, 2010
+
+Nicholas A. Bellinger <nab@linux-iscsi.org>
diff --git a/Documentation/target/tcm_mod_builder.txt b/Documentation/target/tcm_mod_builder.txt
deleted file mode 100644
index ae22f7005540..000000000000
--- a/Documentation/target/tcm_mod_builder.txt
+++ /dev/null
@@ -1,145 +0,0 @@
->>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<<
-
-Greetings all,
-
-This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
-script to generate a brand new functional TCM v4 fabric .ko module of your very own,
-that once built can be immediately be loaded to start access the new TCM/ConfigFS
-fabric skeleton, by simply using:
-
- modprobe $TCM_NEW_MOD
- mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
-
-This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
-
- *) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
- ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created
- into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
- *) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
- using a skeleton struct target_core_fabric_ops API template.
- *) Based on user defined T10 Proto_Ident for the new fabric module being built,
- the TransportID / Initiator and Target WWPN related handlers for
- SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
- using drivers/target/target_core_fabric_lib.c logic.
- *) NOP API calls for all other Data I/O path and fabric dependent attribute logic
- in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
-
-tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
-$FABRIC_MOD_name' parameters, and actually running the script looks like:
-
-target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
-tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
-Set fabric_mod_name: tcm_nab5000
-Set fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Using proto_ident: iSCSI
-Creating fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
-Using tcm_mod_scan_fabric_ops:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
-Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
-Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
-
-At the end of tcm_mod_builder.py. the script will ask to add the following
-line to drivers/target/Kbuild:
-
- obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/
-
-and the same for drivers/target/Kconfig:
-
- source "drivers/target/tcm_nab5000/Kconfig"
-
-*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:
-
- <M> TCM_NAB5000 fabric module
-
-*) Build using 'make modules', once completed you will have:
-
-target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
-total 1348
-drwxr-xr-x 2 root root 4096 2010-10-05 03:23 .
-drwxr-xr-x 9 root root 4096 2010-10-05 03:22 ..
--rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild
--rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig
--rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order
--rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h
--rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c
--rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
--rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
--rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c
--rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h
--rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
--rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
--rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
--rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
--rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c
--rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o
--rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
--rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
--rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd
-
-*) Load the new module, create a lun_0 configfs group, and add new TCM Core
- IBLOCK backstore symlink to port:
-
-target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
-target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
-target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
-
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
-target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
-/sys/kernel/config/target/nab5000/
-|-- discovery_auth
-|-- iqn.foo
-| `-- tpgt_1
-| |-- acls
-| |-- attrib
-| |-- lun
-| | `-- lun_0
-| | |-- alua_tg_pt_gp
-| | |-- alua_tg_pt_offline
-| | |-- alua_tg_pt_status
-| | |-- alua_tg_pt_write_md
-| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
-| |-- np
-| `-- param
-`-- version
-
-target:/mnt/sdb/lio-core-2.6.git# lsmod
-Module Size Used by
-tcm_nab5000 3935 4
-iscsi_target_mod 193211 0
-target_core_stgt 8090 0
-target_core_pscsi 11122 1
-target_core_file 9172 2
-target_core_iblock 9280 1
-target_core_mod 228575 31
-tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
-libfc 73681 0
-scsi_debug 56265 0
-scsi_tgt 8666 1 target_core_stgt
-configfs 20644 2 target_core_mod
-
-----------------------------------------------------------------------
-
-Future TODO items:
-
- *) Add more T10 proto_idents
- *) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
- defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
- structure members.
-
-October 5th, 2010
-Nicholas A. Bellinger <nab@linux-iscsi.org>
diff --git a/Documentation/target/tcmu-design.txt b/Documentation/target/tcmu-design.rst
similarity index 69%
rename from Documentation/target/tcmu-design.txt
rename to Documentation/target/tcmu-design.rst
index 4cebc1ebf99a..a7b426707bf6 100644
--- a/Documentation/target/tcmu-design.txt
+++ b/Documentation/target/tcmu-design.rst
@@ -1,25 +1,30 @@
-Contents:
+====================
+TCM Userspace Design
+====================
+
+
+.. Contents:
-1) TCM Userspace Design
- a) Background
- b) Benefits
- c) Design constraints
- d) Implementation overview
- i. Mailbox
- ii. Command ring
- iii. Data Area
- e) Device discovery
- f) Device events
- g) Other contingencies
-2) Writing a user pass-through handler
- a) Discovering and configuring TCMU uio devices
- b) Waiting for events on the device(s)
- c) Managing the command ring
-3) A final note
+ 1) TCM Userspace Design
+ a) Background
+ b) Benefits
+ c) Design constraints
+ d) Implementation overview
+ i. Mailbox
+ ii. Command ring
+ iii. Data Area
+ e) Device discovery
+ f) Device events
+ g) Other contingencies
+ 2) Writing a user pass-through handler
+ a) Discovering and configuring TCMU uio devices
+ b) Waiting for events on the device(s)
+ c) Managing the command ring
+ 3) A final note
TCM Userspace Design
---------------------
+====================
TCM is another name for LIO, an in-kernel iSCSI target (server).
Existing TCM targets run in the kernel. TCMU (TCM in Userspace)
@@ -32,7 +37,8 @@ modules for file, block device, RAM or using another SCSI device as
storage. These are called "backstores" or "storage engines". These
built-in modules are implemented entirely as kernel code.
-Background:
+Background
+----------
In addition to modularizing the transport protocol used for carrying
SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes
@@ -60,7 +66,8 @@ kernel, another approach is to create a userspace pass-through
backstore for LIO, "TCMU".
-Benefits:
+Benefits
+--------
In addition to allowing relatively easy support for RBD and GLFS, TCMU
will also allow easier development of new backstores. TCMU combines
@@ -72,21 +79,25 @@ The disadvantage is there are more distinct components to configure, and
potentially to malfunction. This is unavoidable, but hopefully not
fatal if we're careful to keep things as simple as possible.
-Design constraints:
+Design constraints
+------------------
- Good performance: high throughput, low latency
- Cleanly handle if userspace:
+
1) never attaches
2) hangs
3) dies
4) misbehaves
+
- Allow future flexibility in user & kernel implementations
- Be reasonably memory-efficient
- Simple to configure & run
- Simple to write a userspace backend
-Implementation overview:
+Implementation overview
+-----------------------
The core of the TCMU interface is a memory region that is shared
between kernel and userspace. Within this region is: a control area
@@ -108,7 +119,8 @@ the region mapped at a different virtual address.
See target_core_user.h for the struct definitions.
-The Mailbox:
+The Mailbox
+-----------
The mailbox is always at the start of the shared memory region, and
contains a version, details about the starting offset and size of the
@@ -117,19 +129,27 @@ userspace (respectively) to put commands on the ring, and indicate
when the commands are completed.
version - 1 (userspace should abort if otherwise)
+
flags:
-- TCMU_MAILBOX_FLAG_CAP_OOOC: indicates out-of-order completion is
- supported. See "The Command Ring" for details.
-cmdr_off - The offset of the start of the command ring from the start
-of the memory region, to account for the mailbox size.
-cmdr_size - The size of the command ring. This does *not* need to be a
-power of two.
-cmd_head - Modified by the kernel to indicate when a command has been
-placed on the ring.
-cmd_tail - Modified by userspace to indicate when it has completed
-processing of a command.
+ - TCMU_MAILBOX_FLAG_CAP_OOOC:
+ indicates out-of-order completion is supported.
+ See "The Command Ring" for details.
-The Command Ring:
+cmdr_off
+ The offset of the start of the command ring from the start
+ of the memory region, to account for the mailbox size.
+cmdr_size
+ The size of the command ring. This does *not* need to be a
+ power of two.
+cmd_head
+ Modified by the kernel to indicate when a command has been
+ placed on the ring.
+cmd_tail
+ Modified by userspace to indicate when it has completed
+ processing of a command.
+
+The Command Ring
+----------------
Commands are placed on the ring by the kernel incrementing
mailbox.cmd_head by the size of the command, modulo cmdr_size, and
@@ -180,29 +200,31 @@ opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in
hdr.uflags, update cmd_tail, and proceed with processing additional
commands, if any.
-The Data Area:
+The Data Area
+-------------
This is shared-memory space after the command ring. The organization
of this area is not defined in the TCMU interface, and userspace
should access only the parts referenced by pending iovs.
-Device Discovery:
+Device Discovery
+----------------
Other devices may be using UIO besides TCMU. Unrelated user processes
may also be handling different sets of TCMU devices. TCMU userspace
processes must find their devices by scanning sysfs
class/uio/uio*/name. For TCMU devices, these names will be of the
-format:
+format::
-tcm-user/<hba_num>/<device_name>/<subtype>/<path>
+ tcm-user/<hba_num>/<device_name>/<subtype>/<path>
where "tcm-user" is common for all TCMU-backed UIO devices. <hba_num>
and <device_name> allow userspace to find the device's path in the
kernel target's configfs tree. Assuming the usual mount point, it is
-found at:
+found at::
-/sys/kernel/config/target/core/user_<hba_num>/<device_name>
+ /sys/kernel/config/target/core/user_<hba_num>/<device_name>
This location contains attributes such as "hw_block_size", that
userspace needs to know for correct operation.
@@ -214,15 +236,16 @@ configure the device, if needed. The name cannot contain ':', due to
LIO limitations.
For all devices so discovered, the user handler opens /dev/uioX and
-calls mmap():
+calls mmap()::
-mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
+ mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
where size must be equal to the value read from
/sys/class/uio/uioX/maps/map0/size.
-Device Events:
+Device Events
+-------------
If a new device is added or removed, a notification will be broadcast
over netlink, using a generic netlink family name of "TCM-USER" and a
@@ -233,7 +256,8 @@ the LIO device, so that after determining the device is supported
(based on subtype) it can take the appropriate action.
-Other contingencies:
+Other contingencies
+-------------------
Userspace handler process never attaches:
@@ -258,7 +282,7 @@ Userspace handler process is malicious:
Writing a user pass-through handler (with example code)
--------------------------------------------------------
+=======================================================
A user process handing a TCMU device must support the following:
@@ -277,103 +301,103 @@ TCMU is designed so that multiple unrelated processes can manage TCMU
devices separately. All handlers should make sure to only open their
devices, based opon a known subtype string.
-a) Discovering and configuring TCMU UIO devices:
+a) Discovering and configuring TCMU UIO devices::
-(error checking omitted for brevity)
+ /* error checking omitted for brevity */
-int fd, dev_fd;
-char buf[256];
-unsigned long long map_len;
-void *map;
+ int fd, dev_fd;
+ char buf[256];
+ unsigned long long map_len;
+ void *map;
-fd = open("/sys/class/uio/uio0/name", O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open("/sys/class/uio/uio0/name", O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-/* we only want uio devices whose name is a format we expect */
-if (strncmp(buf, "tcm-user", 8))
+ /* we only want uio devices whose name is a format we expect */
+ if (strncmp(buf, "tcm-user", 8))
exit(-1);
-/* Further checking for subtype also needed here */
+ /* Further checking for subtype also needed here */
-fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
-ret = read(fd, buf, sizeof(buf));
-close(fd);
-str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
+ fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
+ ret = read(fd, buf, sizeof(buf));
+ close(fd);
+ str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */
-map_len = strtoull(buf, NULL, 0);
+ map_len = strtoull(buf, NULL, 0);
-dev_fd = open("/dev/uio0", O_RDWR);
-map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
+ dev_fd = open("/dev/uio0", O_RDWR);
+ map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);
-b) Waiting for events on the device(s)
+ b) Waiting for events on the device(s)
-while (1) {
- char buf[4];
+ while (1) {
+ char buf[4];
- int ret = read(dev_fd, buf, 4); /* will block */
+ int ret = read(dev_fd, buf, 4); /* will block */
- handle_device_events(dev_fd, map);
-}
-
-
-c) Managing the command ring
-
-#include <linux/target_core_user.h>
-
-int handle_device_events(int fd, void *map)
-{
- struct tcmu_mailbox *mb = map;
- struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- int did_some_work = 0;
-
- /* Process events from cmd ring until we catch up with cmd_head */
- while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
-
- if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
- uint8_t *cdb = (void *)mb + ent->req.cdb_off;
- bool success = true;
+ handle_device_events(dev_fd, map);
+ }
- /* Handle command here. */
- printf("SCSI opcode: 0x%x\n", cdb[0]);
- /* Set response fields */
- if (success)
- ent->rsp.scsi_status = SCSI_NO_SENSE;
- else {
- /* Also fill in rsp->sense_buffer here */
- ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+c) Managing the command ring::
+
+ #include <linux/target_core_user.h>
+
+ int handle_device_events(int fd, void *map)
+ {
+ struct tcmu_mailbox *mb = map;
+ struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ int did_some_work = 0;
+
+ /* Process events from cmd ring until we catch up with cmd_head */
+ while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {
+
+ if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
+ uint8_t *cdb = (void *)mb + ent->req.cdb_off;
+ bool success = true;
+
+ /* Handle command here. */
+ printf("SCSI opcode: 0x%x\n", cdb[0]);
+
+ /* Set response fields */
+ if (success)
+ ent->rsp.scsi_status = SCSI_NO_SENSE;
+ else {
+ /* Also fill in rsp->sense_buffer here */
+ ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
+ }
+ }
+ else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
+ /* Tell the kernel we didn't handle unknown opcodes */
+ ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
+ }
+ else {
+ /* Do nothing for PAD entries except update cmd_tail */
+ }
+
+ /* update cmd_tail */
+ mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
+ ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
+ did_some_work = 1;
+ }
+
+ /* Notify the kernel that work has been finished */
+ if (did_some_work) {
+ uint32_t buf = 0;
+
+ write(fd, &buf, 4);
+ }
+
+ return 0;
}
- }
- else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
- /* Tell the kernel we didn't handle unknown opcodes */
- ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
- }
- else {
- /* Do nothing for PAD entries except update cmd_tail */
- }
-
- /* update cmd_tail */
- mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
- ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
- did_some_work = 1;
- }
-
- /* Notify the kernel that work has been finished */
- if (did_some_work) {
- uint32_t buf = 0;
-
- write(fd, &buf, 4);
- }
-
- return 0;
-}
A final note
-------------
+============
Please be careful to return codes as defined by the SCSI
specifications. These are different than some values defined in the
diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check
index 440227bb55a9..a4139a576726 100755
--- a/scripts/documentation-file-ref-check
+++ b/scripts/documentation-file-ref-check
@@ -124,7 +124,7 @@ while (<IN>) {
# Remove sched-pelt false-positive
next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
- # Discard some build examples from Documentation/target/tcm_mod_builder.txt
+ # Discard some build examples from Documentation/target/tcm_mod_builder.rst
next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
# Check if exists, evaluating wildcards
--
2.21.0
^ permalink raw reply related
* [PATCH v4 15/28] docs: mic: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sudeep Dutt, Ashutosh Dixit
In-Reply-To: <cover.1560361364.git.mchehab+samsung@kernel.org>
Convert Intel Many Integrated Core architecture docs to ReST.
The conversion is trivial: just add title and literal block
markups, and adjust some identation.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/mic/index.rst | 18 ++++++
.../{mic_overview.txt => mic_overview.rst} | 6 +-
.../{scif_overview.txt => scif_overview.rst} | 58 +++++++++++--------
3 files changed, 57 insertions(+), 25 deletions(-)
create mode 100644 Documentation/mic/index.rst
rename Documentation/mic/{mic_overview.txt => mic_overview.rst} (96%)
rename Documentation/mic/{scif_overview.txt => scif_overview.rst} (76%)
diff --git a/Documentation/mic/index.rst b/Documentation/mic/index.rst
new file mode 100644
index 000000000000..082fa8f6a260
--- /dev/null
+++ b/Documentation/mic/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=============================================
+Intel Many Integrated Core (MIC) architecture
+=============================================
+
+.. toctree::
+ :maxdepth: 1
+
+ mic_overview
+ scif_overview
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/mic/mic_overview.txt b/Documentation/mic/mic_overview.rst
similarity index 96%
rename from Documentation/mic/mic_overview.txt
rename to Documentation/mic/mic_overview.rst
index 074adbdf83a4..17d956bdaf7c 100644
--- a/Documentation/mic/mic_overview.txt
+++ b/Documentation/mic/mic_overview.rst
@@ -1,3 +1,7 @@
+======================================================
+Intel Many Integrated Core (MIC) architecture overview
+======================================================
+
An Intel MIC X100 device is a PCIe form factor add-in coprocessor
card based on the Intel Many Integrated Core (MIC) architecture
that runs a Linux OS. It is a PCIe endpoint in a platform and therefore
@@ -45,7 +49,7 @@ Here is a block diagram of the various components described above. The
virtio backends are situated on the host rather than the card given better
single threaded performance for the host compared to MIC, the ability of
the host to initiate DMA's to/from the card using the MIC DMA engine and
-the fact that the virtio block storage backend can only be on the host.
+the fact that the virtio block storage backend can only be on the host::
+----------+ | +----------+
| Card OS | | | Host OS |
diff --git a/Documentation/mic/scif_overview.txt b/Documentation/mic/scif_overview.rst
similarity index 76%
rename from Documentation/mic/scif_overview.txt
rename to Documentation/mic/scif_overview.rst
index 0a280d986731..4c8ad9e43706 100644
--- a/Documentation/mic/scif_overview.txt
+++ b/Documentation/mic/scif_overview.rst
@@ -1,3 +1,7 @@
+========================================
+Symmetric Communication Interface (SCIF)
+========================================
+
The Symmetric Communication Interface (SCIF (pronounced as skiff)) is a low
level communications API across PCIe currently implemented for MIC. Currently
SCIF provides inter-node communication within a single host platform, where a
@@ -8,8 +12,11 @@ is to deliver the maximum possible performance given the communication
abilities of the hardware. SCIF has been used to implement an offload compiler
runtime and OFED support for MPI implementations for MIC coprocessors.
-==== SCIF API Components ====
+SCIF API Components
+===================
+
The SCIF API has the following parts:
+
1. Connection establishment using a client server model
2. Byte stream messaging intended for short messages
3. Node enumeration to determine online nodes
@@ -28,9 +35,12 @@ can also register local memory which is followed by data transfer using either
DMA, CPU copies or remote memory mapping via mmap. SCIF supports both user and
kernel mode clients which are functionally equivalent.
-==== SCIF Performance for MIC ====
+SCIF Performance for MIC
+========================
+
DMA bandwidth comparison between the TCP (over ethernet over PCIe) stack versus
-SCIF shows the performance advantages of SCIF for HPC applications and runtimes.
+SCIF shows the performance advantages of SCIF for HPC applications and
+runtimes::
Comparison of TCP and SCIF based BW
@@ -66,33 +76,33 @@ space API similar to the kernel API in scif.h. The SCIF user space library
is distributed @ https://software.intel.com/en-us/mic-developer
Here is some pseudo code for an example of how two applications on two PCIe
-nodes would typically use the SCIF API:
+nodes would typically use the SCIF API::
-Process A (on node A) Process B (on node B)
+ Process A (on node A) Process B (on node B)
-/* get online node information */
-scif_get_node_ids(..) scif_get_node_ids(..)
-scif_open(..) scif_open(..)
-scif_bind(..) scif_bind(..)
-scif_listen(..)
-scif_accept(..) scif_connect(..)
-/* SCIF connection established */
+ /* get online node information */
+ scif_get_node_ids(..) scif_get_node_ids(..)
+ scif_open(..) scif_open(..)
+ scif_bind(..) scif_bind(..)
+ scif_listen(..)
+ scif_accept(..) scif_connect(..)
+ /* SCIF connection established */
-/* Send and receive short messages */
-scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
+ /* Send and receive short messages */
+ scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
-/* Register memory */
-scif_register(..) scif_register(..)
+ /* Register memory */
+ scif_register(..) scif_register(..)
-/* RDMA */
-scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
+ /* RDMA */
+ scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
-/* Fence DMAs */
-scif_fence_signal(..) scif_fence_signal(..)
+ /* Fence DMAs */
+ scif_fence_signal(..) scif_fence_signal(..)
-mmap(..) mmap(..)
+ mmap(..) mmap(..)
-/* Access remote registered memory */
+ /* Access remote registered memory */
-/* Close the endpoints */
-scif_close(..) scif_close(..)
+ /* Close the endpoints */
+ scif_close(..) scif_close(..)
--
2.21.0
^ permalink raw reply related
* [PATCH v4 20/28] docs: pps.txt: convert to ReST and rename to pps.rst
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rodolfo Giometti
In-Reply-To: <cover.1560361364.git.mchehab+samsung@kernel.org>
This file is already in a good shape: just its title and
adding some literal block markups is needed for it to be
part of the document.
While it has a small chapter with sysfs stuff, most of
the document is focused on driver development.
As it describes a kernel API, move it to the driver-api
directory.
In order to avoid conflicts, let's add an :orphan: tag
to it, to be removed when added to the driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rodolfo Giometti <giometti@enneenne.com>
---
.../{pps/pps.txt => driver-api/pps.rst} | 67 ++++++++++---------
MAINTAINERS | 2 +-
2 files changed, 36 insertions(+), 33 deletions(-)
rename Documentation/{pps/pps.txt => driver-api/pps.rst} (89%)
diff --git a/Documentation/pps/pps.txt b/Documentation/driver-api/pps.rst
similarity index 89%
rename from Documentation/pps/pps.txt
rename to Documentation/driver-api/pps.rst
index 99f5d8c4c652..1456d2c32ebd 100644
--- a/Documentation/pps/pps.txt
+++ b/Documentation/driver-api/pps.rst
@@ -1,8 +1,10 @@
+:orphan:
- PPS - Pulse Per Second
- ----------------------
+======================
+PPS - Pulse Per Second
+======================
-(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
+Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
@@ -88,7 +90,7 @@ Coding example
--------------
To register a PPS source into the kernel you should define a struct
-pps_source_info as follows:
+pps_source_info as follows::
static struct pps_source_info pps_ktimer_info = {
.name = "ktimer",
@@ -101,12 +103,12 @@ pps_source_info as follows:
};
and then calling the function pps_register_source() in your
-initialization routine as follows:
+initialization routine as follows::
source = pps_register_source(&pps_ktimer_info,
PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
-The pps_register_source() prototype is:
+The pps_register_source() prototype is::
int pps_register_source(struct pps_source_info *info, int default_params)
@@ -118,7 +120,7 @@ pps_source_info which describe the capabilities of the driver).
Once you have registered a new PPS source into the system you can
signal an assert event (for example in the interrupt handler routine)
-just using:
+just using::
pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
@@ -134,13 +136,13 @@ Please see the file drivers/pps/clients/pps-ktimer.c for example code.
SYSFS support
-------------
-If the SYSFS filesystem is enabled in the kernel it provides a new class:
+If the SYSFS filesystem is enabled in the kernel it provides a new class::
$ ls /sys/class/pps/
pps0/ pps1/ pps2/
Every directory is the ID of a PPS sources defined in the system and
-inside you find several files:
+inside you find several files::
$ ls -F /sys/class/pps/pps0/
assert dev mode path subsystem@
@@ -148,7 +150,7 @@ inside you find several files:
Inside each "assert" and "clear" file you can find the timestamp and a
-sequence number:
+sequence number::
$ cat /sys/class/pps/pps0/assert
1170026870.983207967#8
@@ -175,11 +177,11 @@ and the userland tools available in your distribution's pps-tools package,
http://linuxpps.org , or https://github.com/redlab-i/pps-tools.
Once you have enabled the compilation of pps-ktimer just modprobe it (if
-not statically compiled):
+not statically compiled)::
# modprobe pps-ktimer
-and the run ppstest as follow:
+and the run ppstest as follow::
$ ./ppstest /dev/pps1
trying PPS source "/dev/pps1"
@@ -204,26 +206,27 @@ nor affordable. The cheap way is to load a PPS generator on one of the
computers (master) and PPS clients on others (slaves), and use very simple
cables to deliver signals using parallel ports, for example.
-Parallel port cable pinout:
-pin name master slave
-1 STROBE *------ *
-2 D0 * | *
-3 D1 * | *
-4 D2 * | *
-5 D3 * | *
-6 D4 * | *
-7 D5 * | *
-8 D6 * | *
-9 D7 * | *
-10 ACK * ------*
-11 BUSY * *
-12 PE * *
-13 SEL * *
-14 AUTOFD * *
-15 ERROR * *
-16 INIT * *
-17 SELIN * *
-18-25 GND *-----------*
+Parallel port cable pinout::
+
+ pin name master slave
+ 1 STROBE *------ *
+ 2 D0 * | *
+ 3 D1 * | *
+ 4 D2 * | *
+ 5 D3 * | *
+ 6 D4 * | *
+ 7 D5 * | *
+ 8 D6 * | *
+ 9 D7 * | *
+ 10 ACK * ------*
+ 11 BUSY * *
+ 12 PE * *
+ 13 SEL * *
+ 14 AUTOFD * *
+ 15 ERROR * *
+ 16 INIT * *
+ 17 SELIN * *
+ 18-25 GND *-----------*
Please note that parallel port interrupt occurs only on high->low transition,
so it is used for PPS assert edge. PPS clear edge can be determined only
diff --git a/MAINTAINERS b/MAINTAINERS
index b3746e7b5652..5c5714eddde4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12709,7 +12709,7 @@ M: Rodolfo Giometti <giometti@enneenne.com>
W: http://wiki.enneenne.com/index.php/LinuxPPS_support
L: linuxpps@ml.enneenne.com (subscribers-only)
S: Maintained
-F: Documentation/pps/
+F: Documentation/driver-api/pps.rst
F: Documentation/devicetree/bindings/pps/pps-gpio.txt
F: Documentation/ABI/testing/sysfs-pps
F: drivers/pps/
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v4 24/28] docs: timers: convert docs to ReST and rename to *.rst
From: Mark Brown @ 2019-06-12 18:25 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Thomas Gleixner, Clemens Ladisch,
Antti Palosaari, Liam Girdwood, Andy Whitcroft, Joe Perches,
Jaroslav Kysela, Takashi Iwai, alsa-devel
In-Reply-To: <30e605cd5a295c42c39523d88b4c57298c5a6f1d.1560361364.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 288 bytes --]
On Wed, Jun 12, 2019 at 02:53:00PM -0300, Mauro Carvalho Chehab wrote:
> The conversion here is really trivial: just a bunch of title
> markups and very few puntual changes is enough to make it to
> be parsed by Sphinx and generate a nice html.
Acked-by: Mark Brown <broonie@kernel.org>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply
* [PATCH v1 11/31] docs: memory-devices: convert ti-emif.txt to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Prepare this file to be moved to a kernel book by converting
it to ReST format and renaming it to ti-emif.rst.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{ti-emif.txt => ti-emif.rst} | 27 ++++++++++++-------
1 file changed, 17 insertions(+), 10 deletions(-)
rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%)
diff --git a/Documentation/memory-devices/ti-emif.txt b/Documentation/memory-devices/ti-emif.rst
similarity index 81%
rename from Documentation/memory-devices/ti-emif.txt
rename to Documentation/memory-devices/ti-emif.rst
index f4ad9a7d0f4b..c9242294e63c 100644
--- a/Documentation/memory-devices/ti-emif.txt
+++ b/Documentation/memory-devices/ti-emif.rst
@@ -1,20 +1,24 @@
-TI EMIF SDRAM Controller Driver:
+:orphan:
+
+===============================
+TI EMIF SDRAM Controller Driver
+===============================
Author
-========
+======
Aneesh V <aneesh@ti.com>
Location
-============
+========
driver/memory/emif.c
Supported SoCs:
-===================
+===============
TI OMAP44xx
TI OMAP54xx
Menuconfig option:
-==========================
+==================
Device Drivers
Memory devices
Texas Instruments EMIF driver
@@ -29,10 +33,11 @@ functions of the driver includes re-configuring AC timing
parameters and other settings during frequency, voltage and
temperature changes
-Platform Data (see include/linux/platform_data/emif_plat.h):
-=====================================================================
+Platform Data (see include/linux/platform_data/emif_plat.h)
+===========================================================
DDR device details and other board dependent and SoC dependent
information can be passed through platform data (struct emif_platform_data)
+
- DDR device details: 'struct ddr_device_info'
- Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck'
- Custom configurations: customizable policy options through
@@ -40,17 +45,19 @@ information can be passed through platform data (struct emif_platform_data)
- IP revision
- PHY type
-Interface to the external world:
-================================
+Interface to the external world
+===============================
EMIF driver registers notifiers for voltage and frequency changes
affecting EMIF and takes appropriate actions when these are invoked.
+
- freq_pre_notify_handling()
- freq_post_notify_handling()
- volt_notify_handling()
Debugfs
-========
+=======
The driver creates two debugfs entries per device.
+
- regcache_dump : dump of register values calculated and saved for all
frequencies used so far.
- mr4 : last polled value of MR4 register in the LPDDR2 device. MR4
--
2.21.0
^ permalink raw reply related
* [PATCH v1 14/31] docs: nvmem: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
In order to be able to add it into a doc book, we need first
convert it to ReST.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- mark literal blocks;
- adjust title markups.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 ++++++++++---------
1 file changed, 59 insertions(+), 53 deletions(-)
rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)
diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.rst
similarity index 62%
rename from Documentation/nvmem/nvmem.txt
rename to Documentation/nvmem/nvmem.rst
index fc2fe4b18655..3866b6e066d5 100644
--- a/Documentation/nvmem/nvmem.txt
+++ b/Documentation/nvmem/nvmem.rst
@@ -1,5 +1,10 @@
- NVMEM SUBSYSTEM
- Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
+:orphan:
+
+===============
+NVMEM Subsystem
+===============
+
+ Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
This document explains the NVMEM Framework along with the APIs provided,
and how to use it.
@@ -40,54 +45,54 @@ nvmem_device pointer.
nvmem_unregister(nvmem) is used to unregister a previously registered provider.
-For example, a simple qfprom case:
+For example, a simple qfprom case::
-static struct nvmem_config econfig = {
+ static struct nvmem_config econfig = {
.name = "qfprom",
.owner = THIS_MODULE,
-};
+ };
-static int qfprom_probe(struct platform_device *pdev)
-{
+ static int qfprom_probe(struct platform_device *pdev)
+ {
...
econfig.dev = &pdev->dev;
nvmem = nvmem_register(&econfig);
...
-}
+ }
It is mandatory that the NVMEM provider has a regmap associated with its
struct device. Failure to do would return error code from nvmem_register().
Users of board files can define and register nvmem cells using the
-nvmem_cell_table struct:
+nvmem_cell_table struct::
-static struct nvmem_cell_info foo_nvmem_cells[] = {
+ static struct nvmem_cell_info foo_nvmem_cells[] = {
{
.name = "macaddr",
.offset = 0x7f00,
.bytes = ETH_ALEN,
}
-};
+ };
-static struct nvmem_cell_table foo_nvmem_cell_table = {
+ static struct nvmem_cell_table foo_nvmem_cell_table = {
.nvmem_name = "i2c-eeprom",
.cells = foo_nvmem_cells,
.ncells = ARRAY_SIZE(foo_nvmem_cells),
-};
+ };
-nvmem_add_cell_table(&foo_nvmem_cell_table);
+ nvmem_add_cell_table(&foo_nvmem_cell_table);
Additionally it is possible to create nvmem cell lookup entries and register
-them with the nvmem framework from machine code as shown in the example below:
+them with the nvmem framework from machine code as shown in the example below::
-static struct nvmem_cell_lookup foo_nvmem_lookup = {
+ static struct nvmem_cell_lookup foo_nvmem_lookup = {
.nvmem_name = "i2c-eeprom",
.cell_name = "macaddr",
.dev_id = "foo_mac.0",
.con_id = "mac-address",
-};
+ };
-nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
+ nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
NVMEM Consumers
+++++++++++++++
@@ -99,43 +104,43 @@ read from and to NVMEM.
=================================
NVMEM cells are the data entries/fields in the NVMEM.
-The NVMEM framework provides 3 APIs to read/write NVMEM cells.
+The NVMEM framework provides 3 APIs to read/write NVMEM cells::
-struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
-struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
+ struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
+ struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+ void nvmem_cell_put(struct nvmem_cell *cell);
+ void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
-int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
+ void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
+ int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
-*nvmem_cell_get() apis will get a reference to nvmem cell for a given id,
+`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
and nvmem_cell_read/write() can then read or write to the cell.
-Once the usage of the cell is finished the consumer should call *nvmem_cell_put()
-to free all the allocation memory for the cell.
+Once the usage of the cell is finished the consumer should call
+`*nvmem_cell_put()` to free all the allocation memory for the cell.
4. Direct NVMEM device based consumer APIs
==========================================
In some instances it is necessary to directly read/write the NVMEM.
-To facilitate such consumers NVMEM framework provides below apis.
+To facilitate such consumers NVMEM framework provides below apis::
-struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
-struct nvmem_device *devm_nvmem_device_get(struct device *dev,
+ struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
+ struct nvmem_device *devm_nvmem_device_get(struct device *dev,
const char *name);
-void nvmem_device_put(struct nvmem_device *nvmem);
-int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
+ void nvmem_device_put(struct nvmem_device *nvmem);
+ int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf);
-int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
+ int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf);
-int nvmem_device_cell_read(struct nvmem_device *nvmem,
+ int nvmem_device_cell_read(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf);
-int nvmem_device_cell_write(struct nvmem_device *nvmem,
+ int nvmem_device_cell_write(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf);
Before the consumers can read/write NVMEM directly, it should get hold
-of nvmem_controller from one of the *nvmem_device_get() api.
+of nvmem_controller from one of the `*nvmem_device_get()` api.
The difference between these apis and cell based apis is that these apis always
take nvmem_device as parameter.
@@ -145,12 +150,12 @@ take nvmem_device as parameter.
When a consumer no longer needs the NVMEM, it has to release the reference
to the NVMEM it has obtained using the APIs mentioned in the above section.
-The NVMEM framework provides 2 APIs to release a reference to the NVMEM.
+The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void nvmem_device_put(struct nvmem_device *nvmem);
-void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
+ void nvmem_cell_put(struct nvmem_cell *cell);
+ void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+ void nvmem_device_put(struct nvmem_device *nvmem);
+ void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
Both these APIs are used to release a reference to the NVMEM and
devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
@@ -162,20 +167,21 @@ Userspace
6. Userspace binary interface
==============================
-Userspace can read/write the raw NVMEM file located at
-/sys/bus/nvmem/devices/*/nvmem
+Userspace can read/write the raw NVMEM file located at::
-ex:
+ /sys/bus/nvmem/devices/*/nvmem
-hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ex::
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-*
-00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-...
-*
-0001000
+ hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ ...
+ *
+ 0001000
7. DeviceTree Binding
=====================
--
2.21.0
^ permalink raw reply related
* [PATCH v1 13/31] docs: bus-devices: ti-gpmc.rst: convert it to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
In order to be able to add this file to a book, it needs
first to be converted to ReST and renamed.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../bus-devices/{ti-gpmc.txt => ti-gpmc.rst} | 159 ++++++++++++------
1 file changed, 108 insertions(+), 51 deletions(-)
rename Documentation/bus-devices/{ti-gpmc.txt => ti-gpmc.rst} (58%)
diff --git a/Documentation/bus-devices/ti-gpmc.txt b/Documentation/bus-devices/ti-gpmc.rst
similarity index 58%
rename from Documentation/bus-devices/ti-gpmc.txt
rename to Documentation/bus-devices/ti-gpmc.rst
index cc9ce57e0a26..87c366e418be 100644
--- a/Documentation/bus-devices/ti-gpmc.txt
+++ b/Documentation/bus-devices/ti-gpmc.rst
@@ -1,8 +1,12 @@
-GPMC (General Purpose Memory Controller):
-=========================================
+:orphan:
+
+========================================
+GPMC (General Purpose Memory Controller)
+========================================
GPMC is an unified memory controller dedicated to interfacing external
memory devices like
+
* Asynchronous SRAM like memories and application specific integrated
circuit devices.
* Asynchronous, synchronous, and page mode burst NOR flash devices
@@ -48,75 +52,128 @@ most of the datasheets & hardware (to be exact none of those supported
in mainline having custom timing routine) and by simulation.
gpmc timing dependency on peripheral timings:
+
[<gpmc_timing>: <peripheral timing1>, <peripheral timing2> ...]
1. common
-cs_on: t_ceasu
-adv_on: t_avdasu, t_ceavd
+
+cs_on:
+ t_ceasu
+adv_on:
+ t_avdasu, t_ceavd
2. sync common
-sync_clk: clk
-page_burst_access: t_bacc
-clk_activation: t_ces, t_avds
+
+sync_clk:
+ clk
+page_burst_access:
+ t_bacc
+clk_activation:
+ t_ces, t_avds
3. read async muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu, t_aavdh
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+ t_avdp_r
+oe_on:
+ t_oeasu, t_aavdh
+access:
+ t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+ t_rd_cycle, t_cez_r, t_oez
4. read async non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+ t_avdp_r
+oe_on:
+ t_oeasu
+access:
+ t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+ t_rd_cycle, t_cez_r, t_oez
5. read sync muxed
-adv_rd_off: t_avdp_r, t_avdh
-oe_on: t_oeasu, t_ach, cyc_aavdh_oe
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+ t_avdp_r, t_avdh
+oe_on:
+ t_oeasu, t_ach, cyc_aavdh_oe
+access:
+ t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+ t_cez_r, t_oez, t_ce_rdyz
6. read sync non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+ t_avdp_r
+oe_on:
+ t_oeasu
+access:
+ t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+ t_cez_r, t_oez, t_ce_rdyz
7. write async muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_aavdh, cyc_aavhd_we
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+ t_avdp_w
+we_on, wr_data_mux_bus:
+ t_weasu, t_aavdh, cyc_aavhd_we
+we_off:
+ t_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_wr_cycle
8. write async non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+ t_avdp_w
+we_on, wr_data_mux_bus:
+ t_weasu
+we_off:
+ t_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_wr_cycle
9. write sync muxed
-adv_wr_off: t_avdp_w, t_avdh
-we_on, wr_data_mux_bus: t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
+
+adv_wr_off:
+ t_avdp_w, t_avdh
+we_on, wr_data_mux_bus:
+ t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
+we_off:
+ t_wpl, cyc_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_ce_rdyz
10. write sync non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_rdyo
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
+adv_wr_off:
+ t_avdp_w
+we_on, wr_data_mux_bus:
+ t_weasu, t_rdyo
+we_off:
+ t_wpl, cyc_wpl
+cs_wr_off:
+ t_wph
+wr_cycle:
+ t_cez_w, t_ce_rdyz
-Note: Many of gpmc timings are dependent on other gpmc timings (a few
-gpmc timings purely dependent on other gpmc timings, a reason that
-some of the gpmc timings are missing above), and it will result in
-indirect dependency of peripheral timings to gpmc timings other than
-mentioned above, refer timing routine for more details. To know what
-these peripheral timings correspond to, please see explanations in
-struct gpmc_device_timings definition. And for gpmc timings refer
-IP details (link above).
+
+Note:
+ Many of gpmc timings are dependent on other gpmc timings (a few
+ gpmc timings purely dependent on other gpmc timings, a reason that
+ some of the gpmc timings are missing above), and it will result in
+ indirect dependency of peripheral timings to gpmc timings other than
+ mentioned above, refer timing routine for more details. To know what
+ these peripheral timings correspond to, please see explanations in
+ struct gpmc_device_timings definition. And for gpmc timings refer
+ IP details (link above).
--
2.21.0
^ permalink raw reply related
* [PATCH v1 26/31] docs: nfc: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the nfc documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/nfc/index.rst | 11 ++
.../nfc/{nfc-hci.txt => nfc-hci.rst} | 163 ++++++++++--------
.../nfc/{nfc-pn544.txt => nfc-pn544.rst} | 6 +-
3 files changed, 107 insertions(+), 73 deletions(-)
create mode 100644 Documentation/nfc/index.rst
rename Documentation/nfc/{nfc-hci.txt => nfc-hci.rst} (71%)
rename Documentation/nfc/{nfc-pn544.txt => nfc-pn544.rst} (82%)
diff --git a/Documentation/nfc/index.rst b/Documentation/nfc/index.rst
new file mode 100644
index 000000000000..4f4947fce80d
--- /dev/null
+++ b/Documentation/nfc/index.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+========================
+Near Field Communication
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ nfc-hci
+ nfc-pn544
diff --git a/Documentation/nfc/nfc-hci.txt b/Documentation/nfc/nfc-hci.rst
similarity index 71%
rename from Documentation/nfc/nfc-hci.txt
rename to Documentation/nfc/nfc-hci.rst
index 0dc078cab972..eb8a1a14e919 100644
--- a/Documentation/nfc/nfc-hci.txt
+++ b/Documentation/nfc/nfc-hci.rst
@@ -1,7 +1,9 @@
+========================
HCI backend for NFC Core
+========================
-Author: Eric Lapuyade, Samuel Ortiz
-Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
+- Author: Eric Lapuyade, Samuel Ortiz
+- Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
General
-------
@@ -24,12 +26,13 @@ HCI events can also be received from the host controller. They will be handled
and a translation will be forwarded to NFC Core as needed. There are hooks to
let the HCI driver handle proprietary events or override standard behavior.
HCI uses 2 execution contexts:
+
- one for executing commands : nfc_hci_msg_tx_work(). Only one command
-can be executing at any given moment.
+ can be executing at any given moment.
- one for dispatching received events and commands : nfc_hci_msg_rx_work().
-HCI Session initialization:
----------------------------
+HCI Session initialization
+--------------------------
The Session initialization is an HCI standard which must unfortunately
support proprietary gates. This is the reason why the driver will pass a list
@@ -58,9 +61,9 @@ HCI Management
--------------
A driver would normally register itself with HCI and provide the following
-entry points:
+entry points::
-struct nfc_hci_ops {
+ struct nfc_hci_ops {
int (*open)(struct nfc_hci_dev *hdev);
void (*close)(struct nfc_hci_dev *hdev);
int (*hci_ready) (struct nfc_hci_dev *hdev);
@@ -82,38 +85,38 @@ struct nfc_hci_ops {
struct nfc_target *target);
int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event,
struct sk_buff *skb);
-};
+ };
- open() and close() shall turn the hardware on and off.
- hci_ready() is an optional entry point that is called right after the hci
-session has been set up. The driver can use it to do additional initialization
-that must be performed using HCI commands.
+ session has been set up. The driver can use it to do additional initialization
+ that must be performed using HCI commands.
- xmit() shall simply write a frame to the physical link.
- start_poll() is an optional entrypoint that shall set the hardware in polling
-mode. This must be implemented only if the hardware uses proprietary gates or a
-mechanism slightly different from the HCI standard.
+ mode. This must be implemented only if the hardware uses proprietary gates or a
+ mechanism slightly different from the HCI standard.
- dep_link_up() is called after a p2p target has been detected, to finish
-the p2p connection setup with hardware parameters that need to be passed back
-to nfc core.
+ the p2p connection setup with hardware parameters that need to be passed back
+ to nfc core.
- dep_link_down() is called to bring the p2p link down.
- target_from_gate() is an optional entrypoint to return the nfc protocols
-corresponding to a proprietary gate.
+ corresponding to a proprietary gate.
- complete_target_discovered() is an optional entry point to let the driver
-perform additional proprietary processing necessary to auto activate the
-discovered target.
+ perform additional proprietary processing necessary to auto activate the
+ discovered target.
- im_transceive() must be implemented by the driver if proprietary HCI commands
-are required to send data to the tag. Some tag types will require custom
-commands, others can be written to using the standard HCI commands. The driver
-can check the tag type and either do proprietary processing, or return 1 to ask
-for standard processing. The data exchange command itself must be sent
-asynchronously.
+ are required to send data to the tag. Some tag types will require custom
+ commands, others can be written to using the standard HCI commands. The driver
+ can check the tag type and either do proprietary processing, or return 1 to ask
+ for standard processing. The data exchange command itself must be sent
+ asynchronously.
- tm_send() is called to send data in the case of a p2p connection
- check_presence() is an optional entry point that will be called regularly
-by the core to check that an activated tag is still in the field. If this is
-not implemented, the core will not be able to push tag_lost events to the user
-space
+ by the core to check that an activated tag is still in the field. If this is
+ not implemented, the core will not be able to push tag_lost events to the user
+ space
- event_received() is called to handle an event coming from the chip. Driver
-can handle the event or return 1 to let HCI attempt standard processing.
+ can handle the event or return 1 to let HCI attempt standard processing.
On the rx path, the driver is responsible to push incoming HCP frames to HCI
using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
@@ -122,20 +125,23 @@ This must be done from a context that can sleep.
PHY Management
--------------
-The physical link (i2c, ...) management is defined by the following structure:
+The physical link (i2c, ...) management is defined by the following structure::
-struct nfc_phy_ops {
+ struct nfc_phy_ops {
int (*write)(void *dev_id, struct sk_buff *skb);
int (*enable)(void *dev_id);
void (*disable)(void *dev_id);
-};
+ };
-enable(): turn the phy on (power on), make it ready to transfer data
-disable(): turn the phy off
-write(): Send a data frame to the chip. Note that to enable higher
-layers such as an llc to store the frame for re-emission, this function must
-not alter the skb. It must also not return a positive result (return 0 for
-success, negative for failure).
+enable():
+ turn the phy on (power on), make it ready to transfer data
+disable():
+ turn the phy off
+write():
+ Send a data frame to the chip. Note that to enable higher
+ layers such as an llc to store the frame for re-emission, this
+ function must not alter the skb. It must also not return a positive
+ result (return 0 for success, negative for failure).
Data coming from the chip shall be sent directly to nfc_hci_recv_frame().
@@ -145,9 +151,9 @@ LLC
Communication between the CPU and the chip often requires some link layer
protocol. Those are isolated as modules managed by the HCI layer. There are
currently two modules : nop (raw transfert) and shdlc.
-A new llc must implement the following functions:
+A new llc must implement the following functions::
-struct nfc_llc_ops {
+ struct nfc_llc_ops {
void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv,
rcv_to_hci_t rcv_to_hci, int tx_headroom,
int tx_tailroom, int *rx_headroom, int *rx_tailroom,
@@ -157,17 +163,25 @@ struct nfc_llc_ops {
int (*stop) (struct nfc_llc *llc);
void (*rcv_from_drv) (struct nfc_llc *llc, struct sk_buff *skb);
int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb);
-};
+ };
-- init() : allocate and init your private storage
-- deinit() : cleanup
-- start() : establish the logical connection
-- stop () : terminate the logical connection
-- rcv_from_drv() : handle data coming from the chip, going to HCI
-- xmit_from_hci() : handle data sent by HCI, going to the chip
+init():
+ allocate and init your private storage
+deinit():
+ cleanup
+start():
+ establish the logical connection
+stop ():
+ terminate the logical connection
+rcv_from_drv():
+ handle data coming from the chip, going to HCI
+xmit_from_hci():
+ handle data sent by HCI, going to the chip
The llc must be registered with nfc before it can be used. Do that by
-calling nfc_llc_register(const char *name, struct nfc_llc_ops *ops);
+calling::
+
+ nfc_llc_register(const char *name, struct nfc_llc_ops *ops);
Again, note that the llc does not handle the physical link. It is thus very
easy to mix any physical link with any llc for a given chip driver.
@@ -187,26 +201,32 @@ fast, cannot sleep. sends incoming frames to HCI where they are passed to
the current llc. In case of shdlc, the frame is queued in shdlc rx queue.
- SHDLC State Machine worker (SMW)
-Only when llc_shdlc is used: handles shdlc rx & tx queues.
-Dispatches HCI cmd responses.
+
+ Only when llc_shdlc is used: handles shdlc rx & tx queues.
+
+ Dispatches HCI cmd responses.
- HCI Tx Cmd worker (MSGTXWQ)
-Serializes execution of HCI commands. Completes execution in case of response
-timeout.
+
+ Serializes execution of HCI commands.
+
+ Completes execution in case of response timeout.
- HCI Rx worker (MSGRXWQ)
-Dispatches incoming HCI commands or events.
+
+ Dispatches incoming HCI commands or events.
- Syscall context from a userspace call (SYSCALL)
-Any entrypoint in HCI called from NFC Core
+
+ Any entrypoint in HCI called from NFC Core
Workflow executing an HCI command (using shdlc)
-----------------------------------------------
Executing an HCI command can easily be performed synchronously using the
-following API:
+following API::
-int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd,
+ int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd,
const u8 *param, size_t param_len, struct sk_buff **skb)
The API must be invoked from a context that can sleep. Most of the time, this
@@ -234,11 +254,11 @@ waiting command execution. Response processing involves invoking the completion
callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
The completion callback will then wake the syscall context.
-It is also possible to execute the command asynchronously using this API:
+It is also possible to execute the command asynchronously using this API::
-static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,
- const u8 *param, size_t param_len,
- data_exchange_cb_t cb, void *cb_context)
+ static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,
+ const u8 *param, size_t param_len,
+ data_exchange_cb_t cb, void *cb_context)
The workflow is the same, except that the API call returns immediately, and
the callback will be called with the result from the SMW context.
@@ -268,23 +288,24 @@ went wrong below and know that expected events will probably never happen.
Handling of these errors is done as follows:
- driver (pn544) fails to deliver an incoming frame: it stores the error such
-that any subsequent call to the driver will result in this error. Then it calls
-the standard nfc_shdlc_recv_frame() with a NULL argument to report the problem
-above. shdlc stores a EREMOTEIO sticky status, which will trigger SMW to
-report above in turn.
+ that any subsequent call to the driver will result in this error. Then it
+ calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the
+ problem above. shdlc stores a EREMOTEIO sticky status, which will trigger
+ SMW to report above in turn.
- SMW is basically a background thread to handle incoming and outgoing shdlc
-frames. This thread will also check the shdlc sticky status and report to HCI
-when it discovers it is not able to run anymore because of an unrecoverable
-error that happened within shdlc or below. If the problem occurs during shdlc
-connection, the error is reported through the connect completion.
+ frames. This thread will also check the shdlc sticky status and report to HCI
+ when it discovers it is not able to run anymore because of an unrecoverable
+ error that happened within shdlc or below. If the problem occurs during shdlc
+ connection, the error is reported through the connect completion.
- HCI: if an internal HCI error happens (frame is lost), or HCI is reported an
-error from a lower layer, HCI will either complete the currently executing
-command with that error, or notify NFC Core directly if no command is executing.
+ error from a lower layer, HCI will either complete the currently executing
+ command with that error, or notify NFC Core directly if no command is
+ executing.
- NFC Core: when NFC Core is notified of an error from below and polling is
-active, it will send a tag discovered event with an empty tag list to the user
-space to let it know that the poll operation will never be able to detect a tag.
-If polling is not active and the error was sticky, lower levels will return it
-at next invocation.
+ active, it will send a tag discovered event with an empty tag list to the user
+ space to let it know that the poll operation will never be able to detect a
+ tag. If polling is not active and the error was sticky, lower levels will
+ return it at next invocation.
diff --git a/Documentation/nfc/nfc-pn544.txt b/Documentation/nfc/nfc-pn544.rst
similarity index 82%
rename from Documentation/nfc/nfc-pn544.txt
rename to Documentation/nfc/nfc-pn544.rst
index b36ca14ca2d6..6b2d8aae0c4e 100644
--- a/Documentation/nfc/nfc-pn544.txt
+++ b/Documentation/nfc/nfc-pn544.rst
@@ -1,5 +1,7 @@
-Kernel driver for the NXP Semiconductors PN544 Near Field
-Communication chip
+============================================================================
+Kernel driver for the NXP Semiconductors PN544 Near Field Communication chip
+============================================================================
+
General
-------
--
2.21.0
^ permalink raw reply related
* [PATCH v1 25/31] docs: namespaces: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the namespaces documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
There are two upper case file names. Rename them to
lower case, as we're working to avoid upper case file
names at Documentation.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...{compatibility-list.txt => compatibility-list.rst} | 10 +++++++---
Documentation/namespaces/index.rst | 11 +++++++++++
.../{resource-control.txt => resource-control.rst} | 4 ++++
3 files changed, 22 insertions(+), 3 deletions(-)
rename Documentation/namespaces/{compatibility-list.txt => compatibility-list.rst} (86%)
create mode 100644 Documentation/namespaces/index.rst
rename Documentation/namespaces/{resource-control.txt => resource-control.rst} (89%)
diff --git a/Documentation/namespaces/compatibility-list.txt b/Documentation/namespaces/compatibility-list.rst
similarity index 86%
rename from Documentation/namespaces/compatibility-list.txt
rename to Documentation/namespaces/compatibility-list.rst
index defc5589bfcd..318800b2a943 100644
--- a/Documentation/namespaces/compatibility-list.txt
+++ b/Documentation/namespaces/compatibility-list.rst
@@ -1,4 +1,6 @@
- Namespaces compatibility list
+=============================
+Namespaces compatibility list
+=============================
This document contains the information about the problems user
may have when creating tasks living in different namespaces.
@@ -7,13 +9,16 @@ Here's the summary. This matrix shows the known problems, that
occur when tasks share some namespace (the columns) while living
in different other namespaces (the rows):
- UTS IPC VFS PID User Net
+==== === === === === ==== ===
+- UTS IPC VFS PID User Net
+==== === === === === ==== ===
UTS X
IPC X 1
VFS X
PID 1 1 X
User 2 2 X
Net X
+==== === === === === ==== ===
1. Both the IPC and the PID namespaces provide IDs to address
object inside the kernel. E.g. semaphore with IPCID or
@@ -36,4 +41,3 @@ Net X
even having equal UIDs.
But currently this is not so.
-
diff --git a/Documentation/namespaces/index.rst b/Documentation/namespaces/index.rst
new file mode 100644
index 000000000000..bf40625dd11a
--- /dev/null
+++ b/Documentation/namespaces/index.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+==========
+Namespaces
+==========
+
+.. toctree::
+ :maxdepth: 1
+
+ compatibility-list
+ resource-control
diff --git a/Documentation/namespaces/resource-control.txt b/Documentation/namespaces/resource-control.rst
similarity index 89%
rename from Documentation/namespaces/resource-control.txt
rename to Documentation/namespaces/resource-control.rst
index abc13c394738..369556e00f0c 100644
--- a/Documentation/namespaces/resource-control.txt
+++ b/Documentation/namespaces/resource-control.rst
@@ -1,3 +1,7 @@
+===========================
+Namespaces research control
+===========================
+
There are a lot of kinds of objects in the kernel that don't have
individual limits or that have limits that are ineffective when a set
of processes is allowed to switch user ids. With user namespaces
--
2.21.0
^ permalink raw reply related
* [PATCH v1 08/31] docs: early-userspace: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
The two files there describes a Kernel API feature, used to
support early userspace stuff. Prepare for moving them to
the kernel API book by converting to ReST format.
The conversion itself was quite trivial: just add/mark a few
titles as such, add a literal block markup, add a table markup
and a few blank lines, in order to make Sphinx to properly parse it.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{buffer-format.txt => buffer-format.rst} | 19 +++++++++++++------
.../{README => early_userspace_support.rst} | 3 +++
Documentation/early-userspace/index.rst | 18 ++++++++++++++++++
Documentation/filesystems/nfs/nfsroot.txt | 2 +-
.../filesystems/ramfs-rootfs-initramfs.txt | 4 ++--
usr/Kconfig | 2 +-
6 files changed, 38 insertions(+), 10 deletions(-)
rename Documentation/early-userspace/{buffer-format.txt => buffer-format.rst} (91%)
rename Documentation/early-userspace/{README => early_userspace_support.rst} (99%)
create mode 100644 Documentation/early-userspace/index.rst
diff --git a/Documentation/early-userspace/buffer-format.txt b/Documentation/early-userspace/buffer-format.rst
similarity index 91%
rename from Documentation/early-userspace/buffer-format.txt
rename to Documentation/early-userspace/buffer-format.rst
index e1fd7f9dad16..7f74e301fdf3 100644
--- a/Documentation/early-userspace/buffer-format.txt
+++ b/Documentation/early-userspace/buffer-format.rst
@@ -1,8 +1,10 @@
- initramfs buffer format
- -----------------------
+=======================
+initramfs buffer format
+=======================
- Al Viro, H. Peter Anvin
- Last revision: 2002-01-13
+Al Viro, H. Peter Anvin
+
+Last revision: 2002-01-13
Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
getting {replaced/complemented} with the new "initial ramfs"
@@ -18,7 +20,8 @@ archive can be compressed using gzip(1). One valid version of an
initramfs buffer is thus a single .cpio.gz file.
The full format of the initramfs buffer is defined by the following
-grammar, where:
+grammar, where::
+
* is used to indicate "0 or more occurrences of"
(|) indicates alternatives
+ indicates concatenation
@@ -49,7 +52,9 @@ hexadecimal ASCII numbers fully padded with '0' on the left to the
full width of the field, for example, the integer 4780 is represented
by the ASCII string "000012ac"):
+============= ================== ==============================================
Field name Field size Meaning
+============= ================== ==============================================
c_magic 6 bytes The string "070701" or "070702"
c_ino 8 bytes File inode number
c_mode 8 bytes File mode and permissions
@@ -65,6 +70,7 @@ c_rmin 8 bytes Minor part of device node reference
c_namesize 8 bytes Length of filename, including final \0
c_chksum 8 bytes Checksum of data field if c_magic is 070702;
otherwise zero
+============= ================== ==============================================
The c_mode field matches the contents of st_mode returned by stat(2)
on Linux, and encodes the file type and file permissions.
@@ -82,7 +88,8 @@ If the filename is "TRAILER!!!" this is actually an end-of-archive
marker; the c_filesize for an end-of-archive marker must be zero.
-*** Handling of hard links
+Handling of hard links
+======================
When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino)
tuple is looked up in a tuple buffer. If not found, it is entered in
diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/early_userspace_support.rst
similarity index 99%
rename from Documentation/early-userspace/README
rename to Documentation/early-userspace/early_userspace_support.rst
index 955d667dc87e..3deefb34046b 100644
--- a/Documentation/early-userspace/README
+++ b/Documentation/early-userspace/early_userspace_support.rst
@@ -1,3 +1,4 @@
+=======================
Early userspace support
=======================
@@ -26,6 +27,7 @@ archive to be used as the image or have the kernel build process build
the image from specifications.
CPIO ARCHIVE method
+-------------------
You can create a cpio archive that contains the early userspace image.
Your cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it
@@ -34,6 +36,7 @@ CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in
combination with a cpio archive.
IMAGE BUILDING method
+---------------------
The kernel build process can also build an early userspace image from
source parts rather than supplying a cpio archive. This method provides
diff --git a/Documentation/early-userspace/index.rst b/Documentation/early-userspace/index.rst
new file mode 100644
index 000000000000..2b8eb6132058
--- /dev/null
+++ b/Documentation/early-userspace/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+===============
+Early Userspace
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ early_userspace_support
+ buffer-format
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt
index d2963123eb1c..4862d3d77e27 100644
--- a/Documentation/filesystems/nfs/nfsroot.txt
+++ b/Documentation/filesystems/nfs/nfsroot.txt
@@ -239,7 +239,7 @@ rdinit=<executable file>
A description of the process of mounting the root file system can be
found in:
- Documentation/early-userspace/README
+ Documentation/early-userspace/early_userspace_support.rst
diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.txt b/Documentation/filesystems/ramfs-rootfs-initramfs.txt
index 79637d227e85..fa985909dbca 100644
--- a/Documentation/filesystems/ramfs-rootfs-initramfs.txt
+++ b/Documentation/filesystems/ramfs-rootfs-initramfs.txt
@@ -105,7 +105,7 @@ All this differs from the old initrd in several ways:
- The old initrd file was a gzipped filesystem image (in some file format,
such as ext2, that needed a driver built into the kernel), while the new
initramfs archive is a gzipped cpio archive (like tar only simpler,
- see cpio(1) and Documentation/early-userspace/buffer-format.txt). The
+ see cpio(1) and Documentation/early-userspace/buffer-format.rst). The
kernel's cpio extraction code is not only extremely small, it's also
__init text and data that can be discarded during the boot process.
@@ -159,7 +159,7 @@ One advantage of the configuration file is that root access is not required to
set permissions or create device nodes in the new archive. (Note that those
two example "file" entries expect to find files named "init.sh" and "busybox" in
a directory called "initramfs", under the linux-2.6.* directory. See
-Documentation/early-userspace/README for more details.)
+Documentation/early-userspace/early_userspace_support.rst for more details.)
The kernel does not depend on external cpio tools. If you specify a
directory instead of a configuration file, the kernel's build infrastructure
diff --git a/usr/Kconfig b/usr/Kconfig
index 43658b8a975e..86e37e297278 100644
--- a/usr/Kconfig
+++ b/usr/Kconfig
@@ -18,7 +18,7 @@ config INITRAMFS_SOURCE
When multiple directories and files are specified then the
initramfs image will be the aggregate of all of them.
- See <file:Documentation/early-userspace/README> for more details.
+ See <file:Documentation/early-userspace/early_userspace_support.rst> for more details.
If you are not sure, leave it blank.
--
2.21.0
^ permalink raw reply related
* [PATCH v1 06/31] docs: console.txt: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Bartlomiej Zolnierkiewicz, Greg Kroah-Hartman,
Jiri Slaby, dri-devel, linux-fbdev
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Convert this small file to ReST in preparation for adding it to
the driver-api book.
While this is not part of the driver-api book, mark it as
:orphan:, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../console/{console.txt => console.rst} | 63 ++++++++++---------
Documentation/fb/fbcon.rst | 4 +-
drivers/tty/Kconfig | 2 +-
3 files changed, 38 insertions(+), 31 deletions(-)
rename Documentation/console/{console.txt => console.rst} (80%)
diff --git a/Documentation/console/console.txt b/Documentation/console/console.rst
similarity index 80%
rename from Documentation/console/console.txt
rename to Documentation/console/console.rst
index d73c2ab4beda..b374141b027e 100644
--- a/Documentation/console/console.txt
+++ b/Documentation/console/console.rst
@@ -1,3 +1,6 @@
+:orphan:
+
+===============
Console Drivers
===============
@@ -17,25 +20,26 @@ of driver occupying the consoles.) They can only take over the console that is
occupied by the system driver. In the same token, if the modular driver is
released by the console, the system driver will take over.
-Modular drivers, from the programmer's point of view, have to call:
+Modular drivers, from the programmer's point of view, have to call::
do_take_over_console() - load and bind driver to console layer
give_up_console() - unload driver; it will only work if driver
is fully unbound
-In newer kernels, the following are also available:
+In newer kernels, the following are also available::
do_register_con_driver()
do_unregister_con_driver()
If sysfs is enabled, the contents of /sys/class/vtconsole can be
examined. This shows the console backends currently registered by the
-system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus:
+system which are named vtcon<n> where <n> is an integer from 0 to 15.
+Thus::
ls /sys/class/vtconsole
. .. vtcon0 vtcon1
-Each directory in /sys/class/vtconsole has 3 files:
+Each directory in /sys/class/vtconsole has 3 files::
ls /sys/class/vtconsole/vtcon0
. .. bind name uevent
@@ -46,27 +50,29 @@ What do these files signify?
read, or acts to bind or unbind the driver to the virtual consoles
when written to. The possible values are:
- 0 - means the driver is not bound and if echo'ed, commands the driver
+ 0
+ - means the driver is not bound and if echo'ed, commands the driver
to unbind
- 1 - means the driver is bound and if echo'ed, commands the driver to
+ 1
+ - means the driver is bound and if echo'ed, commands the driver to
bind
- 2. name - read-only file. Shows the name of the driver in this format:
+ 2. name - read-only file. Shows the name of the driver in this format::
- cat /sys/class/vtconsole/vtcon0/name
- (S) VGA+
+ cat /sys/class/vtconsole/vtcon0/name
+ (S) VGA+
- '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
- commanded to bind or unbind
+ '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
+ commanded to bind or unbind
- 'VGA+' is the name of the driver
+ 'VGA+' is the name of the driver
- cat /sys/class/vtconsole/vtcon1/name
- (M) frame buffer device
+ cat /sys/class/vtconsole/vtcon1/name
+ (M) frame buffer device
- In this case, '(M)' stands for a (M)odular driver, one that can be
- directly commanded to bind or unbind.
+ In this case, '(M)' stands for a (M)odular driver, one that can be
+ directly commanded to bind or unbind.
3. uevent - ignore this file
@@ -75,14 +81,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other
hand, will bind the driver to the consoles that are currently occupied by a
system driver.
-NOTE1: Binding and unbinding must be selected in Kconfig. It's under:
+NOTE1:
+ Binding and unbinding must be selected in Kconfig. It's under::
-Device Drivers -> Character devices -> Support for binding and unbinding
-console drivers
+ Device Drivers ->
+ Character devices ->
+ Support for binding and unbinding console drivers
-NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
-unbinding will not succeed. An example of an application that sets the console
-to KD_GRAPHICS is X.
+NOTE2:
+ If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
+ unbinding will not succeed. An example of an application that sets the
+ console to KD_GRAPHICS is X.
How useful is this feature? This is very useful for console driver
developers. By unbinding the driver from the console layer, one can unload the
@@ -92,10 +101,10 @@ framebuffer console to VGA console and vice versa, this feature also makes
this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
for more details.)
-Notes for developers:
-=====================
+Notes for developers
+====================
-do_take_over_console() is now broken up into:
+do_take_over_console() is now broken up into::
do_register_con_driver()
do_bind_con_driver() - private function
@@ -104,7 +113,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must
be fully unbound for this call to succeed. con_is_bound() will check if the
driver is bound or not.
-Guidelines for console driver writers:
+Guidelines for console driver writers
=====================================
In order for binding to and unbinding from the console to properly work,
@@ -140,6 +149,4 @@ The current crop of console drivers should still work correctly, but binding
and unbinding them may cause problems. With minimal fixes, these drivers can
be made to work correctly.
-==========================
Antonino Daplas <adaplas@pol.net>
-
diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst
index cfb9f7c38f18..22112718dd5d 100644
--- a/Documentation/fb/fbcon.rst
+++ b/Documentation/fb/fbcon.rst
@@ -187,7 +187,7 @@ the hardware. Thus, in a VGA console::
Assuming the VGA driver can be unloaded, one must first unbind the VGA driver
from the console layer before unloading the driver. The VGA driver cannot be
unloaded if it is still bound to the console layer. (See
-Documentation/console/console.txt for more information).
+Documentation/console/console.rst for more information).
This is more complicated in the case of the framebuffer console (fbcon),
because fbcon is an intermediate layer between the console and the drivers::
@@ -204,7 +204,7 @@ fbcon. Thus, there is no need to explicitly unbind the fbdev drivers from
fbcon.
So, how do we unbind fbcon from the console? Part of the answer is in
-Documentation/console/console.txt. To summarize:
+Documentation/console/console.rst. To summarize:
Echo a value to the bind file that represents the framebuffer console
driver. So assuming vtcon1 represents fbcon, then::
diff --git a/drivers/tty/Kconfig b/drivers/tty/Kconfig
index 0e3e4dacbc12..1cb50f19d58c 100644
--- a/drivers/tty/Kconfig
+++ b/drivers/tty/Kconfig
@@ -93,7 +93,7 @@ config VT_HW_CONSOLE_BINDING
select the console driver that will serve as the backend for the
virtual terminals.
- See <file:Documentation/console/console.txt> for more
+ See <file:Documentation/console/console.rst> for more
information. For framebuffer console users, please refer to
<file:Documentation/fb/fbcon.rst>.
--
2.21.0
^ permalink raw reply related
* [PATCH v1 04/31] docs: m68k: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Convert the m68k kernel-options.txt file to ReST.
The conversion is trivial, as the document is already on a format
close enough to ReST. Just some small adjustments were needed in
order to make it both good for being parsed while keeping it on
a good txt shape.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../admin-guide/kernel-parameters.rst | 2 +-
Documentation/m68k/index.rst | 17 +
...{kernel-options.txt => kernel-options.rst} | 319 ++++++++++--------
3 files changed, 191 insertions(+), 147 deletions(-)
create mode 100644 Documentation/m68k/index.rst
rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%)
diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index 8d3273e32eb1..006196bd763a 100644
--- a/Documentation/admin-guide/kernel-parameters.rst
+++ b/Documentation/admin-guide/kernel-parameters.rst
@@ -118,7 +118,7 @@ parameter is applicable::
LOOP Loopback device support is enabled.
M68k M68k architecture is enabled.
These options have more detailed description inside of
- Documentation/m68k/kernel-options.txt.
+ Documentation/m68k/kernel-options.rst.
MDA MDA console support is enabled.
MIPS MIPS architecture is enabled.
MOUSE Appropriate mouse support is enabled.
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
new file mode 100644
index 000000000000..f3273ec075c3
--- /dev/null
+++ b/Documentation/m68k/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+=================
+m68k Architecture
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ kernel-options
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.rst
similarity index 78%
rename from Documentation/m68k/kernel-options.txt
rename to Documentation/m68k/kernel-options.rst
index 79d21246c75a..cabd9419740d 100644
--- a/Documentation/m68k/kernel-options.txt
+++ b/Documentation/m68k/kernel-options.rst
@@ -1,22 +1,24 @@
-
-
- Command Line Options for Linux/m68k
- ===================================
+===================================
+Command Line Options for Linux/m68k
+===================================
Last Update: 2 May 1999
+
Linux/m68k version: 2.2.6
+
Author: Roman.Hodek@informatik.uni-erlangen.de (Roman Hodek)
+
Update: jds@kom.auc.dk (Jes Sorensen) and faq@linux-m68k.org (Chris Lawrence)
0) Introduction
===============
- Often I've been asked which command line options the Linux/m68k
+Often I've been asked which command line options the Linux/m68k
kernel understands, or how the exact syntax for the ... option is, or
... about the option ... . I hope, this document supplies all the
answers...
- Note that some options might be outdated, their descriptions being
+Note that some options might be outdated, their descriptions being
incomplete or missing. Please update the information and send in the
patches.
@@ -38,11 +40,11 @@ argument contains an '=', it is of class 2, and the definition is put
into init's environment. All other arguments are passed to init as
command line options.
- This document describes the valid kernel options for Linux/m68k in
+This document describes the valid kernel options for Linux/m68k in
the version mentioned at the start of this file. Later revisions may
add new such options, and some may be missing in older versions.
- In general, the value (the part after the '=') of an option is a
+In general, the value (the part after the '=') of an option is a
list of values separated by commas. The interpretation of these values
is up to the driver that "owns" the option. This association of
options with drivers is also the reason that some are further
@@ -55,21 +57,21 @@ subdivided.
2.1) root=
----------
-Syntax: root=/dev/<device>
- or: root=<hex_number>
+:Syntax: root=/dev/<device>
+:or: root=<hex_number>
This tells the kernel which device it should mount as the root
filesystem. The device must be a block device with a valid filesystem
on it.
- The first syntax gives the device by name. These names are converted
+The first syntax gives the device by name. These names are converted
into a major/minor number internally in the kernel in an unusual way.
Normally, this "conversion" is done by the device files in /dev, but
this isn't possible here, because the root filesystem (with /dev)
isn't mounted yet... So the kernel parses the name itself, with some
hardcoded name to number mappings. The name must always be a
combination of two or three letters, followed by a decimal number.
-Valid names are:
+Valid names are::
/dev/ram: -> 0x0100 (initial ramdisk)
/dev/hda: -> 0x0300 (first IDE disk)
@@ -81,7 +83,7 @@ Valid names are:
/dev/sde: -> 0x0840 (fifth SCSI disk)
/dev/fd : -> 0x0200 (floppy disk)
- The name must be followed by a decimal number, that stands for the
+The name must be followed by a decimal number, that stands for the
partition number. Internally, the value of the number is just
added to the device number mentioned in the table above. The
exceptions are /dev/ram and /dev/fd, where /dev/ram refers to an
@@ -100,12 +102,12 @@ the kernel command line.
[Strange and maybe uninteresting stuff ON]
- This unusual translation of device names has some strange
+This unusual translation of device names has some strange
consequences: If, for example, you have a symbolic link from /dev/fd
to /dev/fd0D720 as an abbreviation for floppy driver #0 in DD format,
you cannot use this name for specifying the root device, because the
kernel cannot see this symlink before mounting the root FS and it
-isn't in the table above. If you use it, the root device will not be
+isn't in the table above. If you use it, the root device will not be
set at all, without an error message. Another example: You cannot use a
partition on e.g. the sixth SCSI disk as the root filesystem, if you
want to specify it by name. This is, because only the devices up to
@@ -118,7 +120,7 @@ knowledge that each disk uses 16 minors, and write "root=/dev/sde17"
[Strange and maybe uninteresting stuff OFF]
- If the device containing your root partition isn't in the table
+If the device containing your root partition isn't in the table
above, you can also specify it by major and minor numbers. These are
written in hex, with no prefix and no separator between. E.g., if you
have a CD with contents appropriate as a root filesystem in the first
@@ -136,6 +138,7 @@ known partition UUID as the starting point. For example,
if partition 5 of the device has the UUID of
00112233-4455-6677-8899-AABBCCDDEEFF then partition 3 may be found as
follows:
+
PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2
Authoritative information can be found in
@@ -145,8 +148,8 @@ Authoritative information can be found in
2.2) ro, rw
-----------
-Syntax: ro
- or: rw
+:Syntax: ro
+:or: rw
These two options tell the kernel whether it should mount the root
filesystem read-only or read-write. The default is read-only, except
@@ -156,7 +159,7 @@ for ramdisks, which default to read-write.
2.3) debug
----------
-Syntax: debug
+:Syntax: debug
This raises the kernel log level to 10 (the default is 7). This is the
same level as set by the "dmesg" command, just that the maximum level
@@ -166,7 +169,7 @@ selectable by dmesg is 8.
2.4) debug=
-----------
-Syntax: debug=<device>
+:Syntax: debug=<device>
This option causes certain kernel messages be printed to the selected
debugging device. This can aid debugging the kernel, since the
@@ -175,7 +178,7 @@ devices are possible depends on the machine type. There are no checks
for the validity of the device name. If the device isn't implemented,
nothing happens.
- Messages logged this way are in general stack dumps after kernel
+Messages logged this way are in general stack dumps after kernel
memory faults or bad kernel traps, and kernel panics. To be exact: all
messages of level 0 (panic messages) and all messages printed while
the log level is 8 or more (their level doesn't matter). Before stack
@@ -185,19 +188,27 @@ at least 8 can also be set by the "debug" command line option (see
Devices possible for Amiga:
- - "ser": built-in serial port; parameters: 9600bps, 8N1
- - "mem": Save the messages to a reserved area in chip mem. After
+ - "ser":
+ built-in serial port; parameters: 9600bps, 8N1
+ - "mem":
+ Save the messages to a reserved area in chip mem. After
rebooting, they can be read under AmigaOS with the tool
'dmesg'.
Devices possible for Atari:
- - "ser1": ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
- - "ser2": SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
- - "ser" : default serial port
+ - "ser1":
+ ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
+ - "ser2":
+ SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
+ - "ser" :
+ default serial port
This is "ser2" for a Falcon, and "ser1" for any other machine
- - "midi": The MIDI port; parameters: 31250bps, 8N1
- - "par" : parallel port
+ - "midi":
+ The MIDI port; parameters: 31250bps, 8N1
+ - "par" :
+ parallel port
+
The printing routine for this implements a timeout for the
case there's no printer connected (else the kernel would
lock up). The timeout is not exact, but usually a few
@@ -205,26 +216,29 @@ Devices possible for Atari:
2.6) ramdisk_size=
--------------
+------------------
-Syntax: ramdisk_size=<size>
+:Syntax: ramdisk_size=<size>
- This option instructs the kernel to set up a ramdisk of the given
+This option instructs the kernel to set up a ramdisk of the given
size in KBytes. Do not use this option if the ramdisk contents are
passed by bootstrap! In this case, the size is selected automatically
and should not be overwritten.
- The only application is for root filesystems on floppy disks, that
+The only application is for root filesystems on floppy disks, that
should be loaded into memory. To do that, select the corresponding
size of the disk as ramdisk size, and set the root device to the disk
drive (with "root=").
2.7) swap=
+
+ I can't find any sign of this option in 2.2.6.
+
2.8) buff=
-----------
- I can't find any sign of these options in 2.2.6.
+ I can't find any sign of this option in 2.2.6.
3) General Device Options (Amiga and Atari)
@@ -233,13 +247,13 @@ drive (with "root=").
3.1) ether=
-----------
-Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
+:Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
- <dev-name> is the name of a net driver, as specified in
+<dev-name> is the name of a net driver, as specified in
drivers/net/Space.c in the Linux source. Most prominent are eth0, ...
eth3, sl0, ... sl3, ppp0, ..., ppp3, dummy, and lo.
- The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
+The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
settings by this options. Also, the existing ethernet drivers for
Linux/m68k (ariadne, a2065, hydra) don't use them because Zorro boards
are really Plug-'n-Play, so the "ether=" option is useless altogether
@@ -249,9 +263,9 @@ for Linux/m68k.
3.2) hd=
--------
-Syntax: hd=<cylinders>,<heads>,<sectors>
+:Syntax: hd=<cylinders>,<heads>,<sectors>
- This option sets the disk geometry of an IDE disk. The first hd=
+This option sets the disk geometry of an IDE disk. The first hd=
option is for the first IDE disk, the second for the second one.
(I.e., you can give this option twice.) In most cases, you won't have
to use this option, since the kernel can obtain the geometry data
@@ -262,9 +276,9 @@ disks.
3.3) max_scsi_luns=
-------------------
-Syntax: max_scsi_luns=<n>
+:Syntax: max_scsi_luns=<n>
- Sets the maximum number of LUNs (logical units) of SCSI devices to
+Sets the maximum number of LUNs (logical units) of SCSI devices to
be scanned. Valid values for <n> are between 1 and 8. Default is 8 if
"Probe all LUNs on each SCSI device" was selected during the kernel
configuration, else 1.
@@ -273,9 +287,9 @@ configuration, else 1.
3.4) st=
--------
-Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
+:Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
- Sets several parameters of the SCSI tape driver. <buffer_size> is
+Sets several parameters of the SCSI tape driver. <buffer_size> is
the number of 512-byte buffers reserved for tape operations for each
device. <write_thres> sets the number of blocks which must be filled
to start an actual write operation to the tape. Maximum value is the
@@ -286,9 +300,9 @@ buffers allocated for all tape devices.
3.5) dmasound=
--------------
-Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
+:Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
- This option controls some configurations of the Linux/m68k DMA sound
+This option controls some configurations of the Linux/m68k DMA sound
driver (Amiga and Atari): <buffers> is the number of buffers you want
to use (minimum 4, default 4), <buffer-size> is the size of each
buffer in kilobytes (minimum 4, default 32) and <catch-radius> says
@@ -305,20 +319,22 @@ don't need to expand the sound.
4.1) video=
-----------
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
The <fbname> parameter specifies the name of the frame buffer,
-eg. most atari users will want to specify `atafb' here. The
+eg. most atari users will want to specify `atafb` here. The
<sub-options> is a comma-separated list of the sub-options listed
below.
-NB: Please notice that this option was renamed from `atavideo' to
- `video' during the development of the 1.3.x kernels, thus you
+NB:
+ Please notice that this option was renamed from `atavideo` to
+ `video` during the development of the 1.3.x kernels, thus you
might need to update your boot-scripts if upgrading to 2.x from
an 1.2.x kernel.
-NBB: The behavior of video= was changed in 2.1.57 so the recommended
-option is to specify the name of the frame buffer.
+NBB:
+ The behavior of video= was changed in 2.1.57 so the recommended
+ option is to specify the name of the frame buffer.
4.1.1) Video Mode
-----------------
@@ -341,11 +357,11 @@ mode, if the hardware allows. Currently defined names are:
- falh2 : 896x608x1, Falcon only
- falh16 : 896x608x4, Falcon only
- If no video mode is given on the command line, the kernel tries the
+If no video mode is given on the command line, the kernel tries the
modes names "default<n>" in turn, until one is possible with the
hardware in use.
- A video mode setting doesn't make sense, if the external driver is
+A video mode setting doesn't make sense, if the external driver is
activated by a "external:" sub-option.
4.1.2) inverse
@@ -358,17 +374,17 @@ option, you can make the background white.
4.1.3) font
-----------
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
Specify the font to use in text modes. Currently you can choose only
-between `VGA8x8', `VGA8x16' and `PEARL8x8'. `VGA8x8' is default, if the
+between `VGA8x8`, `VGA8x16` and `PEARL8x8`. `VGA8x8` is default, if the
vertical size of the display is less than 400 pixel rows. Otherwise, the
-`VGA8x16' font is the default.
+`VGA8x16` font is the default.
-4.1.4) hwscroll_
-----------------
+4.1.4) `hwscroll_`
+------------------
-Syntax: hwscroll_<n>
+:Syntax: `hwscroll_<n>`
The number of additional lines of video memory to reserve for
speeding up the scrolling ("hardware scrolling"). Hardware scrolling
@@ -378,7 +394,7 @@ possible with plain STs and graphics cards (The former because the
base address must be on a 256 byte boundary there, the latter because
the kernel doesn't know how to set the base address at all.)
- By default, <n> is set to the number of visible text lines on the
+By default, <n> is set to the number of visible text lines on the
display. Thus, the amount of video memory is doubled, compared to no
hardware scrolling. You can turn off the hardware scrolling altogether
by setting <n> to 0.
@@ -386,31 +402,31 @@ by setting <n> to 0.
4.1.5) internal:
----------------
-Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
+:Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
This option specifies the capabilities of some extended internal video
hardware, like e.g. OverScan. <xres> and <yres> give the (extended)
dimensions of the screen.
- If your OverScan needs a black border, you have to write the last
+If your OverScan needs a black border, you have to write the last
three arguments of the "internal:". <xres_max> is the maximum line
length the hardware allows, <yres_max> the maximum number of lines.
<offset> is the offset of the visible part of the screen memory to its
physical start, in bytes.
- Often, extended interval video hardware has to be activated somehow.
+Often, extended interval video hardware has to be activated somehow.
For this, see the "sw_*" options below.
4.1.6) external:
----------------
-Syntax:
- external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>\
- [;<colw>[;<coltype>[;<xres_virtual>]]]]]
+:Syntax:
+ external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>
+ [;<colw>[;<coltype>[;<xres_virtual>]]]]]
-[I had to break this line...]
+.. I had to break this line...
- This is probably the most complicated parameter... It specifies that
+This is probably the most complicated parameter... It specifies that
you have some external video hardware (a graphics board), and how to
use it under Linux/m68k. The kernel cannot know more about the hardware
than you tell it here! The kernel also is unable to set or change any
@@ -418,38 +434,44 @@ video modes, since it doesn't know about any board internal. So, you
have to switch to that video mode before you start Linux, and cannot
switch to another mode once Linux has started.
- The first 3 parameters of this sub-option should be obvious: <xres>,
+The first 3 parameters of this sub-option should be obvious: <xres>,
<yres> and <depth> give the dimensions of the screen and the number of
planes (depth). The depth is the logarithm to base 2 of the number
of colors possible. (Or, the other way round: The number of colors is
2^depth).
- You have to tell the kernel furthermore how the video memory is
+You have to tell the kernel furthermore how the video memory is
organized. This is done by a letter as <org> parameter:
- 'n': "normal planes", i.e. one whole plane after another
- 'i': "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
+ 'n':
+ "normal planes", i.e. one whole plane after another
+ 'i':
+ "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
of the next, and so on... This mode is used only with the
- built-in Atari video modes, I think there is no card that
- supports this mode.
- 'p': "packed pixels", i.e. <depth> consecutive bits stand for all
- planes of one pixel; this is the most common mode for 8 planes
- (256 colors) on graphic cards
- 't': "true color" (more or less packed pixels, but without a color
- lookup table); usually depth is 24
+ built-in Atari video modes, I think there is no card that
+ supports this mode.
+ 'p':
+ "packed pixels", i.e. <depth> consecutive bits stand for all
+ planes of one pixel; this is the most common mode for 8 planes
+ (256 colors) on graphic cards
+ 't':
+ "true color" (more or less packed pixels, but without a color
+ lookup table); usually depth is 24
For monochrome modes (i.e., <depth> is 1), the <org> letter has a
different meaning:
- 'n': normal colors, i.e. 0=white, 1=black
- 'i': inverted colors, i.e. 0=black, 1=white
+ 'n':
+ normal colors, i.e. 0=white, 1=black
+ 'i':
+ inverted colors, i.e. 0=black, 1=white
- The next important information about the video hardware is the base
+The next important information about the video hardware is the base
address of the video memory. That is given in the <scrmem> parameter,
as a hexadecimal number with a "0x" prefix. You have to find out this
address in the documentation of your hardware.
- The next parameter, <scrlen>, tells the kernel about the size of the
+The next parameter, <scrlen>, tells the kernel about the size of the
video memory. If it's missing, the size is calculated from <xres>,
<yres>, and <depth>. For now, it is not useful to write a value here.
It would be used only for hardware scrolling (which isn't possible
@@ -460,7 +482,7 @@ empty, either by ending the "external:" after the video address or by
writing two consecutive semicolons, if you want to give a <vgabase>
(it is allowed to leave this parameter empty).
- The <vgabase> parameter is optional. If it is not given, the kernel
+The <vgabase> parameter is optional. If it is not given, the kernel
cannot read or write any color registers of the video hardware, and
thus you have to set appropriate colors before you start Linux. But if
your card is somehow VGA compatible, you can tell the kernel the base
@@ -472,18 +494,18 @@ uses the addresses vgabase+0x3c7...vgabase+0x3c9. The <vgabase>
parameter is written in hexadecimal with a "0x" prefix, just as
<scrmem>.
- <colw> is meaningful only if <vgabase> is specified. It tells the
+<colw> is meaningful only if <vgabase> is specified. It tells the
kernel how wide each of the color register is, i.e. the number of bits
per single color (red/green/blue). Default is 6, another quite usual
value is 8.
- Also <coltype> is used together with <vgabase>. It tells the kernel
+Also <coltype> is used together with <vgabase>. It tells the kernel
about the color register model of your gfx board. Currently, the types
"vga" (which is also the default) and "mv300" (SANG MV300) are
implemented.
- Parameter <xres_virtual> is required for ProMST or ET4000 cards where
-the physical linelength differs from the visible length. With ProMST,
+Parameter <xres_virtual> is required for ProMST or ET4000 cards where
+the physical linelength differs from the visible length. With ProMST,
xres_virtual must be set to 2048. For ET4000, xres_virtual depends on the
initialisation of the video-card.
If you're missing a corresponding yres_virtual: the external part is legacy,
@@ -499,13 +521,13 @@ currently works only with the ScreenWonder!
4.1.8) monitorcap:
-------------------
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
This describes the capabilities of a multisync monitor. Don't use it
with a fixed-frequency monitor! For now, only the Falcon frame buffer
uses the settings of "monitorcap:".
- <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
your monitor can work with, in Hz. <hmin> and <hmax> are the same for
the horizontal frequency, in kHz.
@@ -520,28 +542,28 @@ If this option is given, the framebuffer device doesn't do any video
mode calculations and settings on its own. The only Atari fb device
that does this currently is the Falcon.
- What you reach with this: Settings for unknown video extensions
+What you reach with this: Settings for unknown video extensions
aren't overridden by the driver, so you can still use the mode found
when booting, when the driver doesn't know to set this mode itself.
But this also means, that you can't switch video modes anymore...
- An example where you may want to use "keep" is the ScreenBlaster for
+An example where you may want to use "keep" is the ScreenBlaster for
the Falcon.
4.2) atamouse=
--------------
-Syntax: atamouse=<x-threshold>,[<y-threshold>]
+:Syntax: atamouse=<x-threshold>,[<y-threshold>]
- With this option, you can set the mouse movement reporting threshold.
+With this option, you can set the mouse movement reporting threshold.
This is the number of pixels of mouse movement that have to accumulate
before the IKBD sends a new mouse packet to the kernel. Higher values
reduce the mouse interrupt load and thus reduce the chance of keyboard
overruns. Lower values give a slightly faster mouse responses and
slightly better mouse tracking.
- You can set the threshold in x and y separately, but usually this is
+You can set the threshold in x and y separately, but usually this is
of little practical use. If there's just one number in the option, it
is used for both dimensions. The default value is 2 for both
thresholds.
@@ -550,7 +572,7 @@ thresholds.
4.3) ataflop=
-------------
-Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
+:Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
The drive type may be 0, 1, or 2, for DD, HD, and ED, resp. This
setting affects how many buffers are reserved and which formats are
@@ -563,15 +585,15 @@ Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
no for the Medusa and yes for all others.
With the two following parameters, you can change the default
- steprate used for drive A and B, resp.
+ steprate used for drive A and B, resp.
4.4) atascsi=
-------------
-Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
+:Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
- This option sets some parameters for the Atari native SCSI driver.
+This option sets some parameters for the Atari native SCSI driver.
Generally, any number of arguments can be omitted from the end. And
for each of the numbers, a negative value means "use default". The
defaults depend on whether TT-style or Falcon-style SCSI is used.
@@ -597,11 +619,14 @@ ignored (others aren't affected).
32). Default: 8/1. (Note: Values > 1 seem to cause problems on a
Falcon, cause not yet known.)
- The <cmd_per_lun> value at a great part determines the amount of
+ The <cmd_per_lun> value at a great part determines the amount of
memory SCSI reserves for itself. The formula is rather
complicated, but I can give you some hints:
- no scatter-gather : cmd_per_lun * 232 bytes
- full scatter-gather: cmd_per_lun * approx. 17 Kbytes
+
+ no scatter-gather:
+ cmd_per_lun * 232 bytes
+ full scatter-gather:
+ cmd_per_lun * approx. 17 Kbytes
<scat-gat>:
Size of the scatter-gather table, i.e. the number of requests
@@ -634,19 +659,23 @@ ignored (others aren't affected).
4.5 switches=
-------------
-Syntax: switches=<list of switches>
+:Syntax: switches=<list of switches>
- With this option you can switch some hardware lines that are often
+With this option you can switch some hardware lines that are often
used to enable/disable certain hardware extensions. Examples are
OverScan, overclocking, ...
- The <list of switches> is a comma-separated list of the following
+The <list of switches> is a comma-separated list of the following
items:
- ikbd: set RTS of the keyboard ACIA high
- midi: set RTS of the MIDI ACIA high
- snd6: set bit 6 of the PSG port A
- snd7: set bit 6 of the PSG port A
+ ikbd:
+ set RTS of the keyboard ACIA high
+ midi:
+ set RTS of the MIDI ACIA high
+ snd6:
+ set bit 6 of the PSG port A
+ snd7:
+ set bit 6 of the PSG port A
It doesn't make sense to mention a switch more than once (no
difference to only once), but you can give as many switches as you
@@ -654,16 +683,16 @@ want to enable different features. The switch lines are set as early
as possible during kernel initialization (even before determining the
present hardware.)
- All of the items can also be prefixed with "ov_", i.e. "ov_ikbd",
-"ov_midi", ... These options are meant for switching on an OverScan
+All of the items can also be prefixed with `ov_`, i.e. `ov_ikbd`,
+`ov_midi`, ... These options are meant for switching on an OverScan
video extension. The difference to the bare option is that the
switch-on is done after video initialization, and somehow synchronized
to the HBLANK. A speciality is that ov_ikbd and ov_midi are switched
off before rebooting, so that OverScan is disabled and TOS boots
correctly.
- If you give an option both, with and without the "ov_" prefix, the
-earlier initialization ("ov_"-less) takes precedence. But the
+If you give an option both, with and without the `ov_` prefix, the
+earlier initialization (`ov_`-less) takes precedence. But the
switching-off on reset still happens in this case.
5) Options for Amiga Only:
@@ -672,10 +701,10 @@ switching-off on reset still happens in this case.
5.1) video=
-----------
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
The <fbname> parameter specifies the name of the frame buffer, valid
-options are `amifb', `cyber', 'virge', `retz3' and `clgen', provided
+options are `amifb`, `cyber`, 'virge', `retz3` and `clgen`, provided
that the respective frame buffer devices have been compiled into the
kernel (or compiled as loadable modules). The behavior of the <fbname>
option was changed in 2.1.57 so it is now recommended to specify this
@@ -697,9 +726,11 @@ predefined video modes are available:
NTSC modes:
- ntsc : 640x200, 15 kHz, 60 Hz
- ntsc-lace : 640x400, 15 kHz, 60 Hz interlaced
+
PAL modes:
- pal : 640x256, 15 kHz, 50 Hz
- pal-lace : 640x512, 15 kHz, 50 Hz interlaced
+
ECS modes:
- multiscan : 640x480, 29 kHz, 57 Hz
- multiscan-lace : 640x960, 29 kHz, 57 Hz interlaced
@@ -715,6 +746,7 @@ ECS modes:
- dblpal-lace : 640x1024, 27 kHz, 47 Hz interlaced
- dblntsc : 640x200, 27 kHz, 57 Hz doublescan
- dblpal : 640x256, 27 kHz, 47 Hz doublescan
+
VGA modes:
- vga : 640x480, 31 kHz, 60 Hz
- vga70 : 640x400, 31 kHz, 70 Hz
@@ -726,7 +758,7 @@ chipset and 8-bit color for the AGA chipset.
5.1.2) depth
------------
-Syntax: depth:<nr. of bit-planes>
+:Syntax: depth:<nr. of bit-planes>
Specify the number of bit-planes for the selected video-mode.
@@ -739,32 +771,32 @@ Use inverted display (black on white). Functionally the same as the
5.1.4) font
-----------
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
Specify the font to use in text modes. Functionally the same as the
-"font" sub-option for the Atari, except that `PEARL8x8' is used instead
-of `VGA8x8' if the vertical size of the display is less than 400 pixel
+"font" sub-option for the Atari, except that `PEARL8x8` is used instead
+of `VGA8x8` if the vertical size of the display is less than 400 pixel
rows.
5.1.5) monitorcap:
-------------------
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
This describes the capabilities of a multisync monitor. For now, only
the color frame buffer uses the settings of "monitorcap:".
- <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
your monitor can work with, in Hz. <hmin> and <hmax> are the same for
the horizontal frequency, in kHz.
- The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
+The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
5.2) fd_def_df0=
----------------
-Syntax: fd_def_df0=<value>
+:Syntax: fd_def_df0=<value>
Sets the df0 value for "silent" floppy drives. The value should be in
hexadecimal with "0x" prefix.
@@ -773,7 +805,7 @@ hexadecimal with "0x" prefix.
5.3) wd33c93=
-------------
-Syntax: wd33c93=<sub-options...>
+:Syntax: wd33c93=<sub-options...>
These options affect the A590/A2091, A3000 and GVP Series II SCSI
controllers.
@@ -784,9 +816,9 @@ below.
5.3.1) nosync
-------------
-Syntax: nosync:bitmask
+:Syntax: nosync:bitmask
- bitmask is a byte where the 1st 7 bits correspond with the 7
+bitmask is a byte where the 1st 7 bits correspond with the 7
possible SCSI devices. Set a bit to prevent sync negotiation on that
device. To maintain backwards compatibility, a command-line such as
"wd33c93=255" will be automatically translated to
@@ -796,35 +828,35 @@ all devices, eg. nosync:0xff.
5.3.2) period
-------------
-Syntax: period:ns
+:Syntax: period:ns
- `ns' is the minimum # of nanoseconds in a SCSI data transfer
+`ns` is the minimum # of nanoseconds in a SCSI data transfer
period. Default is 500; acceptable values are 250 - 1000.
5.3.3) disconnect
-----------------
-Syntax: disconnect:x
+:Syntax: disconnect:x
- Specify x = 0 to never allow disconnects, 2 to always allow them.
+Specify x = 0 to never allow disconnects, 2 to always allow them.
x = 1 does 'adaptive' disconnects, which is the default and generally
the best choice.
5.3.4) debug
------------
-Syntax: debug:x
+:Syntax: debug:x
- If `DEBUGGING_ON' is defined, x is a bit mask that causes various
+If `DEBUGGING_ON` is defined, x is a bit mask that causes various
types of debug output to printed - see the DB_xxx defines in
wd33c93.h.
5.3.5) clock
------------
-Syntax: clock:x
+:Syntax: clock:x
- x = clock input in MHz for WD33c93 chip. Normal values would be from
+x = clock input in MHz for WD33c93 chip. Normal values would be from
8 through 20. The default value depends on your hostadapter(s),
default for the A3000 internal controller is 14, for the A2091 it's 8
and for the GVP hostadapters it's either 8 or 14, depending on the
@@ -834,15 +866,15 @@ hostadapters.
5.3.6) next
-----------
- No argument. Used to separate blocks of keywords when there's more
+No argument. Used to separate blocks of keywords when there's more
than one wd33c93-based host adapter in the system.
5.3.7) nodma
------------
-Syntax: nodma:x
+:Syntax: nodma:x
- If x is 1 (or if the option is just written as "nodma"), the WD33c93
+If x is 1 (or if the option is just written as "nodma"), the WD33c93
controller will not use DMA (= direct memory access) to access the
Amiga's memory. This is useful for some systems (like A3000's and
A4000's with the A3640 accelerator, revision 3.0) that have problems
@@ -853,32 +885,27 @@ possible.
5.4) gvp11=
-----------
-Syntax: gvp11=<addr-mask>
+:Syntax: gvp11=<addr-mask>
- The earlier versions of the GVP driver did not handle DMA
+The earlier versions of the GVP driver did not handle DMA
address-mask settings correctly which made it necessary for some
people to use this option, in order to get their GVP controller
running under Linux. These problems have hopefully been solved and the
use of this option is now highly unrecommended!
- Incorrect use can lead to unpredictable behavior, so please only use
+Incorrect use can lead to unpredictable behavior, so please only use
this option if you *know* what you are doing and have a reason to do
so. In any case if you experience problems and need to use this
option, please inform us about it by mailing to the Linux/68k kernel
mailing list.
- The address mask set by this option specifies which addresses are
+The address mask set by this option specifies which addresses are
valid for DMA with the GVP Series II SCSI controller. An address is
valid, if no bits are set except the bits that are set in the mask,
too.
- Some versions of the GVP can only DMA into a 24 bit address range,
+Some versions of the GVP can only DMA into a 24 bit address range,
some can address a 25 bit address range while others can use the whole
32 bit address range for DMA. The correct setting depends on your
controller and should be autodetected by the driver. An example is the
24 bit region which is specified by a mask of 0x00fffffe.
-
-
-/* Local Variables: */
-/* mode: text */
-/* End: */
--
2.21.0
^ permalink raw reply related
* [PATCH v1 28/31] docs: mtd: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Miquel Raynal, Richard Weinberger,
David Woodhouse, Brian Norris, Marek Vasut, Vignesh Raghavendra,
linux-mtd
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the mtd documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
It should be noticed that Sphinx doesn't handle very well
URLs with dots in the middle. Thankfully, internally, the '.'
char is translated to %2E, so we can jus use %2E instead of
dots, and this will work fine on both text and processed files.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/mtd/index.rst | 12 +
.../mtd/{intel-spi.txt => intel-spi.rst} | 46 +-
.../mtd/{nand_ecc.txt => nand_ecc.rst} | 481 ++++++++++--------
.../mtd/{spi-nor.txt => spi-nor.rst} | 7 +-
drivers/mtd/nand/raw/nand_ecc.c | 2 +-
5 files changed, 306 insertions(+), 242 deletions(-)
create mode 100644 Documentation/mtd/index.rst
rename Documentation/mtd/{intel-spi.txt => intel-spi.rst} (71%)
rename Documentation/mtd/{nand_ecc.txt => nand_ecc.rst} (67%)
rename Documentation/mtd/{spi-nor.txt => spi-nor.rst} (94%)
diff --git a/Documentation/mtd/index.rst b/Documentation/mtd/index.rst
new file mode 100644
index 000000000000..4fdae418ac97
--- /dev/null
+++ b/Documentation/mtd/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+==============================
+Memory Technology Device (MTD)
+==============================
+
+.. toctree::
+ :maxdepth: 1
+
+ intel-spi
+ nand_ecc
+ spi-nor
diff --git a/Documentation/mtd/intel-spi.txt b/Documentation/mtd/intel-spi.rst
similarity index 71%
rename from Documentation/mtd/intel-spi.txt
rename to Documentation/mtd/intel-spi.rst
index bc357729c2cb..0e6d9cd5388d 100644
--- a/Documentation/mtd/intel-spi.txt
+++ b/Documentation/mtd/intel-spi.rst
@@ -1,5 +1,6 @@
+==============================
Upgrading BIOS using intel-spi
-------------------------------
+==============================
Many Intel CPUs like Baytrail and Braswell include SPI serial flash host
controller which is used to hold BIOS and other platform specific data.
@@ -36,45 +37,45 @@ Linux.
module parameter to modprobe).
4) Once the board is up and running again, find the right MTD partition
- (it is named as "BIOS"):
+ (it is named as "BIOS")::
- # cat /proc/mtd
- dev: size erasesize name
- mtd0: 00800000 00001000 "BIOS"
+ # cat /proc/mtd
+ dev: size erasesize name
+ mtd0: 00800000 00001000 "BIOS"
So here it will be /dev/mtd0 but it may vary.
- 5) Make backup of the existing image first:
+ 5) Make backup of the existing image first::
- # dd if=/dev/mtd0ro of=bios.bak
- 16384+0 records in
- 16384+0 records out
- 8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s
+ # dd if=/dev/mtd0ro of=bios.bak
+ 16384+0 records in
+ 16384+0 records out
+ 8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s
- 6) Verify the backup
+ 6) Verify the backup:
- # sha1sum /dev/mtd0ro bios.bak
- fdbb011920572ca6c991377c4b418a0502668b73 /dev/mtd0ro
- fdbb011920572ca6c991377c4b418a0502668b73 bios.bak
+ # sha1sum /dev/mtd0ro bios.bak
+ fdbb011920572ca6c991377c4b418a0502668b73 /dev/mtd0ro
+ fdbb011920572ca6c991377c4b418a0502668b73 bios.bak
The SHA1 sums must match. Otherwise do not continue any further!
7) Erase the SPI serial flash. After this step, do not reboot the
- board! Otherwise it will not start anymore.
+ board! Otherwise it will not start anymore::
- # flash_erase /dev/mtd0 0 0
- Erasing 4 Kibyte @ 7ff000 -- 100 % complete
+ # flash_erase /dev/mtd0 0 0
+ Erasing 4 Kibyte @ 7ff000 -- 100 % complete
8) Once completed without errors you can write the new BIOS image:
# dd if=MNW2MAX1.X64.0092.R01.1605221712.bin of=/dev/mtd0
9) Verify that the new content of the SPI serial flash matches the new
- BIOS image:
+ BIOS image::
- # sha1sum /dev/mtd0ro MNW2MAX1.X64.0092.R01.1605221712.bin
- 9b4df9e4be2057fceec3a5529ec3d950836c87a2 /dev/mtd0ro
- 9b4df9e4be2057fceec3a5529ec3d950836c87a2 MNW2MAX1.X64.0092.R01.1605221712.bin
+ # sha1sum /dev/mtd0ro MNW2MAX1.X64.0092.R01.1605221712.bin
+ 9b4df9e4be2057fceec3a5529ec3d950836c87a2 /dev/mtd0ro
+ 9b4df9e4be2057fceec3a5529ec3d950836c87a2 MNW2MAX1.X64.0092.R01.1605221712.bin
The SHA1 sums should match.
@@ -84,5 +85,6 @@ Linux.
References
----------
-[1] https://firmware.intel.com/sites/default/files/MinnowBoard.MAX_.X64.92.R01.zip
+[1] https://firmware.intel.com/sites/default/files/MinnowBoard%2EMAX_%2EX64%2E92%2ER01%2Ezip
+
[2] http://www.linux-mtd.infradead.org/
diff --git a/Documentation/mtd/nand_ecc.txt b/Documentation/mtd/nand_ecc.rst
similarity index 67%
rename from Documentation/mtd/nand_ecc.txt
rename to Documentation/mtd/nand_ecc.rst
index f8c3284bf6a7..e8d3c53a5056 100644
--- a/Documentation/mtd/nand_ecc.txt
+++ b/Documentation/mtd/nand_ecc.rst
@@ -1,3 +1,7 @@
+==========================
+NAND Error-correction Code
+==========================
+
Introduction
============
@@ -37,63 +41,79 @@ sometimes also referred to as xor. In C the operator for xor is ^
Back to ecc.
Let's give a small figure:
+========= ==== ==== ==== ==== ==== ==== ==== ==== === === === === ====
byte 0: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp2 rp4 ... rp14
byte 1: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp2 rp4 ... rp14
byte 2: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp3 rp4 ... rp14
byte 3: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp3 rp4 ... rp14
byte 4: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp2 rp5 ... rp14
-....
+...
byte 254: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp3 rp5 ... rp15
byte 255: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp3 rp5 ... rp15
cp1 cp0 cp1 cp0 cp1 cp0 cp1 cp0
cp3 cp3 cp2 cp2 cp3 cp3 cp2 cp2
cp5 cp5 cp5 cp5 cp4 cp4 cp4 cp4
+========= ==== ==== ==== ==== ==== ==== ==== ==== === === === === ====
This figure represents a sector of 256 bytes.
cp is my abbreviation for column parity, rp for row parity.
Let's start to explain column parity.
-cp0 is the parity that belongs to all bit0, bit2, bit4, bit6.
-so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even.
+
+- cp0 is the parity that belongs to all bit0, bit2, bit4, bit6.
+
+ so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even.
+
Similarly cp1 is the sum of all bit1, bit3, bit5 and bit7.
-cp2 is the parity over bit0, bit1, bit4 and bit5
-cp3 is the parity over bit2, bit3, bit6 and bit7.
-cp4 is the parity over bit0, bit1, bit2 and bit3.
-cp5 is the parity over bit4, bit5, bit6 and bit7.
+
+- cp2 is the parity over bit0, bit1, bit4 and bit5
+- cp3 is the parity over bit2, bit3, bit6 and bit7.
+- cp4 is the parity over bit0, bit1, bit2 and bit3.
+- cp5 is the parity over bit4, bit5, bit6 and bit7.
+
Note that each of cp0 .. cp5 is exactly one bit.
Row parity actually works almost the same.
-rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254)
-rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255)
-rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ...
-(so handle two bytes, then skip 2 bytes).
-rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...)
-for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc.
-so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...)
-and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, ..
+
+- rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254)
+- rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255)
+- rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ...
+ (so handle two bytes, then skip 2 bytes).
+- rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...)
+- for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc.
+
+ so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...)
+- and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, ..
+
The story now becomes quite boring. I guess you get the idea.
-rp6 covers 8 bytes then skips 8 etc
-rp7 skips 8 bytes then covers 8 etc
-rp8 covers 16 bytes then skips 16 etc
-rp9 skips 16 bytes then covers 16 etc
-rp10 covers 32 bytes then skips 32 etc
-rp11 skips 32 bytes then covers 32 etc
-rp12 covers 64 bytes then skips 64 etc
-rp13 skips 64 bytes then covers 64 etc
-rp14 covers 128 bytes then skips 128
-rp15 skips 128 bytes then covers 128
+
+- rp6 covers 8 bytes then skips 8 etc
+- rp7 skips 8 bytes then covers 8 etc
+- rp8 covers 16 bytes then skips 16 etc
+- rp9 skips 16 bytes then covers 16 etc
+- rp10 covers 32 bytes then skips 32 etc
+- rp11 skips 32 bytes then covers 32 etc
+- rp12 covers 64 bytes then skips 64 etc
+- rp13 skips 64 bytes then covers 64 etc
+- rp14 covers 128 bytes then skips 128
+- rp15 skips 128 bytes then covers 128
In the end the parity bits are grouped together in three bytes as
follows:
+
+===== ===== ===== ===== ===== ===== ===== ===== =====
ECC Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0
+===== ===== ===== ===== ===== ===== ===== ===== =====
ECC 0 rp07 rp06 rp05 rp04 rp03 rp02 rp01 rp00
ECC 1 rp15 rp14 rp13 rp12 rp11 rp10 rp09 rp08
ECC 2 cp5 cp4 cp3 cp2 cp1 cp0 1 1
+===== ===== ===== ===== ===== ===== ===== ===== =====
I detected after writing this that ST application note AN1823
(http://www.st.com/stonline/) gives a much
nicer picture.(but they use line parity as term where I use row parity)
Oh well, I'm graphically challenged, so suffer with me for a moment :-)
+
And I could not reuse the ST picture anyway for copyright reasons.
@@ -101,9 +121,10 @@ Attempt 0
=========
Implementing the parity calculation is pretty simple.
-In C pseudocode:
-for (i = 0; i < 256; i++)
-{
+In C pseudocode::
+
+ for (i = 0; i < 256; i++)
+ {
if (i & 0x01)
rp1 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp1;
else
@@ -142,7 +163,7 @@ for (i = 0; i < 256; i++)
cp3 = bit7 ^ bit6 ^ bit3 ^ bit2 ^ cp3
cp4 = bit3 ^ bit2 ^ bit1 ^ bit0 ^ cp4
cp5 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ cp5
-}
+ }
Analysis 0
@@ -167,82 +188,84 @@ This leads to:
Attempt 1
=========
-const char parity[256] = {
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
- 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0
-};
+::
-void ecc1(const unsigned char *buf, unsigned char *code)
-{
- int i;
- const unsigned char *bp = buf;
- unsigned char cur;
- unsigned char rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
- unsigned char rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
- unsigned char par;
+ const char parity[256] = {
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+ 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0
+ };
- par = 0;
- rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
- rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
- rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
- rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
+ void ecc1(const unsigned char *buf, unsigned char *code)
+ {
+ int i;
+ const unsigned char *bp = buf;
+ unsigned char cur;
+ unsigned char rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
+ unsigned char rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
+ unsigned char par;
- for (i = 0; i < 256; i++)
- {
- cur = *bp++;
- par ^= cur;
- if (i & 0x01) rp1 ^= cur; else rp0 ^= cur;
- if (i & 0x02) rp3 ^= cur; else rp2 ^= cur;
- if (i & 0x04) rp5 ^= cur; else rp4 ^= cur;
- if (i & 0x08) rp7 ^= cur; else rp6 ^= cur;
- if (i & 0x10) rp9 ^= cur; else rp8 ^= cur;
- if (i & 0x20) rp11 ^= cur; else rp10 ^= cur;
- if (i & 0x40) rp13 ^= cur; else rp12 ^= cur;
- if (i & 0x80) rp15 ^= cur; else rp14 ^= cur;
- }
- code[0] =
- (parity[rp7] << 7) |
- (parity[rp6] << 6) |
- (parity[rp5] << 5) |
- (parity[rp4] << 4) |
- (parity[rp3] << 3) |
- (parity[rp2] << 2) |
- (parity[rp1] << 1) |
- (parity[rp0]);
- code[1] =
- (parity[rp15] << 7) |
- (parity[rp14] << 6) |
- (parity[rp13] << 5) |
- (parity[rp12] << 4) |
- (parity[rp11] << 3) |
- (parity[rp10] << 2) |
- (parity[rp9] << 1) |
- (parity[rp8]);
- code[2] =
- (parity[par & 0xf0] << 7) |
- (parity[par & 0x0f] << 6) |
- (parity[par & 0xcc] << 5) |
- (parity[par & 0x33] << 4) |
- (parity[par & 0xaa] << 3) |
- (parity[par & 0x55] << 2);
- code[0] = ~code[0];
- code[1] = ~code[1];
- code[2] = ~code[2];
-}
+ par = 0;
+ rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
+ rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
+ rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
+ rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
+
+ for (i = 0; i < 256; i++)
+ {
+ cur = *bp++;
+ par ^= cur;
+ if (i & 0x01) rp1 ^= cur; else rp0 ^= cur;
+ if (i & 0x02) rp3 ^= cur; else rp2 ^= cur;
+ if (i & 0x04) rp5 ^= cur; else rp4 ^= cur;
+ if (i & 0x08) rp7 ^= cur; else rp6 ^= cur;
+ if (i & 0x10) rp9 ^= cur; else rp8 ^= cur;
+ if (i & 0x20) rp11 ^= cur; else rp10 ^= cur;
+ if (i & 0x40) rp13 ^= cur; else rp12 ^= cur;
+ if (i & 0x80) rp15 ^= cur; else rp14 ^= cur;
+ }
+ code[0] =
+ (parity[rp7] << 7) |
+ (parity[rp6] << 6) |
+ (parity[rp5] << 5) |
+ (parity[rp4] << 4) |
+ (parity[rp3] << 3) |
+ (parity[rp2] << 2) |
+ (parity[rp1] << 1) |
+ (parity[rp0]);
+ code[1] =
+ (parity[rp15] << 7) |
+ (parity[rp14] << 6) |
+ (parity[rp13] << 5) |
+ (parity[rp12] << 4) |
+ (parity[rp11] << 3) |
+ (parity[rp10] << 2) |
+ (parity[rp9] << 1) |
+ (parity[rp8]);
+ code[2] =
+ (parity[par & 0xf0] << 7) |
+ (parity[par & 0x0f] << 6) |
+ (parity[par & 0xcc] << 5) |
+ (parity[par & 0x33] << 4) |
+ (parity[par & 0xaa] << 3) |
+ (parity[par & 0x55] << 2);
+ code[0] = ~code[0];
+ code[1] = ~code[1];
+ code[2] = ~code[2];
+ }
Still pretty straightforward. The last three invert statements are there to
give a checksum of 0xff 0xff 0xff for an empty flash. In an empty flash
@@ -293,88 +316,90 @@ Let's give it a try...
Attempt 2
=========
-extern const char parity[256];
+::
-void ecc2(const unsigned char *buf, unsigned char *code)
-{
- int i;
- const unsigned long *bp = (unsigned long *)buf;
- unsigned long cur;
- unsigned long rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
- unsigned long rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
- unsigned long par;
+ extern const char parity[256];
- par = 0;
- rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
- rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
- rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
- rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
+ void ecc2(const unsigned char *buf, unsigned char *code)
+ {
+ int i;
+ const unsigned long *bp = (unsigned long *)buf;
+ unsigned long cur;
+ unsigned long rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
+ unsigned long rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
+ unsigned long par;
- for (i = 0; i < 64; i++)
- {
- cur = *bp++;
- par ^= cur;
- if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
- if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
- if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
- if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
- if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
- if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
- }
- /*
- we need to adapt the code generation for the fact that rp vars are now
- long; also the column parity calculation needs to be changed.
- we'll bring rp4 to 15 back to single byte entities by shifting and
- xoring
- */
- rp4 ^= (rp4 >> 16); rp4 ^= (rp4 >> 8); rp4 &= 0xff;
- rp5 ^= (rp5 >> 16); rp5 ^= (rp5 >> 8); rp5 &= 0xff;
- rp6 ^= (rp6 >> 16); rp6 ^= (rp6 >> 8); rp6 &= 0xff;
- rp7 ^= (rp7 >> 16); rp7 ^= (rp7 >> 8); rp7 &= 0xff;
- rp8 ^= (rp8 >> 16); rp8 ^= (rp8 >> 8); rp8 &= 0xff;
- rp9 ^= (rp9 >> 16); rp9 ^= (rp9 >> 8); rp9 &= 0xff;
- rp10 ^= (rp10 >> 16); rp10 ^= (rp10 >> 8); rp10 &= 0xff;
- rp11 ^= (rp11 >> 16); rp11 ^= (rp11 >> 8); rp11 &= 0xff;
- rp12 ^= (rp12 >> 16); rp12 ^= (rp12 >> 8); rp12 &= 0xff;
- rp13 ^= (rp13 >> 16); rp13 ^= (rp13 >> 8); rp13 &= 0xff;
- rp14 ^= (rp14 >> 16); rp14 ^= (rp14 >> 8); rp14 &= 0xff;
- rp15 ^= (rp15 >> 16); rp15 ^= (rp15 >> 8); rp15 &= 0xff;
- rp3 = (par >> 16); rp3 ^= (rp3 >> 8); rp3 &= 0xff;
- rp2 = par & 0xffff; rp2 ^= (rp2 >> 8); rp2 &= 0xff;
- par ^= (par >> 16);
- rp1 = (par >> 8); rp1 &= 0xff;
- rp0 = (par & 0xff);
- par ^= (par >> 8); par &= 0xff;
+ par = 0;
+ rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
+ rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
+ rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
+ rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
- code[0] =
- (parity[rp7] << 7) |
- (parity[rp6] << 6) |
- (parity[rp5] << 5) |
- (parity[rp4] << 4) |
- (parity[rp3] << 3) |
- (parity[rp2] << 2) |
- (parity[rp1] << 1) |
- (parity[rp0]);
- code[1] =
- (parity[rp15] << 7) |
- (parity[rp14] << 6) |
- (parity[rp13] << 5) |
- (parity[rp12] << 4) |
- (parity[rp11] << 3) |
- (parity[rp10] << 2) |
- (parity[rp9] << 1) |
- (parity[rp8]);
- code[2] =
- (parity[par & 0xf0] << 7) |
- (parity[par & 0x0f] << 6) |
- (parity[par & 0xcc] << 5) |
- (parity[par & 0x33] << 4) |
- (parity[par & 0xaa] << 3) |
- (parity[par & 0x55] << 2);
- code[0] = ~code[0];
- code[1] = ~code[1];
- code[2] = ~code[2];
-}
+ for (i = 0; i < 64; i++)
+ {
+ cur = *bp++;
+ par ^= cur;
+ if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
+ if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
+ if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
+ if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
+ if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
+ if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
+ }
+ /*
+ we need to adapt the code generation for the fact that rp vars are now
+ long; also the column parity calculation needs to be changed.
+ we'll bring rp4 to 15 back to single byte entities by shifting and
+ xoring
+ */
+ rp4 ^= (rp4 >> 16); rp4 ^= (rp4 >> 8); rp4 &= 0xff;
+ rp5 ^= (rp5 >> 16); rp5 ^= (rp5 >> 8); rp5 &= 0xff;
+ rp6 ^= (rp6 >> 16); rp6 ^= (rp6 >> 8); rp6 &= 0xff;
+ rp7 ^= (rp7 >> 16); rp7 ^= (rp7 >> 8); rp7 &= 0xff;
+ rp8 ^= (rp8 >> 16); rp8 ^= (rp8 >> 8); rp8 &= 0xff;
+ rp9 ^= (rp9 >> 16); rp9 ^= (rp9 >> 8); rp9 &= 0xff;
+ rp10 ^= (rp10 >> 16); rp10 ^= (rp10 >> 8); rp10 &= 0xff;
+ rp11 ^= (rp11 >> 16); rp11 ^= (rp11 >> 8); rp11 &= 0xff;
+ rp12 ^= (rp12 >> 16); rp12 ^= (rp12 >> 8); rp12 &= 0xff;
+ rp13 ^= (rp13 >> 16); rp13 ^= (rp13 >> 8); rp13 &= 0xff;
+ rp14 ^= (rp14 >> 16); rp14 ^= (rp14 >> 8); rp14 &= 0xff;
+ rp15 ^= (rp15 >> 16); rp15 ^= (rp15 >> 8); rp15 &= 0xff;
+ rp3 = (par >> 16); rp3 ^= (rp3 >> 8); rp3 &= 0xff;
+ rp2 = par & 0xffff; rp2 ^= (rp2 >> 8); rp2 &= 0xff;
+ par ^= (par >> 16);
+ rp1 = (par >> 8); rp1 &= 0xff;
+ rp0 = (par & 0xff);
+ par ^= (par >> 8); par &= 0xff;
+
+ code[0] =
+ (parity[rp7] << 7) |
+ (parity[rp6] << 6) |
+ (parity[rp5] << 5) |
+ (parity[rp4] << 4) |
+ (parity[rp3] << 3) |
+ (parity[rp2] << 2) |
+ (parity[rp1] << 1) |
+ (parity[rp0]);
+ code[1] =
+ (parity[rp15] << 7) |
+ (parity[rp14] << 6) |
+ (parity[rp13] << 5) |
+ (parity[rp12] << 4) |
+ (parity[rp11] << 3) |
+ (parity[rp10] << 2) |
+ (parity[rp9] << 1) |
+ (parity[rp8]);
+ code[2] =
+ (parity[par & 0xf0] << 7) |
+ (parity[par & 0x0f] << 6) |
+ (parity[par & 0xcc] << 5) |
+ (parity[par & 0x33] << 4) |
+ (parity[par & 0xaa] << 3) |
+ (parity[par & 0x55] << 2);
+ code[0] = ~code[0];
+ code[1] = ~code[1];
+ code[2] = ~code[2];
+ }
The parity array is not shown any more. Note also that for these
examples I kinda deviated from my regular programming style by allowing
@@ -403,28 +428,32 @@ lookups
Attempt 3
=========
-Odd replaced:
- if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
- if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
- if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
- if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
- if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
- if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
-with
- if (i & 0x01) rp5 ^= cur;
- if (i & 0x02) rp7 ^= cur;
- if (i & 0x04) rp9 ^= cur;
- if (i & 0x08) rp11 ^= cur;
- if (i & 0x10) rp13 ^= cur;
- if (i & 0x20) rp15 ^= cur;
+Odd replaced::
- and outside the loop added:
- rp4 = par ^ rp5;
- rp6 = par ^ rp7;
- rp8 = par ^ rp9;
- rp10 = par ^ rp11;
- rp12 = par ^ rp13;
- rp14 = par ^ rp15;
+ if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
+ if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
+ if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
+ if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
+ if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
+ if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
+
+with::
+
+ if (i & 0x01) rp5 ^= cur;
+ if (i & 0x02) rp7 ^= cur;
+ if (i & 0x04) rp9 ^= cur;
+ if (i & 0x08) rp11 ^= cur;
+ if (i & 0x10) rp13 ^= cur;
+ if (i & 0x20) rp15 ^= cur;
+
+and outside the loop added::
+
+ rp4 = par ^ rp5;
+ rp6 = par ^ rp7;
+ rp8 = par ^ rp9;
+ rp10 = par ^ rp11;
+ rp12 = par ^ rp13;
+ rp14 = par ^ rp15;
And after that the code takes about 30% more time, although the number of
statements is reduced. This is also reflected in the assembly code.
@@ -448,7 +477,7 @@ Attempt 4
=========
Unrolled the loop 1, 2, 3 and 4 times.
-For 4 the code starts with:
+For 4 the code starts with::
for (i = 0; i < 4; i++)
{
@@ -471,8 +500,11 @@ Analysis 4
==========
Unrolling once gains about 15%
+
Unrolling twice keeps the gain at about 15%
+
Unrolling three times gives a gain of 30% compared to attempt 2.
+
Unrolling four times gives a marginal improvement compared to unrolling
three times.
@@ -492,8 +524,10 @@ Attempt 5
Effectively so all odd digit rp assignments in the loop were removed.
This included the else clause of the if statements.
-Of course after the loop we need to correct things by adding code like:
+Of course after the loop we need to correct things by adding code like::
+
rp5 = par ^ rp4;
+
Also the initial assignments (rp5 = 0; etc) could be removed.
Along the line I also removed the initialisation of rp0/1/2/3.
@@ -513,7 +547,7 @@ statement. Time for yet another version!
Attempt 6
=========
-THe code within the for loop was changed to:
+THe code within the for loop was changed to::
for (i = 0; i < 4; i++)
{
@@ -564,13 +598,17 @@ million iterations in order not to lose too much accuracy. This one
definitely seemed to be the jackpot!
There is a little bit more room for improvement though. There are three
-places with statements:
-rp4 ^= cur; rp6 ^= cur;
+places with statements::
+
+ rp4 ^= cur; rp6 ^= cur;
+
It seems more efficient to also maintain a variable rp4_6 in the while
loop; This eliminates 3 statements per loop. Of course after the loop we
-need to correct by adding:
- rp4 ^= rp4_6;
- rp6 ^= rp4_6
+need to correct by adding::
+
+ rp4 ^= rp4_6;
+ rp6 ^= rp4_6
+
Furthermore there are 4 sequential assignments to rp8. This can be
encoded slightly more efficiently by saving tmppar before those 4 lines
and later do rp8 = rp8 ^ tmppar ^ notrp8;
@@ -582,7 +620,7 @@ Time for a new test!
Attempt 7
=========
-The new code now looks like:
+The new code now looks like::
for (i = 0; i < 4; i++)
{
@@ -644,9 +682,12 @@ Although it seems that the code within the loop cannot be optimised
further there is still room to optimize the generation of the ecc codes.
We can simply calculate the total parity. If this is 0 then rp4 = rp5
etc. If the parity is 1, then rp4 = !rp5;
+
But if rp4 = rp5 we do not need rp5 etc. We can just write the even bits
-in the result byte and then do something like
+in the result byte and then do something like::
+
code[0] |= (code[0] << 1);
+
Lets test this.
@@ -657,11 +698,13 @@ Changed the code but again this slightly degrades performance. Tried all
kind of other things, like having dedicated parity arrays to avoid the
shift after parity[rp7] << 7; No gain.
Change the lookup using the parity array by using shift operators (e.g.
-replace parity[rp7] << 7 with:
-rp7 ^= (rp7 << 4);
-rp7 ^= (rp7 << 2);
-rp7 ^= (rp7 << 1);
-rp7 &= 0x80;
+replace parity[rp7] << 7 with::
+
+ rp7 ^= (rp7 << 4);
+ rp7 ^= (rp7 << 2);
+ rp7 ^= (rp7 << 1);
+ rp7 &= 0x80;
+
No gain.
The only marginal change was inverting the parity bits, so we can remove
@@ -683,13 +726,16 @@ Correcting errors
For correcting errors I again used the ST application note as a starter,
but I also peeked at the existing code.
+
The algorithm itself is pretty straightforward. Just xor the given and
the calculated ecc. If all bytes are 0 there is no problem. If 11 bits
are 1 we have one correctable bit error. If there is 1 bit 1, we have an
error in the given ecc code.
+
It proved to be fastest to do some table lookups. Performance gain
introduced by this is about a factor 2 on my system when a repair had to
be done, and 1% or so if no repair had to be done.
+
Code size increased from 330 bytes to 686 bytes for this function.
(gcc 4.2, -O3)
@@ -700,8 +746,10 @@ Conclusion
The gain when calculating the ecc is tremendous. Om my development hardware
a speedup of a factor of 18 for ecc calculation was achieved. On a test on an
embedded system with a MIPS core a factor 7 was obtained.
+
On a test with a Linksys NSLU2 (ARMv5TE processor) the speedup was a factor
5 (big endian mode, gcc 4.1.2, -O3)
+
For correction not much gain could be obtained (as bitflips are rare). Then
again there are also much less cycles spent there.
@@ -711,4 +759,5 @@ out of it with an assembler program, but due to pipeline behaviour etc
this is very tricky (at least for intel hw).
Author: Frans Meulenbroeks
+
Copyright (C) 2008 Koninklijke Philips Electronics NV.
diff --git a/Documentation/mtd/spi-nor.txt b/Documentation/mtd/spi-nor.rst
similarity index 94%
rename from Documentation/mtd/spi-nor.txt
rename to Documentation/mtd/spi-nor.rst
index da1fbff5a24c..f5333e3bf486 100644
--- a/Documentation/mtd/spi-nor.txt
+++ b/Documentation/mtd/spi-nor.rst
@@ -1,5 +1,6 @@
- SPI NOR framework
- ============================================
+=================
+SPI NOR framework
+=================
Part I - Why do we need this framework?
---------------------------------------
@@ -23,7 +24,7 @@ This framework just adds a new layer between the MTD and the SPI bus driver.
With this new layer, the SPI NOR controller driver does not depend on the
m25p80 code anymore.
- Before this framework, the layer is like:
+Before this framework, the layer is like::
MTD
------------------------
diff --git a/drivers/mtd/nand/raw/nand_ecc.c b/drivers/mtd/nand/raw/nand_ecc.c
index 223fbd8052b3..f6a7808db818 100644
--- a/drivers/mtd/nand/raw/nand_ecc.c
+++ b/drivers/mtd/nand/raw/nand_ecc.c
@@ -11,7 +11,7 @@
* Thomas Gleixner (tglx@linutronix.de)
*
* Information on how this algorithm works and how it was developed
- * can be found in Documentation/mtd/nand_ecc.txt
+ * can be found in Documentation/mtd/nand_ecc.rst
*/
#include <linux/types.h>
--
2.21.0
^ permalink raw reply related
* [PATCH v1 22/31] docs: leds: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Vadim Pasternak, Jacek Anaszewski, Pavel Machek,
Dan Murphy, Pablo Neira Ayuso, Jozsef Kadlecsik, Florian Westphal,
David S. Miller, linux-leds, netfilter-devel, coreteam, netdev
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the leds documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/laptops/thinkpad-acpi.txt | 4 +-
Documentation/leds/index.rst | 25 ++
.../leds/{leds-blinkm.txt => leds-blinkm.rst} | 64 ++---
...s-class-flash.txt => leds-class-flash.rst} | 49 ++--
.../leds/{leds-class.txt => leds-class.rst} | 15 +-
.../leds/{leds-lm3556.txt => leds-lm3556.rst} | 100 ++++++--
.../leds/{leds-lp3944.txt => leds-lp3944.rst} | 23 +-
Documentation/leds/leds-lp5521.rst | 115 +++++++++
Documentation/leds/leds-lp5521.txt | 101 --------
Documentation/leds/leds-lp5523.rst | 147 ++++++++++++
Documentation/leds/leds-lp5523.txt | 130 ----------
Documentation/leds/leds-lp5562.rst | 137 +++++++++++
Documentation/leds/leds-lp5562.txt | 120 ----------
Documentation/leds/leds-lp55xx.rst | 224 ++++++++++++++++++
Documentation/leds/leds-lp55xx.txt | 194 ---------------
Documentation/leds/leds-mlxcpld.rst | 118 +++++++++
Documentation/leds/leds-mlxcpld.txt | 110 ---------
...edtrig-oneshot.txt => ledtrig-oneshot.rst} | 11 +-
...ig-transient.txt => ledtrig-transient.rst} | 63 +++--
...edtrig-usbport.txt => ledtrig-usbport.rst} | 11 +-
Documentation/leds/{uleds.txt => uleds.rst} | 5 +-
MAINTAINERS | 2 +-
drivers/leds/trigger/Kconfig | 2 +-
drivers/leds/trigger/ledtrig-transient.c | 2 +-
net/netfilter/Kconfig | 2 +-
25 files changed, 996 insertions(+), 778 deletions(-)
create mode 100644 Documentation/leds/index.rst
rename Documentation/leds/{leds-blinkm.txt => leds-blinkm.rst} (57%)
rename Documentation/leds/{leds-class-flash.txt => leds-class-flash.rst} (74%)
rename Documentation/leds/{leds-class.txt => leds-class.rst} (92%)
rename Documentation/leds/{leds-lm3556.txt => leds-lm3556.rst} (70%)
rename Documentation/leds/{leds-lp3944.txt => leds-lp3944.rst} (78%)
create mode 100644 Documentation/leds/leds-lp5521.rst
delete mode 100644 Documentation/leds/leds-lp5521.txt
create mode 100644 Documentation/leds/leds-lp5523.rst
delete mode 100644 Documentation/leds/leds-lp5523.txt
create mode 100644 Documentation/leds/leds-lp5562.rst
delete mode 100644 Documentation/leds/leds-lp5562.txt
create mode 100644 Documentation/leds/leds-lp55xx.rst
delete mode 100644 Documentation/leds/leds-lp55xx.txt
create mode 100644 Documentation/leds/leds-mlxcpld.rst
delete mode 100644 Documentation/leds/leds-mlxcpld.txt
rename Documentation/leds/{ledtrig-oneshot.txt => ledtrig-oneshot.rst} (90%)
rename Documentation/leds/{ledtrig-transient.txt => ledtrig-transient.rst} (81%)
rename Documentation/leds/{ledtrig-usbport.txt => ledtrig-usbport.rst} (86%)
rename Documentation/leds/{uleds.txt => uleds.rst} (95%)
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index 6cced88de6da..75ef063622d2 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -679,7 +679,7 @@ status as "unknown". The available commands are:
sysfs notes:
The ThinkLight sysfs interface is documented by the LED class
-documentation, in Documentation/leds/leds-class.txt. The ThinkLight LED name
+documentation, in Documentation/leds/leds-class.rst. The ThinkLight LED name
is "tpacpi::thinklight".
Due to limitations in the sysfs LED class, if the status of the ThinkLight
@@ -779,7 +779,7 @@ All of the above can be turned on and off and can be made to blink.
sysfs notes:
The ThinkPad LED sysfs interface is described in detail by the LED class
-documentation, in Documentation/leds/leds-class.txt.
+documentation, in Documentation/leds/leds-class.rst.
The LEDs are named (in LED ID order, from 0 to 12):
"tpacpi::power", "tpacpi:orange:batt", "tpacpi:green:batt",
diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
new file mode 100644
index 000000000000..9885f7c1b75d
--- /dev/null
+++ b/Documentation/leds/index.rst
@@ -0,0 +1,25 @@
+:orphan:
+
+====
+LEDs
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ leds-class
+ leds-class-flash
+ ledtrig-oneshot
+ ledtrig-transient
+ ledtrig-usbport
+
+ uleds
+
+ leds-blinkm
+ leds-lm3556
+ leds-lp3944
+ leds-lp5521
+ leds-lp5523
+ leds-lp5562
+ leds-lp55xx
+ leds-mlxcpld
diff --git a/Documentation/leds/leds-blinkm.txt b/Documentation/leds/leds-blinkm.rst
similarity index 57%
rename from Documentation/leds/leds-blinkm.txt
rename to Documentation/leds/leds-blinkm.rst
index 9dd92f4cf4e1..c74b5bc877b1 100644
--- a/Documentation/leds/leds-blinkm.txt
+++ b/Documentation/leds/leds-blinkm.rst
@@ -1,3 +1,7 @@
+==================
+Leds BlinkM driver
+==================
+
The leds-blinkm driver supports the devices of the BlinkM family.
They are RGB-LED modules driven by a (AT)tiny microcontroller and
@@ -14,35 +18,36 @@ The interface this driver provides is 2-fold:
a) LED class interface for use with triggers
############################################
-The registration follows the scheme:
-blinkm-<i2c-bus-nr>-<i2c-device-nr>-<color>
+The registration follows the scheme::
-$ ls -h /sys/class/leds/blinkm-6-*
-/sys/class/leds/blinkm-6-9-blue:
-brightness device max_brightness power subsystem trigger uevent
+ blinkm-<i2c-bus-nr>-<i2c-device-nr>-<color>
-/sys/class/leds/blinkm-6-9-green:
-brightness device max_brightness power subsystem trigger uevent
+ $ ls -h /sys/class/leds/blinkm-6-*
+ /sys/class/leds/blinkm-6-9-blue:
+ brightness device max_brightness power subsystem trigger uevent
-/sys/class/leds/blinkm-6-9-red:
-brightness device max_brightness power subsystem trigger uevent
+ /sys/class/leds/blinkm-6-9-green:
+ brightness device max_brightness power subsystem trigger uevent
+
+ /sys/class/leds/blinkm-6-9-red:
+ brightness device max_brightness power subsystem trigger uevent
(same is /sys/bus/i2c/devices/6-0009/leds)
We can control the colors separated into red, green and blue and
assign triggers on each color.
-E.g.:
+E.g.::
-$ cat blinkm-6-9-blue/brightness
-05
+ $ cat blinkm-6-9-blue/brightness
+ 05
-$ echo 200 > blinkm-6-9-blue/brightness
-$
+ $ echo 200 > blinkm-6-9-blue/brightness
+ $
-$ modprobe ledtrig-heartbeat
-$ echo heartbeat > blinkm-6-9-green/trigger
-$
+ $ modprobe ledtrig-heartbeat
+ $ echo heartbeat > blinkm-6-9-green/trigger
+ $
b) Sysfs group to control rgb, fade, hsb, scripts ...
@@ -52,29 +57,28 @@ This extended interface is available as folder blinkm
in the sysfs folder of the I2C device.
E.g. below /sys/bus/i2c/devices/6-0009/blinkm
-$ ls -h /sys/bus/i2c/devices/6-0009/blinkm/
-blue green red test
+ $ ls -h /sys/bus/i2c/devices/6-0009/blinkm/
+ blue green red test
Currently supported is just setting red, green, blue
and a test sequence.
-E.g.:
+E.g.::
-$ cat *
-00
-00
-00
-#Write into test to start test sequence!#
+ $ cat *
+ 00
+ 00
+ 00
+ #Write into test to start test sequence!#
-$ echo 1 > test
-$
+ $ echo 1 > test
+ $
-$ echo 255 > red
-$
+ $ echo 255 > red
+ $
as of 6/2012
dl9pf <at> gmx <dot> de
-
diff --git a/Documentation/leds/leds-class-flash.txt b/Documentation/leds/leds-class-flash.rst
similarity index 74%
rename from Documentation/leds/leds-class-flash.txt
rename to Documentation/leds/leds-class-flash.rst
index 8da3c6f4b60b..6ec12c5a1a0e 100644
--- a/Documentation/leds/leds-class-flash.txt
+++ b/Documentation/leds/leds-class-flash.rst
@@ -1,9 +1,9 @@
-
+==============================
Flash LED handling under Linux
==============================
Some LED devices provide two modes - torch and flash. In the LED subsystem
-those modes are supported by LED class (see Documentation/leds/leds-class.txt)
+those modes are supported by LED class (see Documentation/leds/leds-class.rst)
and LED Flash class respectively. The torch mode related features are enabled
by default and the flash ones only if a driver declares it by setting
LED_DEV_CAP_FLASH flag.
@@ -14,6 +14,7 @@ registered in the LED subsystem with led_classdev_flash_register function.
Following sysfs attributes are exposed for controlling flash LED devices:
(see Documentation/ABI/testing/sysfs-class-led-flash)
+
- flash_brightness
- max_flash_brightness
- flash_timeout
@@ -31,30 +32,46 @@ be defined in the kernel config.
The driver must call the v4l2_flash_init function to get registered in the
V4L2 subsystem. The function takes six arguments:
-- dev : flash device, e.g. an I2C device
-- of_node : of_node of the LED, may be NULL if the same as device's
-- fled_cdev : LED flash class device to wrap
-- iled_cdev : LED flash class device representing indicator LED associated with
- fled_cdev, may be NULL
-- ops : V4L2 specific ops
- * external_strobe_set - defines the source of the flash LED strobe -
+
+- dev:
+ flash device, e.g. an I2C device
+- of_node:
+ of_node of the LED, may be NULL if the same as device's
+- fled_cdev:
+ LED flash class device to wrap
+- iled_cdev:
+ LED flash class device representing indicator LED associated with
+ fled_cdev, may be NULL
+- ops:
+ V4L2 specific ops
+
+ * external_strobe_set
+ defines the source of the flash LED strobe -
V4L2_CID_FLASH_STROBE control or external source, typically
a sensor, which makes it possible to synchronise the flash
strobe start with exposure start,
- * intensity_to_led_brightness and led_brightness_to_intensity - perform
+ * intensity_to_led_brightness and led_brightness_to_intensity
+ perform
enum led_brightness <-> V4L2 intensity conversion in a device
specific manner - they can be used for devices with non-linear
LED current scale.
-- config : configuration for V4L2 Flash sub-device
- * dev_name - the name of the media entity, unique in the system,
- * flash_faults - bitmask of flash faults that the LED flash class
+- config:
+ configuration for V4L2 Flash sub-device
+
+ * dev_name
+ the name of the media entity, unique in the system,
+ * flash_faults
+ bitmask of flash faults that the LED flash class
device can report; corresponding LED_FAULT* bit definitions are
available in <linux/led-class-flash.h>,
- * torch_intensity - constraints for the LED in TORCH mode
+ * torch_intensity
+ constraints for the LED in TORCH mode
in microamperes,
- * indicator_intensity - constraints for the indicator LED
+ * indicator_intensity
+ constraints for the indicator LED
in microamperes,
- * has_external_strobe - determines whether the flash strobe source
+ * has_external_strobe
+ determines whether the flash strobe source
can be switched to external,
On remove the v4l2_flash_release function has to be called, which takes one
diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.rst
similarity index 92%
rename from Documentation/leds/leds-class.txt
rename to Documentation/leds/leds-class.rst
index 8b39cc6b03ee..df0120a1ee3c 100644
--- a/Documentation/leds/leds-class.txt
+++ b/Documentation/leds/leds-class.rst
@@ -1,4 +1,4 @@
-
+========================
LED handling under Linux
========================
@@ -43,7 +43,7 @@ LED Device Naming
Is currently of the form:
-"devicename:colour:function"
+ "devicename:colour:function"
There have been calls for LED properties such as colour to be exported as
individual led class attributes. As a solution which doesn't incur as much
@@ -57,9 +57,12 @@ Brightness setting API
LED subsystem core exposes following API for setting brightness:
- - led_set_brightness : it is guaranteed not to sleep, passing LED_OFF stops
+ - led_set_brightness:
+ it is guaranteed not to sleep, passing LED_OFF stops
blinking,
- - led_set_brightness_sync : for use cases when immediate effect is desired -
+
+ - led_set_brightness_sync:
+ for use cases when immediate effect is desired -
it can block the caller for the time required for accessing
device registers and can sleep, passing LED_OFF stops hardware
blinking, returns -EBUSY if software blink fallback is enabled.
@@ -70,7 +73,7 @@ LED registration API
A driver wanting to register a LED classdev for use by other drivers /
userspace needs to allocate and fill a led_classdev struct and then call
-[devm_]led_classdev_register. If the non devm version is used the driver
+`[devm_]led_classdev_register`. If the non devm version is used the driver
must call led_classdev_unregister from its remove function before
free-ing the led_classdev struct.
@@ -94,7 +97,7 @@ with brightness value LED_OFF, which should stop any software
timers that may have been required for blinking.
The blink_set() function should choose a user friendly blinking value
-if it is called with *delay_on==0 && *delay_off==0 parameters. In this
+if it is called with `*delay_on==0` && `*delay_off==0` parameters. In this
case the driver should give back the chosen value through delay_on and
delay_off parameters to the leds subsystem.
diff --git a/Documentation/leds/leds-lm3556.txt b/Documentation/leds/leds-lm3556.rst
similarity index 70%
rename from Documentation/leds/leds-lm3556.txt
rename to Documentation/leds/leds-lm3556.rst
index 62278e871b50..1ef17d7d800e 100644
--- a/Documentation/leds/leds-lm3556.txt
+++ b/Documentation/leds/leds-lm3556.rst
@@ -1,68 +1,118 @@
+========================
Kernel driver for lm3556
========================
-*Texas Instrument:
- 1.5 A Synchronous Boost LED Flash Driver w/ High-Side Current Source
+* Texas Instrument:
+ 1.5 A Synchronous Boost LED Flash Driver w/ High-Side Current Source
* Datasheet: http://www.national.com/ds/LM/LM3556.pdf
Authors:
- Daniel Jeong
+ - Daniel Jeong
+
Contact:Daniel Jeong(daniel.jeong-at-ti.com, gshark.jeong-at-gmail.com)
Description
-----------
There are 3 functions in LM3556, Flash, Torch and Indicator.
-FLASH MODE
+Flash Mode
+^^^^^^^^^^
+
In Flash Mode, the LED current source(LED) provides 16 target current levels
from 93.75 mA to 1500 mA.The Flash currents are adjusted via the CURRENT
CONTROL REGISTER(0x09).Flash mode is activated by the ENABLE REGISTER(0x0A),
or by pulling the STROBE pin HIGH.
+
LM3556 Flash can be controlled through sys/class/leds/flash/brightness file
+
* if STROBE pin is enabled, below example control brightness only, and
-ON / OFF will be controlled by STROBE pin.
+ ON / OFF will be controlled by STROBE pin.
Flash Example:
-OFF : #echo 0 > sys/class/leds/flash/brightness
-93.75 mA: #echo 1 > sys/class/leds/flash/brightness
-... .....
-1500 mA: #echo 16 > sys/class/leds/flash/brightness
-TORCH MODE
+OFF::
+
+ #echo 0 > sys/class/leds/flash/brightness
+
+93.75 mA::
+
+ #echo 1 > sys/class/leds/flash/brightness
+
+...
+
+1500 mA::
+
+ #echo 16 > sys/class/leds/flash/brightness
+
+Torch Mode
+^^^^^^^^^^
+
In Torch Mode, the current source(LED) is programmed via the CURRENT CONTROL
REGISTER(0x09).Torch Mode is activated by the ENABLE REGISTER(0x0A) or by the
hardware TORCH input.
+
LM3556 torch can be controlled through sys/class/leds/torch/brightness file.
* if TORCH pin is enabled, below example control brightness only,
and ON / OFF will be controlled by TORCH pin.
Torch Example:
-OFF : #echo 0 > sys/class/leds/torch/brightness
-46.88 mA: #echo 1 > sys/class/leds/torch/brightness
-... .....
-375 mA : #echo 8 > sys/class/leds/torch/brightness
-INDICATOR MODE
+OFF::
+
+ #echo 0 > sys/class/leds/torch/brightness
+
+46.88 mA::
+
+ #echo 1 > sys/class/leds/torch/brightness
+
+...
+
+375 mA::
+
+ #echo 8 > sys/class/leds/torch/brightness
+
+Indicator Mode
+^^^^^^^^^^^^^^
+
Indicator pattern can be set through sys/class/leds/indicator/pattern file,
and 4 patterns are pre-defined in indicator_pattern array.
+
According to N-lank, Pulse time and N Period values, different pattern wiill
be generated.If you want new patterns for your own device, change
indicator_pattern array with your own values and INDIC_PATTERN_SIZE.
+
Please refer datasheet for more detail about N-Blank, Pulse time and N Period.
Indicator pattern example:
-pattern 0: #echo 0 > sys/class/leds/indicator/pattern
-....
-pattern 3: #echo 3 > sys/class/leds/indicator/pattern
+
+pattern 0::
+
+ #echo 0 > sys/class/leds/indicator/pattern
+
+...
+
+pattern 3::
+
+ #echo 3 > sys/class/leds/indicator/pattern
Indicator brightness can be controlled through
sys/class/leds/indicator/brightness file.
Example:
-OFF : #echo 0 > sys/class/leds/indicator/brightness
-5.86 mA : #echo 1 > sys/class/leds/indicator/brightness
-........
-46.875mA : #echo 8 > sys/class/leds/indicator/brightness
+
+OFF::
+
+ #echo 0 > sys/class/leds/indicator/brightness
+
+5.86 mA::
+
+ #echo 1 > sys/class/leds/indicator/brightness
+
+...
+
+46.875mA::
+
+ #echo 8 > sys/class/leds/indicator/brightness
Notes
-----
@@ -70,7 +120,8 @@ Driver expects it is registered using the i2c_board_info mechanism.
To register the chip at address 0x63 on specific adapter, set the platform data
according to include/linux/platform_data/leds-lm3556.h, set the i2c board info
-Example:
+Example::
+
static struct i2c_board_info board_i2c_ch4[] __initdata = {
{
I2C_BOARD_INFO(LM3556_NAME, 0x63),
@@ -80,6 +131,7 @@ Example:
and register it in the platform init function
-Example:
+Example::
+
board_register_i2c_bus(4, 400,
board_i2c_ch4, ARRAY_SIZE(board_i2c_ch4));
diff --git a/Documentation/leds/leds-lp3944.txt b/Documentation/leds/leds-lp3944.rst
similarity index 78%
rename from Documentation/leds/leds-lp3944.txt
rename to Documentation/leds/leds-lp3944.rst
index e88ac3b60c08..c2f87dc1a3a9 100644
--- a/Documentation/leds/leds-lp3944.txt
+++ b/Documentation/leds/leds-lp3944.rst
@@ -1,14 +1,20 @@
+====================
Kernel driver lp3944
====================
* National Semiconductor LP3944 Fun-light Chip
+
Prefix: 'lp3944'
+
Addresses scanned: None (see the Notes section below)
- Datasheet: Publicly available at the National Semiconductor website
- http://www.national.com/pf/LP/LP3944.html
+
+ Datasheet:
+
+ Publicly available at the National Semiconductor website
+ http://www.national.com/pf/LP/LP3944.html
Authors:
- Antonio Ospite <ospite@studenti.unina.it>
+ Antonio Ospite <ospite@studenti.unina.it>
Description
@@ -19,8 +25,11 @@ is used as a led controller.
The DIM modes are used to set _blink_ patterns for leds, the pattern is
specified supplying two parameters:
- - period: from 0s to 1.6s
- - duty cycle: percentage of the period the led is on, from 0 to 100
+
+ - period:
+ from 0s to 1.6s
+ - duty cycle:
+ percentage of the period the led is on, from 0 to 100
Setting a led in DIM0 or DIM1 mode makes it blink according to the pattern.
See the datasheet for details.
@@ -35,7 +44,7 @@ The chip is used mainly in embedded contexts, so this driver expects it is
registered using the i2c_board_info mechanism.
To register the chip at address 0x60 on adapter 0, set the platform data
-according to include/linux/leds-lp3944.h, set the i2c board info:
+according to include/linux/leds-lp3944.h, set the i2c board info::
static struct i2c_board_info a910_i2c_board_info[] __initdata = {
{
@@ -44,7 +53,7 @@ according to include/linux/leds-lp3944.h, set the i2c board info:
},
};
-and register it in the platform init function
+and register it in the platform init function::
i2c_register_board_info(0, a910_i2c_board_info,
ARRAY_SIZE(a910_i2c_board_info));
diff --git a/Documentation/leds/leds-lp5521.rst b/Documentation/leds/leds-lp5521.rst
new file mode 100644
index 000000000000..0432615b083d
--- /dev/null
+++ b/Documentation/leds/leds-lp5521.rst
@@ -0,0 +1,115 @@
+========================
+Kernel driver for lp5521
+========================
+
+* National Semiconductor LP5521 led driver chip
+* Datasheet: http://www.national.com/pf/LP/LP5521.html
+
+Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
+
+Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
+
+Description
+-----------
+
+LP5521 can drive up to 3 channels. Leds can be controlled directly via
+the led class control interface. Channels have generic names:
+lp5521:channelx, where x is 0 .. 2
+
+All three channels can be also controlled using the engine micro programs.
+More details of the instructions can be found from the public data sheet.
+
+LP5521 has the internal program memory for running various LED patterns.
+There are two ways to run LED patterns.
+
+1) Legacy interface - enginex_mode and enginex_load
+ Control interface for the engines:
+
+ x is 1 .. 3
+
+ enginex_mode:
+ disabled, load, run
+ enginex_load:
+ store program (visible only in engine load mode)
+
+ Example (start to blink the channel 2 led)::
+
+ cd /sys/class/leds/lp5521:channel2/device
+ echo "load" > engine3_mode
+ echo "037f4d0003ff6000" > engine3_load
+ echo "run" > engine3_mode
+
+ To stop the engine::
+
+ echo "disabled" > engine3_mode
+
+2) Firmware interface - LP55xx common interface
+
+For the details, please refer to 'firmware' section in leds-lp55xx.txt
+
+sysfs contains a selftest entry.
+
+The test communicates with the chip and checks that
+the clock mode is automatically set to the requested one.
+
+Each channel has its own led current settings.
+
+- /sys/class/leds/lp5521:channel0/led_current - RW
+- /sys/class/leds/lp5521:channel0/max_current - RO
+
+Format: 10x mA i.e 10 means 1.0 mA
+
+example platform data::
+
+ static struct lp55xx_led_config lp5521_led_config[] = {
+ {
+ .name = "red",
+ .chan_nr = 0,
+ .led_current = 50,
+ .max_current = 130,
+ }, {
+ .name = "green",
+ .chan_nr = 1,
+ .led_current = 0,
+ .max_current = 130,
+ }, {
+ .name = "blue",
+ .chan_nr = 2,
+ .led_current = 0,
+ .max_current = 130,
+ }
+ };
+
+ static int lp5521_setup(void)
+ {
+ /* setup HW resources */
+ }
+
+ static void lp5521_release(void)
+ {
+ /* Release HW resources */
+ }
+
+ static void lp5521_enable(bool state)
+ {
+ /* Control of chip enable signal */
+ }
+
+ static struct lp55xx_platform_data lp5521_platform_data = {
+ .led_config = lp5521_led_config,
+ .num_channels = ARRAY_SIZE(lp5521_led_config),
+ .clock_mode = LP55XX_CLOCK_EXT,
+ .setup_resources = lp5521_setup,
+ .release_resources = lp5521_release,
+ .enable = lp5521_enable,
+ };
+
+Note:
+ chan_nr can have values between 0 and 2.
+ The name of each channel can be configurable.
+ If the name field is not defined, the default name will be set to 'xxxx:channelN'
+ (XXXX : pdata->label or i2c client name, N : channel number)
+
+
+If the current is set to 0 in the platform data, that channel is
+disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp5521.txt b/Documentation/leds/leds-lp5521.txt
deleted file mode 100644
index d08d8c179f85..000000000000
--- a/Documentation/leds/leds-lp5521.txt
+++ /dev/null
@@ -1,101 +0,0 @@
-Kernel driver for lp5521
-========================
-
-* National Semiconductor LP5521 led driver chip
-* Datasheet: http://www.national.com/pf/LP/LP5521.html
-
-Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
-Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
-
-Description
------------
-
-LP5521 can drive up to 3 channels. Leds can be controlled directly via
-the led class control interface. Channels have generic names:
-lp5521:channelx, where x is 0 .. 2
-
-All three channels can be also controlled using the engine micro programs.
-More details of the instructions can be found from the public data sheet.
-
-LP5521 has the internal program memory for running various LED patterns.
-There are two ways to run LED patterns.
-
-1) Legacy interface - enginex_mode and enginex_load
- Control interface for the engines:
- x is 1 .. 3
- enginex_mode : disabled, load, run
- enginex_load : store program (visible only in engine load mode)
-
- Example (start to blink the channel 2 led):
- cd /sys/class/leds/lp5521:channel2/device
- echo "load" > engine3_mode
- echo "037f4d0003ff6000" > engine3_load
- echo "run" > engine3_mode
-
- To stop the engine:
- echo "disabled" > engine3_mode
-
-2) Firmware interface - LP55xx common interface
- For the details, please refer to 'firmware' section in leds-lp55xx.txt
-
-sysfs contains a selftest entry.
-The test communicates with the chip and checks that
-the clock mode is automatically set to the requested one.
-
-Each channel has its own led current settings.
-/sys/class/leds/lp5521:channel0/led_current - RW
-/sys/class/leds/lp5521:channel0/max_current - RO
-Format: 10x mA i.e 10 means 1.0 mA
-
-example platform data:
-
-Note: chan_nr can have values between 0 and 2.
-The name of each channel can be configurable.
-If the name field is not defined, the default name will be set to 'xxxx:channelN'
-(XXXX : pdata->label or i2c client name, N : channel number)
-
-static struct lp55xx_led_config lp5521_led_config[] = {
- {
- .name = "red",
- .chan_nr = 0,
- .led_current = 50,
- .max_current = 130,
- }, {
- .name = "green",
- .chan_nr = 1,
- .led_current = 0,
- .max_current = 130,
- }, {
- .name = "blue",
- .chan_nr = 2,
- .led_current = 0,
- .max_current = 130,
- }
-};
-
-static int lp5521_setup(void)
-{
- /* setup HW resources */
-}
-
-static void lp5521_release(void)
-{
- /* Release HW resources */
-}
-
-static void lp5521_enable(bool state)
-{
- /* Control of chip enable signal */
-}
-
-static struct lp55xx_platform_data lp5521_platform_data = {
- .led_config = lp5521_led_config,
- .num_channels = ARRAY_SIZE(lp5521_led_config),
- .clock_mode = LP55XX_CLOCK_EXT,
- .setup_resources = lp5521_setup,
- .release_resources = lp5521_release,
- .enable = lp5521_enable,
-};
-
-If the current is set to 0 in the platform data, that channel is
-disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp5523.rst b/Documentation/leds/leds-lp5523.rst
new file mode 100644
index 000000000000..7d7362a1dd57
--- /dev/null
+++ b/Documentation/leds/leds-lp5523.rst
@@ -0,0 +1,147 @@
+========================
+Kernel driver for lp5523
+========================
+
+* National Semiconductor LP5523 led driver chip
+* Datasheet: http://www.national.com/pf/LP/LP5523.html
+
+Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
+Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
+
+Description
+-----------
+LP5523 can drive up to 9 channels. Leds can be controlled directly via
+the led class control interface.
+The name of each channel is configurable in the platform data - name and label.
+There are three options to make the channel name.
+
+a) Define the 'name' in the platform data
+
+To make specific channel name, then use 'name' platform data.
+
+- /sys/class/leds/R1 (name: 'R1')
+- /sys/class/leds/B1 (name: 'B1')
+
+b) Use the 'label' with no 'name' field
+
+For one device name with channel number, then use 'label'.
+- /sys/class/leds/RGB:channelN (label: 'RGB', N: 0 ~ 8)
+
+c) Default
+
+If both fields are NULL, 'lp5523' is used by default.
+- /sys/class/leds/lp5523:channelN (N: 0 ~ 8)
+
+LP5523 has the internal program memory for running various LED patterns.
+There are two ways to run LED patterns.
+
+1) Legacy interface - enginex_mode, enginex_load and enginex_leds
+
+ Control interface for the engines:
+
+ x is 1 .. 3
+
+ enginex_mode:
+ disabled, load, run
+ enginex_load:
+ microcode load
+ enginex_leds:
+ led mux control
+
+ ::
+
+ cd /sys/class/leds/lp5523:channel2/device
+ echo "load" > engine3_mode
+ echo "9d80400004ff05ff437f0000" > engine3_load
+ echo "111111111" > engine3_leds
+ echo "run" > engine3_mode
+
+ To stop the engine::
+
+ echo "disabled" > engine3_mode
+
+2) Firmware interface - LP55xx common interface
+
+For the details, please refer to 'firmware' section in leds-lp55xx.txt
+
+LP5523 has three master faders. If a channel is mapped to one of
+the master faders, its output is dimmed based on the value of the master
+fader.
+
+For example::
+
+ echo "123000123" > master_fader_leds
+
+creates the following channel-fader mappings::
+
+ channel 0,6 to master_fader1
+ channel 1,7 to master_fader2
+ channel 2,8 to master_fader3
+
+Then, to have 25% of the original output on channel 0,6::
+
+ echo 64 > master_fader1
+
+To have 0% of the original output (i.e. no output) channel 1,7::
+
+ echo 0 > master_fader2
+
+To have 100% of the original output (i.e. no dimming) on channel 2,8::
+
+ echo 255 > master_fader3
+
+To clear all master fader controls::
+
+ echo "000000000" > master_fader_leds
+
+Selftest uses always the current from the platform data.
+
+Each channel contains led current settings.
+- /sys/class/leds/lp5523:channel2/led_current - RW
+- /sys/class/leds/lp5523:channel2/max_current - RO
+
+Format: 10x mA i.e 10 means 1.0 mA
+
+Example platform data::
+
+ static struct lp55xx_led_config lp5523_led_config[] = {
+ {
+ .name = "D1",
+ .chan_nr = 0,
+ .led_current = 50,
+ .max_current = 130,
+ },
+ ...
+ {
+ .chan_nr = 8,
+ .led_current = 50,
+ .max_current = 130,
+ }
+ };
+
+ static int lp5523_setup(void)
+ {
+ /* Setup HW resources */
+ }
+
+ static void lp5523_release(void)
+ {
+ /* Release HW resources */
+ }
+
+ static void lp5523_enable(bool state)
+ {
+ /* Control chip enable signal */
+ }
+
+ static struct lp55xx_platform_data lp5523_platform_data = {
+ .led_config = lp5523_led_config,
+ .num_channels = ARRAY_SIZE(lp5523_led_config),
+ .clock_mode = LP55XX_CLOCK_EXT,
+ .setup_resources = lp5523_setup,
+ .release_resources = lp5523_release,
+ .enable = lp5523_enable,
+ };
+
+Note
+ chan_nr can have values between 0 and 8.
diff --git a/Documentation/leds/leds-lp5523.txt b/Documentation/leds/leds-lp5523.txt
deleted file mode 100644
index 0961a060fc4d..000000000000
--- a/Documentation/leds/leds-lp5523.txt
+++ /dev/null
@@ -1,130 +0,0 @@
-Kernel driver for lp5523
-========================
-
-* National Semiconductor LP5523 led driver chip
-* Datasheet: http://www.national.com/pf/LP/LP5523.html
-
-Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
-Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
-
-Description
------------
-LP5523 can drive up to 9 channels. Leds can be controlled directly via
-the led class control interface.
-The name of each channel is configurable in the platform data - name and label.
-There are three options to make the channel name.
-
-a) Define the 'name' in the platform data
-To make specific channel name, then use 'name' platform data.
-/sys/class/leds/R1 (name: 'R1')
-/sys/class/leds/B1 (name: 'B1')
-
-b) Use the 'label' with no 'name' field
-For one device name with channel number, then use 'label'.
-/sys/class/leds/RGB:channelN (label: 'RGB', N: 0 ~ 8)
-
-c) Default
-If both fields are NULL, 'lp5523' is used by default.
-/sys/class/leds/lp5523:channelN (N: 0 ~ 8)
-
-LP5523 has the internal program memory for running various LED patterns.
-There are two ways to run LED patterns.
-
-1) Legacy interface - enginex_mode, enginex_load and enginex_leds
- Control interface for the engines:
- x is 1 .. 3
- enginex_mode : disabled, load, run
- enginex_load : microcode load
- enginex_leds : led mux control
-
- cd /sys/class/leds/lp5523:channel2/device
- echo "load" > engine3_mode
- echo "9d80400004ff05ff437f0000" > engine3_load
- echo "111111111" > engine3_leds
- echo "run" > engine3_mode
-
- To stop the engine:
- echo "disabled" > engine3_mode
-
-2) Firmware interface - LP55xx common interface
- For the details, please refer to 'firmware' section in leds-lp55xx.txt
-
-LP5523 has three master faders. If a channel is mapped to one of
-the master faders, its output is dimmed based on the value of the master
-fader.
-
-For example,
-
- echo "123000123" > master_fader_leds
-
-creates the following channel-fader mappings:
-
- channel 0,6 to master_fader1
- channel 1,7 to master_fader2
- channel 2,8 to master_fader3
-
-Then, to have 25% of the original output on channel 0,6:
-
- echo 64 > master_fader1
-
-To have 0% of the original output (i.e. no output) channel 1,7:
-
- echo 0 > master_fader2
-
-To have 100% of the original output (i.e. no dimming) on channel 2,8:
-
- echo 255 > master_fader3
-
-To clear all master fader controls:
-
- echo "000000000" > master_fader_leds
-
-Selftest uses always the current from the platform data.
-
-Each channel contains led current settings.
-/sys/class/leds/lp5523:channel2/led_current - RW
-/sys/class/leds/lp5523:channel2/max_current - RO
-Format: 10x mA i.e 10 means 1.0 mA
-
-Example platform data:
-
-Note - chan_nr can have values between 0 and 8.
-
-static struct lp55xx_led_config lp5523_led_config[] = {
- {
- .name = "D1",
- .chan_nr = 0,
- .led_current = 50,
- .max_current = 130,
- },
-...
- {
- .chan_nr = 8,
- .led_current = 50,
- .max_current = 130,
- }
-};
-
-static int lp5523_setup(void)
-{
- /* Setup HW resources */
-}
-
-static void lp5523_release(void)
-{
- /* Release HW resources */
-}
-
-static void lp5523_enable(bool state)
-{
- /* Control chip enable signal */
-}
-
-static struct lp55xx_platform_data lp5523_platform_data = {
- .led_config = lp5523_led_config,
- .num_channels = ARRAY_SIZE(lp5523_led_config),
- .clock_mode = LP55XX_CLOCK_EXT,
- .setup_resources = lp5523_setup,
- .release_resources = lp5523_release,
- .enable = lp5523_enable,
-};
diff --git a/Documentation/leds/leds-lp5562.rst b/Documentation/leds/leds-lp5562.rst
new file mode 100644
index 000000000000..79bbb2487ff6
--- /dev/null
+++ b/Documentation/leds/leds-lp5562.rst
@@ -0,0 +1,137 @@
+========================
+Kernel driver for lp5562
+========================
+
+* TI LP5562 LED Driver
+
+Author: Milo(Woogyom) Kim <milo.kim@ti.com>
+
+Description
+===========
+
+ LP5562 can drive up to 4 channels. R/G/B and White.
+ LEDs can be controlled directly via the led class control interface.
+
+ All four channels can be also controlled using the engine micro programs.
+ LP5562 has the internal program memory for running various LED patterns.
+ For the details, please refer to 'firmware' section in leds-lp55xx.txt
+
+Device attribute
+================
+
+engine_mux
+ 3 Engines are allocated in LP5562, but the number of channel is 4.
+ Therefore each channel should be mapped to the engine number.
+
+ Value: RGB or W
+
+ This attribute is used for programming LED data with the firmware interface.
+ Unlike the LP5521/LP5523/55231, LP5562 has unique feature for the engine mux,
+ so additional sysfs is required
+
+ LED Map
+
+ ===== === ===============================
+ Red ... Engine 1 (fixed)
+ Green ... Engine 2 (fixed)
+ Blue ... Engine 3 (fixed)
+ White ... Engine 1 or 2 or 3 (selective)
+ ===== === ===============================
+
+How to load the program data using engine_mux
+=============================================
+
+ Before loading the LP5562 program data, engine_mux should be written between
+ the engine selection and loading the firmware.
+ Engine mux has two different mode, RGB and W.
+ RGB is used for loading RGB program data, W is used for W program data.
+
+ For example, run blinking green channel pattern::
+
+ echo 2 > /sys/bus/i2c/devices/xxxx/select_engine # 2 is for green channel
+ echo "RGB" > /sys/bus/i2c/devices/xxxx/engine_mux # engine mux for RGB
+ echo 1 > /sys/class/firmware/lp5562/loading
+ echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
+ echo 0 > /sys/class/firmware/lp5562/loading
+ echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+ To run a blinking white pattern::
+
+ echo 1 or 2 or 3 > /sys/bus/i2c/devices/xxxx/select_engine
+ echo "W" > /sys/bus/i2c/devices/xxxx/engine_mux
+ echo 1 > /sys/class/firmware/lp5562/loading
+ echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
+ echo 0 > /sys/class/firmware/lp5562/loading
+ echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+How to load the predefined patterns
+===================================
+
+ Please refer to 'leds-lp55xx.txt"
+
+Setting Current of Each Channel
+===============================
+
+ Like LP5521 and LP5523/55231, LP5562 provides LED current settings.
+ The 'led_current' and 'max_current' are used.
+
+Example of Platform data
+========================
+
+::
+
+ static struct lp55xx_led_config lp5562_led_config[] = {
+ {
+ .name = "R",
+ .chan_nr = 0,
+ .led_current = 20,
+ .max_current = 40,
+ },
+ {
+ .name = "G",
+ .chan_nr = 1,
+ .led_current = 20,
+ .max_current = 40,
+ },
+ {
+ .name = "B",
+ .chan_nr = 2,
+ .led_current = 20,
+ .max_current = 40,
+ },
+ {
+ .name = "W",
+ .chan_nr = 3,
+ .led_current = 20,
+ .max_current = 40,
+ },
+ };
+
+ static int lp5562_setup(void)
+ {
+ /* setup HW resources */
+ }
+
+ static void lp5562_release(void)
+ {
+ /* Release HW resources */
+ }
+
+ static void lp5562_enable(bool state)
+ {
+ /* Control of chip enable signal */
+ }
+
+ static struct lp55xx_platform_data lp5562_platform_data = {
+ .led_config = lp5562_led_config,
+ .num_channels = ARRAY_SIZE(lp5562_led_config),
+ .setup_resources = lp5562_setup,
+ .release_resources = lp5562_release,
+ .enable = lp5562_enable,
+ };
+
+To configure the platform specific data, lp55xx_platform_data structure is used
+
+
+If the current is set to 0 in the platform data, that channel is
+disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp5562.txt b/Documentation/leds/leds-lp5562.txt
deleted file mode 100644
index 5a823ff6b393..000000000000
--- a/Documentation/leds/leds-lp5562.txt
+++ /dev/null
@@ -1,120 +0,0 @@
-Kernel driver for LP5562
-========================
-
-* TI LP5562 LED Driver
-
-Author: Milo(Woogyom) Kim <milo.kim@ti.com>
-
-Description
-
- LP5562 can drive up to 4 channels. R/G/B and White.
- LEDs can be controlled directly via the led class control interface.
-
- All four channels can be also controlled using the engine micro programs.
- LP5562 has the internal program memory for running various LED patterns.
- For the details, please refer to 'firmware' section in leds-lp55xx.txt
-
-Device attribute: engine_mux
-
- 3 Engines are allocated in LP5562, but the number of channel is 4.
- Therefore each channel should be mapped to the engine number.
- Value : RGB or W
-
- This attribute is used for programming LED data with the firmware interface.
- Unlike the LP5521/LP5523/55231, LP5562 has unique feature for the engine mux,
- so additional sysfs is required.
-
- LED Map
- Red ... Engine 1 (fixed)
- Green ... Engine 2 (fixed)
- Blue ... Engine 3 (fixed)
- White ... Engine 1 or 2 or 3 (selective)
-
-How to load the program data using engine_mux
-
- Before loading the LP5562 program data, engine_mux should be written between
- the engine selection and loading the firmware.
- Engine mux has two different mode, RGB and W.
- RGB is used for loading RGB program data, W is used for W program data.
-
- For example, run blinking green channel pattern,
- echo 2 > /sys/bus/i2c/devices/xxxx/select_engine # 2 is for green channel
- echo "RGB" > /sys/bus/i2c/devices/xxxx/engine_mux # engine mux for RGB
- echo 1 > /sys/class/firmware/lp5562/loading
- echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
- echo 0 > /sys/class/firmware/lp5562/loading
- echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
- To run a blinking white pattern,
- echo 1 or 2 or 3 > /sys/bus/i2c/devices/xxxx/select_engine
- echo "W" > /sys/bus/i2c/devices/xxxx/engine_mux
- echo 1 > /sys/class/firmware/lp5562/loading
- echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
- echo 0 > /sys/class/firmware/lp5562/loading
- echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-How to load the predefined patterns
-
- Please refer to 'leds-lp55xx.txt"
-
-Setting Current of Each Channel
-
- Like LP5521 and LP5523/55231, LP5562 provides LED current settings.
- The 'led_current' and 'max_current' are used.
-
-(Example of Platform data)
-
-To configure the platform specific data, lp55xx_platform_data structure is used.
-
-static struct lp55xx_led_config lp5562_led_config[] = {
- {
- .name = "R",
- .chan_nr = 0,
- .led_current = 20,
- .max_current = 40,
- },
- {
- .name = "G",
- .chan_nr = 1,
- .led_current = 20,
- .max_current = 40,
- },
- {
- .name = "B",
- .chan_nr = 2,
- .led_current = 20,
- .max_current = 40,
- },
- {
- .name = "W",
- .chan_nr = 3,
- .led_current = 20,
- .max_current = 40,
- },
-};
-
-static int lp5562_setup(void)
-{
- /* setup HW resources */
-}
-
-static void lp5562_release(void)
-{
- /* Release HW resources */
-}
-
-static void lp5562_enable(bool state)
-{
- /* Control of chip enable signal */
-}
-
-static struct lp55xx_platform_data lp5562_platform_data = {
- .led_config = lp5562_led_config,
- .num_channels = ARRAY_SIZE(lp5562_led_config),
- .setup_resources = lp5562_setup,
- .release_resources = lp5562_release,
- .enable = lp5562_enable,
-};
-
-If the current is set to 0 in the platform data, that channel is
-disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp55xx.rst b/Documentation/leds/leds-lp55xx.rst
new file mode 100644
index 000000000000..632e41cec0b5
--- /dev/null
+++ b/Documentation/leds/leds-lp55xx.rst
@@ -0,0 +1,224 @@
+=================================================
+LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
+=================================================
+
+Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
+
+Description
+-----------
+LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.
+
+ Register access via the I2C
+ Device initialization/deinitialization
+ Create LED class devices for multiple output channels
+ Device attributes for user-space interface
+ Program memory for running LED patterns
+
+The LP55xx common driver provides these features using exported functions.
+
+ lp55xx_init_device() / lp55xx_deinit_device()
+ lp55xx_register_leds() / lp55xx_unregister_leds()
+ lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()
+
+( Driver Structure Data )
+
+In lp55xx common driver, two different data structure is used.
+
+* lp55xx_led
+ control multi output LED channels such as led current, channel index.
+* lp55xx_chip
+ general chip control such like the I2C and platform data.
+
+For example, LP5521 has maximum 3 LED channels.
+LP5523/55231 has 9 output channels::
+
+ lp55xx_chip for LP5521 ... lp55xx_led #1
+ lp55xx_led #2
+ lp55xx_led #3
+
+ lp55xx_chip for LP5523 ... lp55xx_led #1
+ lp55xx_led #2
+ .
+ .
+ lp55xx_led #9
+
+( Chip Dependent Code )
+
+To support device specific configurations, special structure
+'lpxx_device_config' is used.
+
+ - Maximum number of channels
+ - Reset command, chip enable command
+ - Chip specific initialization
+ - Brightness control register access
+ - Setting LED output current
+ - Program memory address access for running patterns
+ - Additional device specific attributes
+
+( Firmware Interface )
+
+LP55xx family devices have the internal program memory for running
+various LED patterns.
+
+This pattern data is saved as a file in the user-land or
+hex byte string is written into the memory through the I2C.
+
+LP55xx common driver supports the firmware interface.
+
+LP55xx chips have three program engines.
+
+To load and run the pattern, the programming sequence is following.
+
+ (1) Select an engine number (1/2/3)
+ (2) Mode change to load
+ (3) Write pattern data into selected area
+ (4) Mode change to run
+
+The LP55xx common driver provides simple interfaces as below.
+
+select_engine:
+ Select which engine is used for running program
+run_engine:
+ Start program which is loaded via the firmware interface
+firmware:
+ Load program data
+
+In case of LP5523, one more command is required, 'enginex_leds'.
+It is used for selecting LED output(s) at each engine number.
+In more details, please refer to 'leds-lp5523.txt'.
+
+For example, run blinking pattern in engine #1 of LP5521::
+
+ echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
+ echo 1 > /sys/class/firmware/lp5521/loading
+ echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
+ echo 0 > /sys/class/firmware/lp5521/loading
+ echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+For example, run blinking pattern in engine #3 of LP55231
+
+Two LEDs are configured as pattern output channels::
+
+ echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
+ echo 1 > /sys/class/firmware/lp55231/loading
+ echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
+ echo 0 > /sys/class/firmware/lp55231/loading
+ echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
+ echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+To start blinking patterns in engine #2 and #3 simultaneously::
+
+ for idx in 2 3
+ do
+ echo $idx > /sys/class/leds/red/device/select_engine
+ sleep 0.1
+ echo 1 > /sys/class/firmware/lp5521/loading
+ echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
+ echo 0 > /sys/class/firmware/lp5521/loading
+ done
+ echo 1 > /sys/class/leds/red/device/run_engine
+
+Here is another example for LP5523.
+
+Full LED strings are selected by 'engine2_leds'::
+
+ echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
+ echo 1 > /sys/class/firmware/lp5523/loading
+ echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
+ echo 0 > /sys/class/firmware/lp5523/loading
+ echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
+ echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+As soon as 'loading' is set to 0, registered callback is called.
+Inside the callback, the selected engine is loaded and memory is updated.
+To run programmed pattern, 'run_engine' attribute should be enabled.
+
+The pattern sequence of LP8501 is similar to LP5523.
+
+However pattern data is specific.
+
+Ex 1) Engine 1 is used::
+
+ echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
+ echo 1 > /sys/class/firmware/lp8501/loading
+ echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
+ echo 0 > /sys/class/firmware/lp8501/loading
+ echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+Ex 2) Engine 2 and 3 are used at the same time::
+
+ echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
+ sleep 1
+ echo 1 > /sys/class/firmware/lp8501/loading
+ echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
+ echo 0 > /sys/class/firmware/lp8501/loading
+ sleep 1
+ echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
+ sleep 1
+ echo 1 > /sys/class/firmware/lp8501/loading
+ echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
+ echo 0 > /sys/class/firmware/lp8501/loading
+ sleep 1
+ echo 1 > /sys/class/leds/d1/device/run_engine
+
+( 'run_engine' and 'firmware_cb' )
+
+The sequence of running the program data is common.
+
+But each device has own specific register addresses for commands.
+
+To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
+
+run_engine:
+ Control the selected engine
+firmware_cb:
+ The callback function after loading the firmware is done.
+
+ Chip specific commands for loading and updating program memory.
+
+( Predefined pattern data )
+
+Without the firmware interface, LP55xx driver provides another method for
+loading a LED pattern. That is 'predefined' pattern.
+
+A predefined pattern is defined in the platform data and load it(or them)
+via the sysfs if needed.
+
+To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
+configured.
+
+Example of predefined pattern data::
+
+ /* mode_1: blinking data */
+ static const u8 mode_1[] = {
+ 0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
+ };
+
+ /* mode_2: always on */
+ static const u8 mode_2[] = { 0x40, 0xFF, };
+
+ struct lp55xx_predef_pattern board_led_patterns[] = {
+ {
+ .r = mode_1,
+ .size_r = ARRAY_SIZE(mode_1),
+ },
+ {
+ .b = mode_2,
+ .size_b = ARRAY_SIZE(mode_2),
+ },
+ }
+
+ struct lp55xx_platform_data lp5562_pdata = {
+ ...
+ .patterns = board_led_patterns,
+ .num_patterns = ARRAY_SIZE(board_led_patterns),
+ };
+
+Then, mode_1 and mode_2 can be run via through the sysfs::
+
+ echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern # red blinking LED pattern
+ echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern # blue LED always on
+
+To stop running pattern::
+
+ echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern
diff --git a/Documentation/leds/leds-lp55xx.txt b/Documentation/leds/leds-lp55xx.txt
deleted file mode 100644
index e23fa91ea722..000000000000
--- a/Documentation/leds/leds-lp55xx.txt
+++ /dev/null
@@ -1,194 +0,0 @@
-LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
-=================================================
-
-Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
-
-Description
------------
-LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.
-
- Register access via the I2C
- Device initialization/deinitialization
- Create LED class devices for multiple output channels
- Device attributes for user-space interface
- Program memory for running LED patterns
-
-The LP55xx common driver provides these features using exported functions.
- lp55xx_init_device() / lp55xx_deinit_device()
- lp55xx_register_leds() / lp55xx_unregister_leds()
- lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()
-
-( Driver Structure Data )
-
-In lp55xx common driver, two different data structure is used.
-
-o lp55xx_led
- control multi output LED channels such as led current, channel index.
-o lp55xx_chip
- general chip control such like the I2C and platform data.
-
-For example, LP5521 has maximum 3 LED channels.
-LP5523/55231 has 9 output channels.
-
-lp55xx_chip for LP5521 ... lp55xx_led #1
- lp55xx_led #2
- lp55xx_led #3
-
-lp55xx_chip for LP5523 ... lp55xx_led #1
- lp55xx_led #2
- .
- .
- lp55xx_led #9
-
-( Chip Dependent Code )
-
-To support device specific configurations, special structure
-'lpxx_device_config' is used.
-
- Maximum number of channels
- Reset command, chip enable command
- Chip specific initialization
- Brightness control register access
- Setting LED output current
- Program memory address access for running patterns
- Additional device specific attributes
-
-( Firmware Interface )
-
-LP55xx family devices have the internal program memory for running
-various LED patterns.
-This pattern data is saved as a file in the user-land or
-hex byte string is written into the memory through the I2C.
-LP55xx common driver supports the firmware interface.
-
-LP55xx chips have three program engines.
-To load and run the pattern, the programming sequence is following.
- (1) Select an engine number (1/2/3)
- (2) Mode change to load
- (3) Write pattern data into selected area
- (4) Mode change to run
-
-The LP55xx common driver provides simple interfaces as below.
-select_engine : Select which engine is used for running program
-run_engine : Start program which is loaded via the firmware interface
-firmware : Load program data
-
-In case of LP5523, one more command is required, 'enginex_leds'.
-It is used for selecting LED output(s) at each engine number.
-In more details, please refer to 'leds-lp5523.txt'.
-
-For example, run blinking pattern in engine #1 of LP5521
-echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp5521/loading
-echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
-echo 0 > /sys/class/firmware/lp5521/loading
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-For example, run blinking pattern in engine #3 of LP55231
-Two LEDs are configured as pattern output channels.
-echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp55231/loading
-echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
-echo 0 > /sys/class/firmware/lp55231/loading
-echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-To start blinking patterns in engine #2 and #3 simultaneously,
-for idx in 2 3
-do
- echo $idx > /sys/class/leds/red/device/select_engine
- sleep 0.1
- echo 1 > /sys/class/firmware/lp5521/loading
- echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
- echo 0 > /sys/class/firmware/lp5521/loading
-done
-echo 1 > /sys/class/leds/red/device/run_engine
-
-Here is another example for LP5523.
-Full LED strings are selected by 'engine2_leds'.
-echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp5523/loading
-echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
-echo 0 > /sys/class/firmware/lp5523/loading
-echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-As soon as 'loading' is set to 0, registered callback is called.
-Inside the callback, the selected engine is loaded and memory is updated.
-To run programmed pattern, 'run_engine' attribute should be enabled.
-
-The pattern sequence of LP8501 is similar to LP5523.
-However pattern data is specific.
-Ex 1) Engine 1 is used
-echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp8501/loading
-echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
-echo 0 > /sys/class/firmware/lp8501/loading
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-Ex 2) Engine 2 and 3 are used at the same time
-echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
-sleep 1
-echo 1 > /sys/class/firmware/lp8501/loading
-echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
-echo 0 > /sys/class/firmware/lp8501/loading
-sleep 1
-echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
-sleep 1
-echo 1 > /sys/class/firmware/lp8501/loading
-echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
-echo 0 > /sys/class/firmware/lp8501/loading
-sleep 1
-echo 1 > /sys/class/leds/d1/device/run_engine
-
-( 'run_engine' and 'firmware_cb' )
-The sequence of running the program data is common.
-But each device has own specific register addresses for commands.
-To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
-run_engine : Control the selected engine
-firmware_cb : The callback function after loading the firmware is done.
- Chip specific commands for loading and updating program memory.
-
-( Predefined pattern data )
-
-Without the firmware interface, LP55xx driver provides another method for
-loading a LED pattern. That is 'predefined' pattern.
-A predefined pattern is defined in the platform data and load it(or them)
-via the sysfs if needed.
-To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
-configured.
-
- Example of predefined pattern data:
-
- /* mode_1: blinking data */
- static const u8 mode_1[] = {
- 0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
- };
-
- /* mode_2: always on */
- static const u8 mode_2[] = { 0x40, 0xFF, };
-
- struct lp55xx_predef_pattern board_led_patterns[] = {
- {
- .r = mode_1,
- .size_r = ARRAY_SIZE(mode_1),
- },
- {
- .b = mode_2,
- .size_b = ARRAY_SIZE(mode_2),
- },
- }
-
- struct lp55xx_platform_data lp5562_pdata = {
- ...
- .patterns = board_led_patterns,
- .num_patterns = ARRAY_SIZE(board_led_patterns),
- };
-
-Then, mode_1 and mode_2 can be run via through the sysfs.
-
- echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern # red blinking LED pattern
- echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern # blue LED always on
-
-To stop running pattern,
- echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern
diff --git a/Documentation/leds/leds-mlxcpld.rst b/Documentation/leds/leds-mlxcpld.rst
new file mode 100644
index 000000000000..528582429e0b
--- /dev/null
+++ b/Documentation/leds/leds-mlxcpld.rst
@@ -0,0 +1,118 @@
+=======================================
+Kernel driver for Mellanox systems LEDs
+=======================================
+
+Provide system LED support for the nex Mellanox systems:
+"msx6710", "msx6720", "msb7700", "msn2700", "msx1410",
+"msn2410", "msb7800", "msn2740", "msn2100".
+
+Description
+-----------
+Driver provides the following LEDs for the systems "msx6710", "msx6720",
+"msb7700", "msn2700", "msx1410", "msn2410", "msb7800", "msn2740":
+
+ - mlxcpld:fan1:green
+ - mlxcpld:fan1:red
+ - mlxcpld:fan2:green
+ - mlxcpld:fan2:red
+ - mlxcpld:fan3:green
+ - mlxcpld:fan3:red
+ - mlxcpld:fan4:green
+ - mlxcpld:fan4:red
+ - mlxcpld:psu:green
+ - mlxcpld:psu:red
+ - mlxcpld:status:green
+ - mlxcpld:status:red
+
+ "status"
+ - CPLD reg offset: 0x20
+ - Bits [3:0]
+
+ "psu"
+ - CPLD reg offset: 0x20
+ - Bits [7:4]
+
+ "fan1"
+ - CPLD reg offset: 0x21
+ - Bits [3:0]
+
+ "fan2"
+ - CPLD reg offset: 0x21
+ - Bits [7:4]
+
+ "fan3"
+ - CPLD reg offset: 0x22
+ - Bits [3:0]
+
+ "fan4"
+ - CPLD reg offset: 0x22
+ - Bits [7:4]
+
+ Color mask for all the above LEDs:
+
+ [bit3,bit2,bit1,bit0] or
+ [bit7,bit6,bit5,bit4]:
+
+ - [0,0,0,0] = LED OFF
+ - [0,1,0,1] = Red static ON
+ - [1,1,0,1] = Green static ON
+ - [0,1,1,0] = Red blink 3Hz
+ - [1,1,1,0] = Green blink 3Hz
+ - [0,1,1,1] = Red blink 6Hz
+ - [1,1,1,1] = Green blink 6Hz
+
+Driver provides the following LEDs for the system "msn2100":
+
+ - mlxcpld:fan:green
+ - mlxcpld:fan:red
+ - mlxcpld:psu1:green
+ - mlxcpld:psu1:red
+ - mlxcpld:psu2:green
+ - mlxcpld:psu2:red
+ - mlxcpld:status:green
+ - mlxcpld:status:red
+ - mlxcpld:uid:blue
+
+ "status"
+ - CPLD reg offset: 0x20
+ - Bits [3:0]
+
+ "fan"
+ - CPLD reg offset: 0x21
+ - Bits [3:0]
+
+ "psu1"
+ - CPLD reg offset: 0x23
+ - Bits [3:0]
+
+ "psu2"
+ - CPLD reg offset: 0x23
+ - Bits [7:4]
+
+ "uid"
+ - CPLD reg offset: 0x24
+ - Bits [3:0]
+
+ Color mask for all the above LEDs, excepted uid:
+
+ [bit3,bit2,bit1,bit0] or
+ [bit7,bit6,bit5,bit4]:
+
+ - [0,0,0,0] = LED OFF
+ - [0,1,0,1] = Red static ON
+ - [1,1,0,1] = Green static ON
+ - [0,1,1,0] = Red blink 3Hz
+ - [1,1,1,0] = Green blink 3Hz
+ - [0,1,1,1] = Red blink 6Hz
+ - [1,1,1,1] = Green blink 6Hz
+
+ Color mask for uid LED:
+ [bit3,bit2,bit1,bit0]:
+
+ - [0,0,0,0] = LED OFF
+ - [1,1,0,1] = Blue static ON
+ - [1,1,1,0] = Blue blink 3Hz
+ - [1,1,1,1] = Blue blink 6Hz
+
+Driver supports HW blinking at 3Hz and 6Hz frequency (50% duty cycle).
+For 3Hz duty cylce is about 167 msec, for 6Hz is about 83 msec.
diff --git a/Documentation/leds/leds-mlxcpld.txt b/Documentation/leds/leds-mlxcpld.txt
deleted file mode 100644
index a0e8fd457117..000000000000
--- a/Documentation/leds/leds-mlxcpld.txt
+++ /dev/null
@@ -1,110 +0,0 @@
-Kernel driver for Mellanox systems LEDs
-=======================================
-
-Provide system LED support for the nex Mellanox systems:
-"msx6710", "msx6720", "msb7700", "msn2700", "msx1410",
-"msn2410", "msb7800", "msn2740", "msn2100".
-
-Description
------------
-Driver provides the following LEDs for the systems "msx6710", "msx6720",
-"msb7700", "msn2700", "msx1410", "msn2410", "msb7800", "msn2740":
- mlxcpld:fan1:green
- mlxcpld:fan1:red
- mlxcpld:fan2:green
- mlxcpld:fan2:red
- mlxcpld:fan3:green
- mlxcpld:fan3:red
- mlxcpld:fan4:green
- mlxcpld:fan4:red
- mlxcpld:psu:green
- mlxcpld:psu:red
- mlxcpld:status:green
- mlxcpld:status:red
-
- "status"
- CPLD reg offset: 0x20
- Bits [3:0]
-
- "psu"
- CPLD reg offset: 0x20
- Bits [7:4]
-
- "fan1"
- CPLD reg offset: 0x21
- Bits [3:0]
-
- "fan2"
- CPLD reg offset: 0x21
- Bits [7:4]
-
- "fan3"
- CPLD reg offset: 0x22
- Bits [3:0]
-
- "fan4"
- CPLD reg offset: 0x22
- Bits [7:4]
-
- Color mask for all the above LEDs:
- [bit3,bit2,bit1,bit0] or
- [bit7,bit6,bit5,bit4]:
- [0,0,0,0] = LED OFF
- [0,1,0,1] = Red static ON
- [1,1,0,1] = Green static ON
- [0,1,1,0] = Red blink 3Hz
- [1,1,1,0] = Green blink 3Hz
- [0,1,1,1] = Red blink 6Hz
- [1,1,1,1] = Green blink 6Hz
-
-Driver provides the following LEDs for the system "msn2100":
- mlxcpld:fan:green
- mlxcpld:fan:red
- mlxcpld:psu1:green
- mlxcpld:psu1:red
- mlxcpld:psu2:green
- mlxcpld:psu2:red
- mlxcpld:status:green
- mlxcpld:status:red
- mlxcpld:uid:blue
-
- "status"
- CPLD reg offset: 0x20
- Bits [3:0]
-
- "fan"
- CPLD reg offset: 0x21
- Bits [3:0]
-
- "psu1"
- CPLD reg offset: 0x23
- Bits [3:0]
-
- "psu2"
- CPLD reg offset: 0x23
- Bits [7:4]
-
- "uid"
- CPLD reg offset: 0x24
- Bits [3:0]
-
- Color mask for all the above LEDs, excepted uid:
- [bit3,bit2,bit1,bit0] or
- [bit7,bit6,bit5,bit4]:
- [0,0,0,0] = LED OFF
- [0,1,0,1] = Red static ON
- [1,1,0,1] = Green static ON
- [0,1,1,0] = Red blink 3Hz
- [1,1,1,0] = Green blink 3Hz
- [0,1,1,1] = Red blink 6Hz
- [1,1,1,1] = Green blink 6Hz
-
- Color mask for uid LED:
- [bit3,bit2,bit1,bit0]:
- [0,0,0,0] = LED OFF
- [1,1,0,1] = Blue static ON
- [1,1,1,0] = Blue blink 3Hz
- [1,1,1,1] = Blue blink 6Hz
-
-Driver supports HW blinking at 3Hz and 6Hz frequency (50% duty cycle).
-For 3Hz duty cylce is about 167 msec, for 6Hz is about 83 msec.
diff --git a/Documentation/leds/ledtrig-oneshot.txt b/Documentation/leds/ledtrig-oneshot.rst
similarity index 90%
rename from Documentation/leds/ledtrig-oneshot.txt
rename to Documentation/leds/ledtrig-oneshot.rst
index fe57474a12e2..69fa3ea1d554 100644
--- a/Documentation/leds/ledtrig-oneshot.txt
+++ b/Documentation/leds/ledtrig-oneshot.rst
@@ -1,3 +1,4 @@
+====================
One-shot LED Trigger
====================
@@ -17,27 +18,27 @@ additional "invert" property specifies if the LED has to stay off (normal) or
on (inverted) when not rearmed.
The trigger can be activated from user space on led class devices as shown
-below:
+below::
echo oneshot > trigger
This adds sysfs attributes to the LED that are documented in:
Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
-Example use-case: network devices, initialization:
+Example use-case: network devices, initialization::
echo oneshot > trigger # set trigger for this led
echo 33 > delay_on # blink at 1 / (33 + 33) Hz on continuous traffic
echo 33 > delay_off
-interface goes up:
+interface goes up::
echo 1 > invert # set led as normally-on, turn the led on
-packet received/transmitted:
+packet received/transmitted::
echo 1 > shot # led starts blinking, ignored if already blinking
-interface goes down
+interface goes down::
echo 0 > invert # set led as normally-off, turn the led off
diff --git a/Documentation/leds/ledtrig-transient.txt b/Documentation/leds/ledtrig-transient.rst
similarity index 81%
rename from Documentation/leds/ledtrig-transient.txt
rename to Documentation/leds/ledtrig-transient.rst
index 3bd38b487df1..d921dc830cd0 100644
--- a/Documentation/leds/ledtrig-transient.txt
+++ b/Documentation/leds/ledtrig-transient.rst
@@ -1,3 +1,4 @@
+=====================
LED Transient Trigger
=====================
@@ -62,12 +63,13 @@ non-transient state. When driver gets suspended, irrespective of the transient
state, the LED state changes to LED_OFF.
Transient trigger can be enabled and disabled from user space on led class
-devices, that support this trigger as shown below:
+devices, that support this trigger as shown below::
-echo transient > trigger
-echo none > trigger
+ echo transient > trigger
+ echo none > trigger
-NOTE: Add a new property trigger state to control the state.
+NOTE:
+ Add a new property trigger state to control the state.
This trigger exports three properties, activate, state, and duration. When
transient trigger is activated these properties are set to default values.
@@ -79,7 +81,8 @@ transient trigger is activated these properties are set to default values.
- state allows user to specify a transient state to be held for the specified
duration.
- activate - one shot timer activate mechanism.
+ activate
+ - one shot timer activate mechanism.
1 when activated, 0 when deactivated.
default value is zero when transient trigger is enabled,
to allow duration to be set.
@@ -89,12 +92,14 @@ transient trigger is activated these properties are set to default values.
deactivated state indicates that there is no active timer
running.
- duration - one shot timer value. When activate is set, duration value
+ duration
+ - one shot timer value. When activate is set, duration value
is used to start a timer that runs once. This value doesn't
get changed by the trigger unless user does a set via
echo new_value > duration
- state - transient state to be held. It has two values 0 or 1. 0 maps
+ state
+ - transient state to be held. It has two values 0 or 1. 0 maps
to LED_OFF and 1 maps to LED_FULL. The specified state is
held for the duration of the one shot timer and then the
state gets changed to the non-transient state which is the
@@ -114,39 +119,49 @@ When timer expires activate goes back to deactivated state, duration is left
at the set value to be used when activate is set at a future time. This will
allow user app to set the time once and activate it to run it once for the
specified value as needed. When timer expires, state is restored to the
-non-transient state which is the inverse of the transient state.
+non-transient state which is the inverse of the transient state:
- echo 1 > activate - starts timer = duration when duration is not 0.
- echo 0 > activate - cancels currently running timer.
- echo n > duration - stores timer value to be used upon next
- activate. Currently active timer if
- any, continues to run for the specified time.
- echo 0 > duration - stores timer value to be used upon next
- activate. Currently active timer if any,
- continues to run for the specified time.
- echo 1 > state - stores desired transient state LED_FULL to be
+ ================= ===============================================
+ echo 1 > activate starts timer = duration when duration is not 0.
+ echo 0 > activate cancels currently running timer.
+ echo n > duration stores timer value to be used upon next
+ activate. Currently active timer if
+ any, continues to run for the specified time.
+ echo 0 > duration stores timer value to be used upon next
+ activate. Currently active timer if any,
+ continues to run for the specified time.
+ echo 1 > state stores desired transient state LED_FULL to be
held for the specified duration.
- echo 0 > state - stores desired transient state LED_OFF to be
+ echo 0 > state stores desired transient state LED_OFF to be
held for the specified duration.
+ ================= ===============================================
+
+What is not supported
+=====================
-What is not supported:
-======================
- Timer activation is one shot and extending and/or shortening the timer
is not supported.
-Example use-case 1:
+Examples
+========
+
+use-case 1::
+
echo transient > trigger
echo n > duration
echo 1 > state
-repeat the following step as needed:
+
+repeat the following step as needed::
+
echo 1 > activate - start timer = duration to run once
echo 1 > activate - start timer = duration to run once
echo none > trigger
This trigger is intended to be used for for the following example use cases:
+
- Control of vibrate (phones, tablets etc.) hardware by user space app.
- Use of LED by user space app as activity indicator.
- Use of LED by user space app as a kind of watchdog indicator -- as
- long as the app is alive, it can keep the LED illuminated, if it dies
- the LED will be extinguished automatically.
+ long as the app is alive, it can keep the LED illuminated, if it dies
+ the LED will be extinguished automatically.
- Use by any user space app that needs a transient GPIO output.
diff --git a/Documentation/leds/ledtrig-usbport.txt b/Documentation/leds/ledtrig-usbport.rst
similarity index 86%
rename from Documentation/leds/ledtrig-usbport.txt
rename to Documentation/leds/ledtrig-usbport.rst
index 69f54bfb4789..37c2505bfd57 100644
--- a/Documentation/leds/ledtrig-usbport.txt
+++ b/Documentation/leds/ledtrig-usbport.rst
@@ -1,3 +1,4 @@
+====================
USB port LED trigger
====================
@@ -10,14 +11,18 @@ listed as separated entries in a "ports" subdirectory. Selecting is handled by
echoing "1" to a chosen port.
Please note that this trigger allows selecting multiple USB ports for a single
-LED. This can be useful in two cases:
+LED.
+
+This can be useful in two cases:
1) Device with single USB LED and few physical ports
+====================================================
In such a case LED will be turned on as long as there is at least one connected
USB device.
2) Device with a physical port handled by few controllers
+=========================================================
Some devices may have one controller per PHY standard. E.g. USB 3.0 physical
port may be handled by ohci-platform, ehci-platform and xhci-hcd. If there is
@@ -25,14 +30,14 @@ only one LED user will most likely want to assign ports from all 3 hubs.
This trigger can be activated from user space on led class devices as shown
-below:
+below::
echo usbport > trigger
This adds sysfs attributes to the LED that are documented in:
Documentation/ABI/testing/sysfs-class-led-trigger-usbport
-Example use-case:
+Example use-case::
echo usbport > trigger
echo 1 > ports/usb1-port1
diff --git a/Documentation/leds/uleds.txt b/Documentation/leds/uleds.rst
similarity index 95%
rename from Documentation/leds/uleds.txt
rename to Documentation/leds/uleds.rst
index 13e375a580f9..83221098009c 100644
--- a/Documentation/leds/uleds.txt
+++ b/Documentation/leds/uleds.rst
@@ -1,3 +1,4 @@
+==============
Userspace LEDs
==============
@@ -10,12 +11,12 @@ Usage
When the driver is loaded, a character device is created at /dev/uleds. To
create a new LED class device, open /dev/uleds and write a uleds_user_dev
-structure to it (found in kernel public header file linux/uleds.h).
+structure to it (found in kernel public header file linux/uleds.h)::
#define LED_MAX_NAME_SIZE 64
struct uleds_user_dev {
- char name[LED_MAX_NAME_SIZE];
+ char name[LED_MAX_NAME_SIZE];
};
A new LED class device will be created with the name given. The name can be
diff --git a/MAINTAINERS b/MAINTAINERS
index f8f2394f9e84..73000e7d7f19 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10172,7 +10172,7 @@ L: linux-leds@vger.kernel.org
S: Supported
F: drivers/leds/leds-mlxcpld.c
F: drivers/leds/leds-mlxreg.c
-F: Documentation/leds/leds-mlxcpld.txt
+F: Documentation/leds/leds-mlxcpld.rst
MELLANOX PLATFORM DRIVER
M: Vadim Pasternak <vadimp@mellanox.com>
diff --git a/drivers/leds/trigger/Kconfig b/drivers/leds/trigger/Kconfig
index 7fa9d174a40c..ce9429ca6dde 100644
--- a/drivers/leds/trigger/Kconfig
+++ b/drivers/leds/trigger/Kconfig
@@ -15,7 +15,7 @@ config LEDS_TRIGGER_TIMER
This allows LEDs to be controlled by a programmable timer
via sysfs. Some LED hardware can be programmed to start
blinking the LED without any further software interaction.
- For more details read Documentation/leds/leds-class.txt.
+ For more details read Documentation/leds/leds-class.rst.
If unsure, say Y.
diff --git a/drivers/leds/trigger/ledtrig-transient.c b/drivers/leds/trigger/ledtrig-transient.c
index a80bb82aacc2..80635183fac8 100644
--- a/drivers/leds/trigger/ledtrig-transient.c
+++ b/drivers/leds/trigger/ledtrig-transient.c
@@ -3,7 +3,7 @@
// LED Kernel Transient Trigger
//
// Transient trigger allows one shot timer activation. Please refer to
-// Documentation/leds/ledtrig-transient.txt for details
+// Documentation/leds/ledtrig-transient.rst for details
// Copyright (C) 2012 Shuah Khan <shuahkhan@gmail.com>
//
// Based on Richard Purdie's ledtrig-timer.c and Atsushi Nemoto's
diff --git a/net/netfilter/Kconfig b/net/netfilter/Kconfig
index dd2af7be3eea..1837734ce85b 100644
--- a/net/netfilter/Kconfig
+++ b/net/netfilter/Kconfig
@@ -906,7 +906,7 @@ config NETFILTER_XT_TARGET_LED
echo netfilter-ssh > /sys/class/leds/<ledname>/trigger
For more information on the LEDs available on your system, see
- Documentation/leds/leds-class.txt
+ Documentation/leds/leds-class.rst
config NETFILTER_XT_TARGET_LOG
tristate "LOG target support"
--
2.21.0
^ permalink raw reply related
* [PATCH v1 21/31] docs: ia64: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Pat Gefre, Ard Biesheuvel, Tony Luck, Fenghua Yu,
linux-ia64, linux-efi
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the ia64 documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
There are two upper case file names. Rename them to
lower case, as we're working to avoid upper case file
names at Documentation.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../ia64/{aliasing.txt => aliasing.rst} | 73 ++--
Documentation/ia64/{efirtc.txt => efirtc.rst} | 118 +++---
.../ia64/{err_inject.txt => err_inject.rst} | 349 +++++++++---------
Documentation/ia64/{fsys.txt => fsys.rst} | 127 ++++---
Documentation/ia64/{README => ia64.rst} | 26 +-
Documentation/ia64/index.rst | 18 +
.../ia64/{IRQ-redir.txt => irq-redir.rst} | 31 +-
Documentation/ia64/{mca.txt => mca.rst} | 10 +-
Documentation/ia64/{serial.txt => serial.rst} | 36 +-
Documentation/ia64/xen.rst | 206 +++++++++++
Documentation/ia64/xen.txt | 183 ---------
MAINTAINERS | 2 +-
arch/ia64/kernel/efi.c | 2 +-
arch/ia64/kernel/fsys.S | 2 +-
arch/ia64/mm/ioremap.c | 2 +-
arch/ia64/pci/pci.c | 2 +-
16 files changed, 660 insertions(+), 527 deletions(-)
rename Documentation/ia64/{aliasing.txt => aliasing.rst} (83%)
rename Documentation/ia64/{efirtc.txt => efirtc.rst} (70%)
rename Documentation/ia64/{err_inject.txt => err_inject.rst} (82%)
rename Documentation/ia64/{fsys.txt => fsys.rst} (76%)
rename Documentation/ia64/{README => ia64.rst} (61%)
create mode 100644 Documentation/ia64/index.rst
rename Documentation/ia64/{IRQ-redir.txt => irq-redir.rst} (86%)
rename Documentation/ia64/{mca.txt => mca.rst} (96%)
rename Documentation/ia64/{serial.txt => serial.rst} (87%)
create mode 100644 Documentation/ia64/xen.rst
delete mode 100644 Documentation/ia64/xen.txt
diff --git a/Documentation/ia64/aliasing.txt b/Documentation/ia64/aliasing.rst
similarity index 83%
rename from Documentation/ia64/aliasing.txt
rename to Documentation/ia64/aliasing.rst
index 5a4dea6abebd..a08b36aba015 100644
--- a/Documentation/ia64/aliasing.txt
+++ b/Documentation/ia64/aliasing.rst
@@ -1,20 +1,25 @@
- MEMORY ATTRIBUTE ALIASING ON IA-64
+==================================
+Memory Attribute Aliasing on IA-64
+==================================
- Bjorn Helgaas
- <bjorn.helgaas@hp.com>
- May 4, 2006
+Bjorn Helgaas <bjorn.helgaas@hp.com>
+May 4, 2006
-MEMORY ATTRIBUTES
+
+Memory Attributes
+=================
Itanium supports several attributes for virtual memory references.
The attribute is part of the virtual translation, i.e., it is
contained in the TLB entry. The ones of most interest to the Linux
kernel are:
- WB Write-back (cacheable)
+ == ======================
+ WB Write-back (cacheable)
UC Uncacheable
WC Write-coalescing
+ == ======================
System memory typically uses the WB attribute. The UC attribute is
used for memory-mapped I/O devices. The WC attribute is uncacheable
@@ -29,7 +34,8 @@ MEMORY ATTRIBUTES
support either WB or UC access to main memory, while others support
only WB access.
-MEMORY MAP
+Memory Map
+==========
Platform firmware describes the physical memory map and the
supported attributes for each region. At boot-time, the kernel uses
@@ -55,7 +61,8 @@ MEMORY MAP
The efi_memmap table is preserved unmodified because the original
boot-time information is required for kexec.
-KERNEL IDENTITY MAPPINGS
+Kernel Identify Mappings
+========================
Linux/ia64 identity mappings are done with large pages, currently
either 16MB or 64MB, referred to as "granules." Cacheable mappings
@@ -74,17 +81,20 @@ KERNEL IDENTITY MAPPINGS
are only partially populated, or populated with a combination of UC
and WB regions.
-USER MAPPINGS
+User Mappings
+=============
User mappings are typically done with 16K or 64K pages. The smaller
page size allows more flexibility because only 16K or 64K has to be
homogeneous with respect to memory attributes.
-POTENTIAL ATTRIBUTE ALIASING CASES
+Potential Attribute Aliasing Cases
+==================================
There are several ways the kernel creates new mappings:
- mmap of /dev/mem
+mmap of /dev/mem
+----------------
This uses remap_pfn_range(), which creates user mappings. These
mappings may be either WB or UC. If the region being mapped
@@ -98,7 +108,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
Since the EFI memory map does not describe MMIO on some
machines, this should use an uncacheable mapping as a fallback.
- mmap of /sys/class/pci_bus/.../legacy_mem
+mmap of /sys/class/pci_bus/.../legacy_mem
+-----------------------------------------
This is very similar to mmap of /dev/mem, except that legacy_mem
only allows mmap of the one megabyte "legacy MMIO" area for a
@@ -112,9 +123,10 @@ POTENTIAL ATTRIBUTE ALIASING CASES
The /dev/mem mmap constraints apply.
- mmap of /proc/bus/pci/.../??.?
+mmap of /proc/bus/pci/.../??.?
+------------------------------
- This is an MMIO mmap of PCI functions, which additionally may or
+ This is an MMIO mmap of PCI functions, which additionally may or
may not be requested as using the WC attribute.
If WC is requested, and the region in kern_memmap is either WC
@@ -124,7 +136,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
Otherwise, the user mapping must use the same attribute as the
kernel mapping.
- read/write of /dev/mem
+read/write of /dev/mem
+----------------------
This uses copy_from_user(), which implicitly uses a kernel
identity mapping. This is obviously safe for things in
@@ -138,7 +151,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
eight-byte accesses, and the copy_from_user() path doesn't allow
any control over the access size, so this would be dangerous.
- ioremap()
+ioremap()
+---------
This returns a mapping for use inside the kernel.
@@ -155,9 +169,11 @@ POTENTIAL ATTRIBUTE ALIASING CASES
Failing all of the above, we have to fall back to a UC mapping.
-PAST PROBLEM CASES
+Past Problem Cases
+==================
- mmap of various MMIO regions from /dev/mem by "X" on Intel platforms
+mmap of various MMIO regions from /dev/mem by "X" on Intel platforms
+--------------------------------------------------------------------
The EFI memory map may not report these MMIO regions.
@@ -166,12 +182,16 @@ PAST PROBLEM CASES
succeed. It may create either WB or UC user mappings, depending
on whether the region is in kern_memmap or the EFI memory map.
- mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled
+mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled
+----------------------------------------------------------------------
The EFI memory map reports the following attributes:
+
+ =============== ======= ==================
0x00000-0x9FFFF WB only
0xA0000-0xBFFFF UC only (VGA frame buffer)
0xC0000-0xFFFFF WB only
+ =============== ======= ==================
This mmap is done with user pages, not kernel identity mappings,
so it is safe to use WB mappings.
@@ -182,7 +202,8 @@ PAST PROBLEM CASES
never generate an uncacheable reference to the WB-only areas unless
the driver explicitly touches them.
- mmap of 0x0-0xFFFFF legacy_mem by "X"
+mmap of 0x0-0xFFFFF legacy_mem by "X"
+-------------------------------------
If the EFI memory map reports that the entire range supports the
same attributes, we can allow the mmap (and we will prefer WB if
@@ -197,15 +218,18 @@ PAST PROBLEM CASES
that doesn't report the VGA frame buffer at all), we should fail the
mmap and force the user to map just the specific region of interest.
- mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled
+mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled
+------------------------------------------------------------------------
+
+ The EFI memory map reports the following attributes::
- The EFI memory map reports the following attributes:
0x00000-0xFFFFF WB only (no VGA MMIO hole)
This is a special case of the previous case, and the mmap should
fail for the same reason as above.
- read of /sys/devices/.../rom
+read of /sys/devices/.../rom
+----------------------------
For VGA devices, this may cause an ioremap() of 0xC0000. This
used to be done with a UC mapping, because the VGA frame buffer
@@ -215,7 +239,8 @@ PAST PROBLEM CASES
We should use WB page table mappings to avoid covering the VGA
frame buffer.
-NOTES
+Notes
+=====
[1] SDM rev 2.2, vol 2, sec 4.4.1.
[2] SDM rev 2.2, vol 2, sec 4.4.6.
diff --git a/Documentation/ia64/efirtc.txt b/Documentation/ia64/efirtc.rst
similarity index 70%
rename from Documentation/ia64/efirtc.txt
rename to Documentation/ia64/efirtc.rst
index 057e6bebda8f..2f7ff5026308 100644
--- a/Documentation/ia64/efirtc.txt
+++ b/Documentation/ia64/efirtc.rst
@@ -1,12 +1,16 @@
+==========================
EFI Real Time Clock driver
--------------------------------
+==========================
+
S. Eranian <eranian@hpl.hp.com>
+
March 2000
-I/ Introduction
+1. Introduction
+===============
This document describes the efirtc.c driver has provided for
-the IA-64 platform.
+the IA-64 platform.
The purpose of this driver is to supply an API for kernel and user applications
to get access to the Time Service offered by EFI version 0.92.
@@ -16,112 +20,124 @@ SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this
driver. We describe those calls as well the design of the driver in the
following sections.
-II/ Design Decisions
+2. Design Decisions
+===================
-The original ideas was to provide a very simple driver to get access to,
-at first, the time of day service. This is required in order to access, in a
-portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock
+The original ideas was to provide a very simple driver to get access to,
+at first, the time of day service. This is required in order to access, in a
+portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock
to initialize the system view of the time during boot.
Because we wanted to minimize the impact on existing user-level apps using
the CMOS clock, we decided to expose an API that was very similar to the one
-used today with the legacy RTC driver (driver/char/rtc.c). However, because
+used today with the legacy RTC driver (driver/char/rtc.c). However, because
EFI provides a simpler services, not all ioctl() are available. Also
-new ioctl()s have been introduced for things that EFI provides but not the
+new ioctl()s have been introduced for things that EFI provides but not the
legacy.
EFI uses a slightly different way of representing the time, noticeably
the reference date is different. Year is the using the full 4-digit format.
The Epoch is January 1st 1998. For backward compatibility reasons we don't
-expose this new way of representing time. Instead we use something very
+expose this new way of representing time. Instead we use something very
similar to the struct tm, i.e. struct rtc_time, as used by hwclock.
One of the reasons for doing it this way is to allow for EFI to still evolve
without necessarily impacting any of the user applications. The decoupling
enables flexibility and permits writing wrapper code is ncase things change.
The driver exposes two interfaces, one via the device file and a set of
-ioctl()s. The other is read-only via the /proc filesystem.
+ioctl()s. The other is read-only via the /proc filesystem.
As of today we don't offer a /proc/sys interface.
To allow for a uniform interface between the legacy RTC and EFI time service,
-we have created the include/linux/rtc.h header file to contain only the
-"public" API of the two drivers. The specifics of the legacy RTC are still
+we have created the include/linux/rtc.h header file to contain only the
+"public" API of the two drivers. The specifics of the legacy RTC are still
in include/linux/mc146818rtc.h.
-
-III/ Time of day service
+
+3. Time of day service
+======================
The part of the driver gives access to the time of day service of EFI.
Two ioctl()s, compatible with the legacy RTC calls:
- Read the CMOS clock: ioctl(d, RTC_RD_TIME, &rtc);
+ Read the CMOS clock::
- Write the CMOS clock: ioctl(d, RTC_SET_TIME, &rtc);
+ ioctl(d, RTC_RD_TIME, &rtc);
+
+ Write the CMOS clock::
+
+ ioctl(d, RTC_SET_TIME, &rtc);
The rtc is a pointer to a data structure defined in rtc.h which is close
-to a struct tm:
+to a struct tm::
-struct rtc_time {
- int tm_sec;
- int tm_min;
- int tm_hour;
- int tm_mday;
- int tm_mon;
- int tm_year;
- int tm_wday;
- int tm_yday;
- int tm_isdst;
-};
+ struct rtc_time {
+ int tm_sec;
+ int tm_min;
+ int tm_hour;
+ int tm_mday;
+ int tm_mon;
+ int tm_year;
+ int tm_wday;
+ int tm_yday;
+ int tm_isdst;
+ };
The driver takes care of converting back an forth between the EFI time and
this format.
Those two ioctl()s can be exercised with the hwclock command:
-For reading:
-# /sbin/hwclock --show
-Mon Mar 6 15:32:32 2000 -0.910248 seconds
+For reading::
-For setting:
-# /sbin/hwclock --systohc
+ # /sbin/hwclock --show
+ Mon Mar 6 15:32:32 2000 -0.910248 seconds
+
+For setting::
+
+ # /sbin/hwclock --systohc
Root privileges are required to be able to set the time of day.
-IV/ Wakeup Alarm service
+4. Wakeup Alarm service
+=======================
EFI provides an API by which one can program when a machine should wakeup,
i.e. reboot. This is very different from the alarm provided by the legacy
RTC which is some kind of interval timer alarm. For this reason we don't use
the same ioctl()s to get access to the service. Instead we have
-introduced 2 news ioctl()s to the interface of an RTC.
+introduced 2 news ioctl()s to the interface of an RTC.
We have added 2 new ioctl()s that are specific to the EFI driver:
- Read the current state of the alarm
- ioctl(d, RTC_WKLAM_RD, &wkt)
+ Read the current state of the alarm::
- Set the alarm or change its status
- ioctl(d, RTC_WKALM_SET, &wkt)
+ ioctl(d, RTC_WKLAM_RD, &wkt)
-The wkt structure encapsulates a struct rtc_time + 2 extra fields to get
-status information:
-
-struct rtc_wkalrm {
+ Set the alarm or change its status::
- unsigned char enabled; /* =1 if alarm is enabled */
- unsigned char pending; /* =1 if alarm is pending */
+ ioctl(d, RTC_WKALM_SET, &wkt)
- struct rtc_time time;
-}
+The wkt structure encapsulates a struct rtc_time + 2 extra fields to get
+status information::
+
+ struct rtc_wkalrm {
+
+ unsigned char enabled; /* =1 if alarm is enabled */
+ unsigned char pending; /* =1 if alarm is pending */
+
+ struct rtc_time time;
+ }
As of today, none of the existing user-level apps supports this feature.
-However writing such a program should be hard by simply using those two
-ioctl().
+However writing such a program should be hard by simply using those two
+ioctl().
Root privileges are required to be able to set the alarm.
-V/ References.
+5. References
+=============
Checkout the following Web site for more information on EFI:
diff --git a/Documentation/ia64/err_inject.txt b/Documentation/ia64/err_inject.rst
similarity index 82%
rename from Documentation/ia64/err_inject.txt
rename to Documentation/ia64/err_inject.rst
index 9f651c181429..900f71e93a29 100644
--- a/Documentation/ia64/err_inject.txt
+++ b/Documentation/ia64/err_inject.rst
@@ -1,4 +1,4 @@
-
+========================================
IPF Machine Check (MC) error inject tool
========================================
@@ -32,94 +32,94 @@ Errata: Itanium 2 Processors Specification Update lists some errata against
the pal_mc_error_inject PAL procedure. The following err.conf has been tested
on latest Montecito PAL.
-err.conf:
+err.conf::
-#This is configuration file for err_inject_tool.
-#The format of the each line is:
-#cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer
-#where
-# cpu: logical cpu number the error will be inject in.
-# loop: times the error will be injected.
-# interval: In second. every so often one error is injected.
-# err_type_info, err_struct_info: PAL parameters.
-#
-#Note: All values are hex w/o or w/ 0x prefix.
+ #This is configuration file for err_inject_tool.
+ #The format of the each line is:
+ #cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer
+ #where
+ # cpu: logical cpu number the error will be inject in.
+ # loop: times the error will be injected.
+ # interval: In second. every so often one error is injected.
+ # err_type_info, err_struct_info: PAL parameters.
+ #
+ #Note: All values are hex w/o or w/ 0x prefix.
-#On cpu2, inject only total 0x10 errors, interval 5 seconds
-#corrected, data cache, hier-2, physical addr(assigned by tool code).
-#working on Montecito latest PAL.
-2, 10, 5, 4101, 95
+ #On cpu2, inject only total 0x10 errors, interval 5 seconds
+ #corrected, data cache, hier-2, physical addr(assigned by tool code).
+ #working on Montecito latest PAL.
+ 2, 10, 5, 4101, 95
-#On cpu4, inject and consume total 0x10 errors, interval 5 seconds
-#corrected, data cache, hier-2, physical addr(assigned by tool code).
-#working on Montecito latest PAL.
-4, 10, 5, 4109, 95
+ #On cpu4, inject and consume total 0x10 errors, interval 5 seconds
+ #corrected, data cache, hier-2, physical addr(assigned by tool code).
+ #working on Montecito latest PAL.
+ 4, 10, 5, 4109, 95
-#On cpu15, inject and consume total 0x10 errors, interval 5 seconds
-#recoverable, DTR0, hier-2.
-#working on Montecito latest PAL.
-0xf, 0x10, 5, 4249, 15
+ #On cpu15, inject and consume total 0x10 errors, interval 5 seconds
+ #recoverable, DTR0, hier-2.
+ #working on Montecito latest PAL.
+ 0xf, 0x10, 5, 4249, 15
The sample application source code:
-err_injection_tool.c:
+err_injection_tool.c::
-/*
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
- * NON INFRINGEMENT. See the GNU General Public License for more
- * details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * Copyright (C) 2006 Intel Co
- * Fenghua Yu <fenghua.yu@intel.com>
- *
- */
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#include <stdio.h>
-#include <sched.h>
-#include <unistd.h>
-#include <stdlib.h>
-#include <stdarg.h>
-#include <string.h>
-#include <errno.h>
-#include <time.h>
-#include <sys/ipc.h>
-#include <sys/sem.h>
-#include <sys/wait.h>
-#include <sys/mman.h>
-#include <sys/shm.h>
+ /*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
+ * NON INFRINGEMENT. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ *
+ * Copyright (C) 2006 Intel Co
+ * Fenghua Yu <fenghua.yu@intel.com>
+ *
+ */
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <fcntl.h>
+ #include <stdio.h>
+ #include <sched.h>
+ #include <unistd.h>
+ #include <stdlib.h>
+ #include <stdarg.h>
+ #include <string.h>
+ #include <errno.h>
+ #include <time.h>
+ #include <sys/ipc.h>
+ #include <sys/sem.h>
+ #include <sys/wait.h>
+ #include <sys/mman.h>
+ #include <sys/shm.h>
-#define MAX_FN_SIZE 256
-#define MAX_BUF_SIZE 256
-#define DATA_BUF_SIZE 256
-#define NR_CPUS 512
-#define MAX_TASK_NUM 2048
-#define MIN_INTERVAL 5 // seconds
-#define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte.
-#define PARA_FIELD_NUM 5
-#define MASK_SIZE (NR_CPUS/64)
-#define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/"
+ #define MAX_FN_SIZE 256
+ #define MAX_BUF_SIZE 256
+ #define DATA_BUF_SIZE 256
+ #define NR_CPUS 512
+ #define MAX_TASK_NUM 2048
+ #define MIN_INTERVAL 5 // seconds
+ #define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte.
+ #define PARA_FIELD_NUM 5
+ #define MASK_SIZE (NR_CPUS/64)
+ #define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/"
-int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask);
+ int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask);
-int verbose;
-#define vbprintf if (verbose) printf
+ int verbose;
+ #define vbprintf if (verbose) printf
-int log_info(int cpu, const char *fmt, ...)
-{
+ int log_info(int cpu, const char *fmt, ...)
+ {
FILE *log;
char fn[MAX_FN_SIZE];
char buf[MAX_BUF_SIZE];
@@ -142,12 +142,12 @@ int log_info(int cpu, const char *fmt, ...)
fclose(log);
return 0;
-}
+ }
-typedef unsigned long u64;
-typedef unsigned int u32;
+ typedef unsigned long u64;
+ typedef unsigned int u32;
-typedef union err_type_info_u {
+ typedef union err_type_info_u {
struct {
u64 mode : 3, /* 0-2 */
err_inj : 3, /* 3-5 */
@@ -157,9 +157,9 @@ typedef union err_type_info_u {
reserved : 48; /* 16-63 */
} err_type_info_u;
u64 err_type_info;
-} err_type_info_t;
+ } err_type_info_t;
-typedef union err_struct_info_u {
+ typedef union err_struct_info_u {
struct {
u64 siv : 1, /* 0 */
c_t : 2, /* 1-2 */
@@ -197,9 +197,9 @@ typedef union err_struct_info_u {
u64 reserved;
} err_struct_info_bus_processor_interconnect;
u64 err_struct_info;
-} err_struct_info_t;
+ } err_struct_info_t;
-typedef union err_data_buffer_u {
+ typedef union err_data_buffer_u {
struct {
u64 trigger_addr; /* 0-63 */
u64 inj_addr; /* 64-127 */
@@ -221,9 +221,9 @@ typedef union err_data_buffer_u {
u64 reserved; /* 0-63 */
} err_data_buffer_bus_processor_interconnect;
u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
-} err_data_buffer_t;
+ } err_data_buffer_t;
-typedef union capabilities_u {
+ typedef union capabilities_u {
struct {
u64 i : 1,
d : 1,
@@ -276,9 +276,9 @@ typedef union capabilities_u {
struct {
u64 reserved;
} capabilities_bus_processor_interconnect;
-} capabilities_t;
+ } capabilities_t;
-typedef struct resources_s {
+ typedef struct resources_s {
u64 ibr0 : 1,
ibr2 : 1,
ibr4 : 1,
@@ -288,24 +288,24 @@ typedef struct resources_s {
dbr4 : 1,
dbr6 : 1,
reserved : 48;
-} resources_t;
+ } resources_t;
-long get_page_size(void)
-{
+ long get_page_size(void)
+ {
long page_size=sysconf(_SC_PAGESIZE);
return page_size;
-}
+ }
-#define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size())
-#define SHM_SIZE (2*PAGE_SIZE*NR_CPUS)
-#define SHM_VA 0x2000000100000000
+ #define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size())
+ #define SHM_SIZE (2*PAGE_SIZE*NR_CPUS)
+ #define SHM_VA 0x2000000100000000
-int shmid;
-void *shmaddr;
+ int shmid;
+ void *shmaddr;
-int create_shm(void)
-{
+ int create_shm(void)
+ {
key_t key;
char fn[MAX_FN_SIZE];
@@ -343,34 +343,34 @@ int create_shm(void)
mlock(shmaddr, SHM_SIZE);
return 0;
-}
+ }
-int free_shm()
-{
+ int free_shm()
+ {
munlock(shmaddr, SHM_SIZE);
- shmdt(shmaddr);
+ shmdt(shmaddr);
semctl(shmid, 0, IPC_RMID);
return 0;
-}
+ }
-#ifdef _SEM_SEMUN_UNDEFINED
-union semun
-{
+ #ifdef _SEM_SEMUN_UNDEFINED
+ union semun
+ {
int val;
struct semid_ds *buf;
unsigned short int *array;
struct seminfo *__buf;
-};
-#endif
+ };
+ #endif
-u32 mode=1; /* 1: physical mode; 2: virtual mode. */
-int one_lock=1;
-key_t key[NR_CPUS];
-int semid[NR_CPUS];
+ u32 mode=1; /* 1: physical mode; 2: virtual mode. */
+ int one_lock=1;
+ key_t key[NR_CPUS];
+ int semid[NR_CPUS];
-int create_sem(int cpu)
-{
+ int create_sem(int cpu)
+ {
union semun arg;
char fn[MAX_FN_SIZE];
int sid;
@@ -407,37 +407,37 @@ int create_sem(int cpu)
}
return 0;
-}
+ }
-static int lock(int cpu)
-{
+ static int lock(int cpu)
+ {
struct sembuf lock;
lock.sem_num = cpu;
lock.sem_op = 1;
semop(semid[cpu], &lock, 1);
- return 0;
-}
+ return 0;
+ }
-static int unlock(int cpu)
-{
+ static int unlock(int cpu)
+ {
struct sembuf unlock;
unlock.sem_num = cpu;
unlock.sem_op = -1;
semop(semid[cpu], &unlock, 1);
- return 0;
-}
+ return 0;
+ }
-void free_sem(int cpu)
-{
+ void free_sem(int cpu)
+ {
semctl(semid[cpu], 0, IPC_RMID);
-}
+ }
-int wr_multi(char *fn, unsigned long *data, int size)
-{
+ int wr_multi(char *fn, unsigned long *data, int size)
+ {
int fd;
char buf[MAX_BUF_SIZE];
int ret;
@@ -459,15 +459,15 @@ int wr_multi(char *fn, unsigned long *data, int size)
ret=write(fd, buf, sizeof(buf));
close(fd);
return ret;
-}
+ }
-int wr(char *fn, unsigned long data)
-{
+ int wr(char *fn, unsigned long data)
+ {
return wr_multi(fn, &data, 1);
-}
+ }
-int rd(char *fn, unsigned long *data)
-{
+ int rd(char *fn, unsigned long *data)
+ {
int fd;
char buf[MAX_BUF_SIZE];
@@ -480,10 +480,10 @@ int rd(char *fn, unsigned long *data)
*data=strtoul(buf, NULL, 16);
close(fd);
return 0;
-}
+ }
-int rd_status(char *path, int *status)
-{
+ int rd_status(char *path, int *status)
+ {
char fn[MAX_FN_SIZE];
sprintf(fn, "%s/status", path);
if (rd(fn, (u64*)status)<0) {
@@ -492,10 +492,10 @@ int rd_status(char *path, int *status)
}
return 0;
-}
+ }
-int rd_capabilities(char *path, u64 *capabilities)
-{
+ int rd_capabilities(char *path, u64 *capabilities)
+ {
char fn[MAX_FN_SIZE];
sprintf(fn, "%s/capabilities", path);
if (rd(fn, capabilities)<0) {
@@ -504,10 +504,10 @@ int rd_capabilities(char *path, u64 *capabilities)
}
return 0;
-}
+ }
-int rd_all(char *path)
-{
+ int rd_all(char *path)
+ {
unsigned long err_type_info, err_struct_info, err_data_buffer;
int status;
unsigned long capabilities, resources;
@@ -556,11 +556,11 @@ int rd_all(char *path)
printf("resources=%lx\n", resources);
return 0;
-}
+ }
-int query_capabilities(char *path, err_type_info_t err_type_info,
+ int query_capabilities(char *path, err_type_info_t err_type_info,
u64 *capabilities)
-{
+ {
char fn[MAX_FN_SIZE];
err_struct_info_t err_struct_info;
err_data_buffer_t err_data_buffer;
@@ -583,10 +583,10 @@ int query_capabilities(char *path, err_type_info_t err_type_info,
return -1;
return 0;
-}
+ }
-int query_all_capabilities()
-{
+ int query_all_capabilities()
+ {
int status;
err_type_info_t err_type_info;
int err_sev, err_struct, struct_hier;
@@ -629,12 +629,12 @@ int query_all_capabilities()
}
return 0;
-}
+ }
-int err_inject(int cpu, char *path, err_type_info_t err_type_info,
+ int err_inject(int cpu, char *path, err_type_info_t err_type_info,
err_struct_info_t err_struct_info,
err_data_buffer_t err_data_buffer)
-{
+ {
int status;
char fn[MAX_FN_SIZE];
@@ -667,13 +667,13 @@ int err_inject(int cpu, char *path, err_type_info_t err_type_info,
}
return status;
-}
+ }
-static int construct_data_buf(char *path, err_type_info_t err_type_info,
+ static int construct_data_buf(char *path, err_type_info_t err_type_info,
err_struct_info_t err_struct_info,
err_data_buffer_t *err_data_buffer,
void *va1)
-{
+ {
char fn[MAX_FN_SIZE];
u64 virt_addr=0, phys_addr=0;
@@ -710,22 +710,22 @@ static int construct_data_buf(char *path, err_type_info_t err_type_info,
}
return 0;
-}
+ }
-typedef struct {
+ typedef struct {
u64 cpu;
u64 loop;
u64 interval;
u64 err_type_info;
u64 err_struct_info;
u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
-} parameters_t;
+ } parameters_t;
-parameters_t line_para;
-int para;
+ parameters_t line_para;
+ int para;
-static int empty_data_buffer(u64 *err_data_buffer)
-{
+ static int empty_data_buffer(u64 *err_data_buffer)
+ {
int empty=1;
int i;
@@ -734,10 +734,10 @@ static int empty_data_buffer(u64 *err_data_buffer)
empty=0;
return empty;
-}
+ }
-int err_inj()
-{
+ int err_inj()
+ {
err_type_info_t err_type_info;
err_struct_info_t err_struct_info;
err_data_buffer_t err_data_buffer;
@@ -951,10 +951,10 @@ int err_inj()
printf("All done.\n");
return 0;
-}
+ }
-void help()
-{
+ void help()
+ {
printf("err_inject_tool:\n");
printf("\t-q: query all capabilities. default: off\n");
printf("\t-m: procedure mode. 1: physical 2: virtual. default: 1\n");
@@ -977,10 +977,10 @@ void help()
printf("The tool will take err.conf file as ");
printf("input to inject single or multiple errors ");
printf("on one or multiple cpus in parallel.\n");
-}
+ }
-int main(int argc, char **argv)
-{
+ int main(int argc, char **argv)
+ {
char c;
int do_err_inj=0;
int do_query_all=0;
@@ -1031,7 +1031,7 @@ int main(int argc, char **argv)
if (count!=PARA_FIELD_NUM+3) {
line_para.err_data_buffer[0]=-1,
line_para.err_data_buffer[1]=-1,
- line_para.err_data_buffer[2]=-1;
+ line_para.err_data_buffer[2]=-1;
count=sscanf(optarg, "%lx, %lx, %lx, %lx, %lx\n",
&line_para.cpu,
&line_para.loop,
@@ -1064,5 +1064,4 @@ int main(int argc, char **argv)
help();
return 0;
-}
-
+ }
diff --git a/Documentation/ia64/fsys.txt b/Documentation/ia64/fsys.rst
similarity index 76%
rename from Documentation/ia64/fsys.txt
rename to Documentation/ia64/fsys.rst
index 59dd689d9b86..a702d2cc94b6 100644
--- a/Documentation/ia64/fsys.txt
+++ b/Documentation/ia64/fsys.rst
@@ -1,9 +1,9 @@
--*-Mode: outline-*-
-
- Light-weight System Calls for IA-64
- -----------------------------------
+===================================
+Light-weight System Calls for IA-64
+===================================
Started: 13-Jan-2003
+
Last update: 27-Sep-2003
David Mosberger-Tang
@@ -52,12 +52,13 @@ privilege level is at level 0, this means that fsys-mode requires some
care (see below).
-* How to tell fsys-mode
+How to tell fsys-mode
+=====================
Linux operates in fsys-mode when (a) the privilege level is 0 (most
privileged) and (b) the stacks have NOT been switched to kernel memory
yet. For convenience, the header file <asm-ia64/ptrace.h> provides
-three macros:
+three macros::
user_mode(regs)
user_stack(task,regs)
@@ -70,11 +71,12 @@ to by "regs" was executing in user mode (privilege level 3).
user_stack() returns TRUE if the state pointed to by "regs" was
executing on the user-level stack(s). Finally, fsys_mode() returns
TRUE if the CPU state pointed to by "regs" was executing in fsys-mode.
-The fsys_mode() macro is equivalent to the expression:
+The fsys_mode() macro is equivalent to the expression::
!user_mode(regs) && user_stack(task,regs)
-* How to write an fsyscall handler
+How to write an fsyscall handler
+================================
The file arch/ia64/kernel/fsys.S contains a table of fsyscall-handlers
(fsyscall_table). This table contains one entry for each system call.
@@ -87,66 +89,72 @@ of the getpid() system call.
The entry and exit-state of an fsyscall handler is as follows:
-** Machine state on entry to fsyscall handler:
+Machine state on entry to fsyscall handler
+------------------------------------------
- - r10 = 0
- - r11 = saved ar.pfs (a user-level value)
- - r15 = system call number
- - r16 = "current" task pointer (in normal kernel-mode, this is in r13)
- - r32-r39 = system call arguments
- - b6 = return address (a user-level value)
- - ar.pfs = previous frame-state (a user-level value)
- - PSR.be = cleared to zero (i.e., little-endian byte order is in effect)
- - all other registers may contain values passed in from user-mode
+ ========= ===============================================================
+ r10 0
+ r11 saved ar.pfs (a user-level value)
+ r15 system call number
+ r16 "current" task pointer (in normal kernel-mode, this is in r13)
+ r32-r39 system call arguments
+ b6 return address (a user-level value)
+ ar.pfs previous frame-state (a user-level value)
+ PSR.be cleared to zero (i.e., little-endian byte order is in effect)
+ - all other registers may contain values passed in from user-mode
+ ========= ===============================================================
-** Required machine state on exit to fsyscall handler:
+Required machine state on exit to fsyscall handler
+--------------------------------------------------
- - r11 = saved ar.pfs (as passed into the fsyscall handler)
- - r15 = system call number (as passed into the fsyscall handler)
- - r32-r39 = system call arguments (as passed into the fsyscall handler)
- - b6 = return address (as passed into the fsyscall handler)
- - ar.pfs = previous frame-state (as passed into the fsyscall handler)
+ ========= ===========================================================
+ r11 saved ar.pfs (as passed into the fsyscall handler)
+ r15 system call number (as passed into the fsyscall handler)
+ r32-r39 system call arguments (as passed into the fsyscall handler)
+ b6 return address (as passed into the fsyscall handler)
+ ar.pfs previous frame-state (as passed into the fsyscall handler)
+ ========= ===========================================================
Fsyscall handlers can execute with very little overhead, but with that
speed comes a set of restrictions:
- o Fsyscall-handlers MUST check for any pending work in the flags
+ * Fsyscall-handlers MUST check for any pending work in the flags
member of the thread-info structure and if any of the
TIF_ALLWORK_MASK flags are set, the handler needs to fall back on
doing a full system call (by calling fsys_fallback_syscall).
- o Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,
+ * Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,
r15, b6, and ar.pfs) because they will be needed in case of a
system call restart. Of course, all "preserved" registers also
must be preserved, in accordance to the normal calling conventions.
- o Fsyscall-handlers MUST check argument registers for containing a
+ * Fsyscall-handlers MUST check argument registers for containing a
NaT value before using them in any way that could trigger a
NaT-consumption fault. If a system call argument is found to
contain a NaT value, an fsyscall-handler may return immediately
with r8=EINVAL, r10=-1.
- o Fsyscall-handlers MUST NOT use the "alloc" instruction or perform
+ * Fsyscall-handlers MUST NOT use the "alloc" instruction or perform
any other operation that would trigger mandatory RSE
(register-stack engine) traffic.
- o Fsyscall-handlers MUST NOT write to any stacked registers because
+ * Fsyscall-handlers MUST NOT write to any stacked registers because
it is not safe to assume that user-level called a handler with the
proper number of arguments.
- o Fsyscall-handlers need to be careful when accessing per-CPU variables:
+ * Fsyscall-handlers need to be careful when accessing per-CPU variables:
unless proper safe-guards are taken (e.g., interruptions are avoided),
execution may be pre-empted and resumed on another CPU at any given
time.
- o Fsyscall-handlers must be careful not to leak sensitive kernel'
+ * Fsyscall-handlers must be careful not to leak sensitive kernel'
information back to user-level. In particular, before returning to
user-level, care needs to be taken to clear any scratch registers
that could contain sensitive information (note that the current
task pointer is not considered sensitive: it's already exposed
through ar.k6).
- o Fsyscall-handlers MUST NOT access user-memory without first
+ * Fsyscall-handlers MUST NOT access user-memory without first
validating access-permission (this can be done typically via
probe.r.fault and/or probe.w.fault) and without guarding against
memory access exceptions (this can be done with the EX() macros
@@ -162,7 +170,8 @@ fast system call execution (while fully preserving system call
semantics), but there is also a lot of flexibility in handling more
complicated cases.
-* Signal handling
+Signal handling
+===============
The delivery of (asynchronous) signals must be delayed until fsys-mode
is exited. This is accomplished with the help of the lower-privilege
@@ -173,7 +182,8 @@ PSR.lp and returns immediately. When fsys-mode is exited via the
occur. The trap handler clears PSR.lp again and returns immediately.
The kernel exit path then checks for and delivers any pending signals.
-* PSR Handling
+PSR Handling
+============
The "epc" instruction doesn't change the contents of PSR at all. This
is in contrast to a regular interruption, which clears almost all
@@ -181,6 +191,7 @@ bits. Because of that, some care needs to be taken to ensure things
work as expected. The following discussion describes how each PSR bit
is handled.
+======= =======================================================================
PSR.be Cleared when entering fsys-mode. A srlz.d instruction is used
to ensure the CPU is in little-endian mode before the first
load/store instruction is executed. PSR.be is normally NOT
@@ -202,7 +213,8 @@ PSR.pp Unchanged.
PSR.di Unchanged.
PSR.si Unchanged.
PSR.db Unchanged. The kernel prevents user-level from setting a hardware
- breakpoint that triggers at any privilege level other than 3 (user-mode).
+ breakpoint that triggers at any privilege level other than
+ 3 (user-mode).
PSR.lp Unchanged.
PSR.tb Lazy redirect. If a taken-branch trap occurs while in
fsys-mode, the trap-handler modifies the saved machine state
@@ -235,47 +247,52 @@ PSR.ed Unchanged. Note: This bit could only have an effect if an fsys-mode
PSR.bn Unchanged. Note: fsys-mode handlers may clear the bit, if needed.
Doing so requires clearing PSR.i and PSR.ic as well.
PSR.ia Unchanged. Note: the ia64 linux kernel never sets this bit.
+======= =======================================================================
-* Using fast system calls
+Using fast system calls
+=======================
To use fast system calls, userspace applications need simply call
__kernel_syscall_via_epc(). For example
-- example fgettimeofday() call --
+
-- fgettimeofday.S --
-#include <asm/asmmacro.h>
+::
-GLOBAL_ENTRY(fgettimeofday)
-.prologue
-.save ar.pfs, r11
-mov r11 = ar.pfs
-.body
+ #include <asm/asmmacro.h>
-mov r2 = 0xa000000000020660;; // gate address
- // found by inspection of System.map for the
+ GLOBAL_ENTRY(fgettimeofday)
+ .prologue
+ .save ar.pfs, r11
+ mov r11 = ar.pfs
+ .body
+
+ mov r2 = 0xa000000000020660;; // gate address
+ // found by inspection of System.map for the
// __kernel_syscall_via_epc() function. See
// below for how to do this for real.
-mov b7 = r2
-mov r15 = 1087 // gettimeofday syscall
-;;
-br.call.sptk.many b6 = b7
-;;
+ mov b7 = r2
+ mov r15 = 1087 // gettimeofday syscall
+ ;;
+ br.call.sptk.many b6 = b7
+ ;;
-.restore sp
+ .restore sp
-mov ar.pfs = r11
-br.ret.sptk.many rp;; // return to caller
-END(fgettimeofday)
+ mov ar.pfs = r11
+ br.ret.sptk.many rp;; // return to caller
+ END(fgettimeofday)
-- end fgettimeofday.S --
In reality, getting the gate address is accomplished by two extra
values passed via the ELF auxiliary vector (include/asm-ia64/elf.h)
- o AT_SYSINFO : is the address of __kernel_syscall_via_epc()
- o AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO
+ * AT_SYSINFO : is the address of __kernel_syscall_via_epc()
+ * AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO
The ELF DSO is a pre-linked library that is mapped in by the kernel at
the gate page. It is a proper ELF shared object so, with a dynamic
diff --git a/Documentation/ia64/README b/Documentation/ia64/ia64.rst
similarity index 61%
rename from Documentation/ia64/README
rename to Documentation/ia64/ia64.rst
index aa17f2154cba..b725019a9492 100644
--- a/Documentation/ia64/README
+++ b/Documentation/ia64/ia64.rst
@@ -1,43 +1,49 @@
- Linux kernel release 2.4.xx for the IA-64 Platform
+===========================================
+Linux kernel release for the IA-64 Platform
+===========================================
- These are the release notes for Linux version 2.4 for IA-64
+ These are the release notes for Linux since version 2.4 for IA-64
platform. This document provides information specific to IA-64
ONLY, to get additional information about the Linux kernel also
read the original Linux README provided with the kernel.
-INSTALLING the kernel:
+Installing the Kernel
+=====================
- IA-64 kernel installation is the same as the other platforms, see
original README for details.
-SOFTWARE REQUIREMENTS
+Software Requirements
+=====================
Compiling and running this kernel requires an IA-64 compliant GCC
compiler. And various software packages also compiled with an
IA-64 compliant GCC compiler.
-CONFIGURING the kernel:
+Configuring the Kernel
+======================
Configuration is the same, see original README for details.
-COMPILING the kernel:
+Compiling the Kernel:
- Compiling this kernel doesn't differ from other platform so read
the original README for details BUT make sure you have an IA-64
compliant GCC compiler.
-IA-64 SPECIFICS
+IA-64 Specifics
+===============
- General issues:
- o Hardly any performance tuning has been done. Obvious targets
+ * Hardly any performance tuning has been done. Obvious targets
include the library routines (IP checksum, etc.). Less
obvious targets include making sure we don't flush the TLB
needlessly, etc.
- o SMP locks cleanup/optimization
+ * SMP locks cleanup/optimization
- o IA32 support. Currently experimental. It mostly works.
+ * IA32 support. Currently experimental. It mostly works.
diff --git a/Documentation/ia64/index.rst b/Documentation/ia64/index.rst
new file mode 100644
index 000000000000..a3e3052ad6e2
--- /dev/null
+++ b/Documentation/ia64/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+==================
+IA-64 Architecture
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ ia64
+ aliasing
+ efirtc
+ err_inject
+ fsys
+ irq-redir
+ mca
+ serial
+ xen
diff --git a/Documentation/ia64/IRQ-redir.txt b/Documentation/ia64/irq-redir.rst
similarity index 86%
rename from Documentation/ia64/IRQ-redir.txt
rename to Documentation/ia64/irq-redir.rst
index f7bd72261283..39bf94484a15 100644
--- a/Documentation/ia64/IRQ-redir.txt
+++ b/Documentation/ia64/irq-redir.rst
@@ -1,6 +1,8 @@
+==============================
IRQ affinity on IA64 platforms
-------------------------------
- 07.01.2002, Erich Focht <efocht@ess.nec.de>
+==============================
+
+07.01.2002, Erich Focht <efocht@ess.nec.de>
By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
@@ -12,22 +14,27 @@ IRQ target is one particular CPU and cannot be a mask of several
CPUs. Only the first non-zero bit is taken into account.
-Usage examples:
+Usage examples
+==============
The target CPU has to be specified as a hexadecimal CPU mask. The
first non-zero bit is the selected CPU. This format has been kept for
compatibility reasons with i386.
Set the delivery mode of interrupt 41 to fixed and route the
-interrupts to CPU #3 (logical CPU number) (2^3=0x08):
+interrupts to CPU #3 (logical CPU number) (2^3=0x08)::
+
echo "8" >/proc/irq/41/smp_affinity
Set the default route for IRQ number 41 to CPU 6 in lowest priority
-delivery mode (redirectable):
+delivery mode (redirectable)::
+
echo "r 40" >/proc/irq/41/smp_affinity
-The output of the command
+The output of the command::
+
cat /proc/irq/IRQ#/smp_affinity
+
gives the target CPU mask for the specified interrupt vector. If the CPU
mask is preceded by the character "r", the interrupt is redirectable
(i.e. lowest priority mode routing is used), otherwise its route is
@@ -35,7 +42,8 @@ fixed.
-Initialization and default behavior:
+Initialization and default behavior
+===================================
If the platform features IRQ redirection (info provided by SAL) all
IO-SAPIC interrupts are initialized with CPU#0 as their default target
@@ -43,9 +51,11 @@ and the routing is the so called "lowest priority mode" (actually
fixed SAPIC mode with hint). The XTP chipset registers are used as hints
for the IRQ routing. Currently in Linux XTP registers can have three
values:
+
- minimal for an idle task,
- normal if any other task runs,
- maximal if the CPU is going to be switched off.
+
The IRQ is routed to the CPU with lowest XTP register value, the
search begins at the default CPU. Therefore most of the interrupts
will be handled by CPU #0.
@@ -53,12 +63,14 @@ will be handled by CPU #0.
If the platform doesn't feature interrupt redirection IOSAPIC fixed
routing is used. The target CPUs are distributed in a round robin
manner. IRQs will be routed only to the selected target CPUs. Check
-with
+with::
+
cat /proc/interrupts
-Comments:
+Comments
+========
On large (multi-node) systems it is recommended to route the IRQs to
the node to which the corresponding device is connected.
@@ -66,4 +78,3 @@ For systems like the NEC AzusA we get IRQ node-affinity for free. This
is because usually the chipsets on each node redirect the interrupts
only to their own CPUs (as they cannot see the XTP registers on the
other nodes).
-
diff --git a/Documentation/ia64/mca.txt b/Documentation/ia64/mca.rst
similarity index 96%
rename from Documentation/ia64/mca.txt
rename to Documentation/ia64/mca.rst
index f097c60cba1b..08270bba44a4 100644
--- a/Documentation/ia64/mca.txt
+++ b/Documentation/ia64/mca.rst
@@ -1,5 +1,8 @@
-An ad-hoc collection of notes on IA64 MCA and INIT processing. Feel
-free to update it with notes about any area that is not clear.
+=============================================================
+An ad-hoc collection of notes on IA64 MCA and INIT processing
+=============================================================
+
+Feel free to update it with notes about any area that is not clear.
---
@@ -82,7 +85,8 @@ if we have a choice here.
own stack as running on that cpu. Then a recursive error gets a
trace of the failing handler's "task".
-[1] My (Keith Owens) original design called for ia64 to separate its
+[1]
+ My (Keith Owens) original design called for ia64 to separate its
struct task and the kernel stacks. Then the MCA/INIT data would be
chained stacks like i386 interrupt stacks. But that required
radical surgery on the rest of ia64, plus extra hard wired TLB
diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.rst
similarity index 87%
rename from Documentation/ia64/serial.txt
rename to Documentation/ia64/serial.rst
index a63d2c54329b..1de70c305a79 100644
--- a/Documentation/ia64/serial.txt
+++ b/Documentation/ia64/serial.rst
@@ -1,4 +1,9 @@
-SERIAL DEVICE NAMING
+==============
+Serial Devices
+==============
+
+Serial Device Naming
+====================
As of 2.6.10, serial devices on ia64 are named based on the
order of ACPI and PCI enumeration. The first device in the
@@ -30,17 +35,21 @@ SERIAL DEVICE NAMING
(described in the ACPI namespace) plus an MP[2] (a PCI device) has
these ports:
- pre-2.6.10 pre-2.6.10
- MMIO (EFI console (EFI console
- address on builtin) on MP port) 2.6.10
- ========== ========== ========== ======
+ ========== ========== ============ ============ =======
+ Type MMIO pre-2.6.10 pre-2.6.10 2.6.10+
+ address
+ (EFI console (EFI console
+ on builtin) on MP port)
+ ========== ========== ============ ============ =======
builtin 0xff5e0000 ttyS0 ttyS1 ttyS0
MP UPS 0xf8031000 ttyS1 ttyS2 ttyS1
MP Console 0xf8030000 ttyS2 ttyS0 ttyS2
MP 2 0xf8030010 ttyS3 ttyS3 ttyS3
MP 3 0xf8030038 ttyS4 ttyS4 ttyS4
+ ========== ========== ============ ============ =======
-CONSOLE SELECTION
+Console Selection
+=================
EFI knows what your console devices are, but it doesn't tell the
kernel quite enough to actually locate them. The DIG64 HCDP
@@ -67,7 +76,8 @@ CONSOLE SELECTION
entries in /etc/inittab (for getty) and /etc/securetty (to allow
root login).
-EARLY SERIAL CONSOLE
+Early Serial Console
+====================
The kernel can't start using a serial console until it knows where
the device lives. Normally this happens when the driver enumerates
@@ -80,7 +90,8 @@ EARLY SERIAL CONSOLE
or if the EFI console path contains only a UART device and the
firmware supplies an HCDP.
-TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
+Troubleshooting Serial Console Problems
+=======================================
No kernel output after elilo prints "Uncompressing Linux... done":
@@ -133,19 +144,22 @@ TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
-[1] http://www.dig64.org/specifications/agreement
+[1]
+ http://www.dig64.org/specifications/agreement
The table was originally defined as the "HCDP" for "Headless
Console/Debug Port." The current version is the "PCDP" for
"Primary Console and Debug Port Devices."
-[2] The HP MP (management processor) is a PCI device that provides
+[2]
+ The HP MP (management processor) is a PCI device that provides
several UARTs. One of the UARTs is often used as a console; the
EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart".
The external connection is usually a 25-pin connector, and a
special dongle converts that to three 9-pin connectors, one of
which is labelled "Console."
-[3] EFI console devices are configured using the EFI Boot Manager
+[3]
+ EFI console devices are configured using the EFI Boot Manager
"Boot option maintenance" menu. You may have to interrupt the
boot sequence to use this menu, and you will have to reset the
box after changing console configuration.
diff --git a/Documentation/ia64/xen.rst b/Documentation/ia64/xen.rst
new file mode 100644
index 000000000000..831339c74441
--- /dev/null
+++ b/Documentation/ia64/xen.rst
@@ -0,0 +1,206 @@
+********************************************************
+Recipe for getting/building/running Xen/ia64 with pv_ops
+********************************************************
+This recipe describes how to get xen-ia64 source and build it,
+and run domU with pv_ops.
+
+Requirements
+============
+
+ - python
+ - mercurial
+ it (aka "hg") is an open-source source code
+ management software. See the below.
+ http://www.selenic.com/mercurial/wiki/
+ - git
+ - bridge-utils
+
+Getting and Building Xen and Dom0
+=================================
+
+ My environment is:
+
+ - Machine : Tiger4
+ - Domain0 OS : RHEL5
+ - DomainU OS : RHEL5
+
+ 1. Download source::
+
+ # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg
+ # cd xen-unstable.hg
+ # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg
+
+ 2. # make world
+
+ 3. # make install-tools
+
+ 4. copy kernels and xen::
+
+ # cp xen/xen.gz /boot/efi/efi/redhat/
+ # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \
+ /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen
+
+ 5. make initrd for Dom0/DomU::
+
+ # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \
+ O=$(pwd)/build-linux-2.6.18-xen_ia64
+ # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \
+ 2.6.18.8-xen --builtin mptspi --builtin mptbase \
+ --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \
+ --builtin ehci-hcd
+
+Making a disk image for guest OS
+================================
+
+ 1. make file::
+
+ # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0
+ # mke2fs -F -j /root/rhel5.img
+ # mount -o loop /root/rhel5.img /mnt
+ # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt
+ # mkdir /mnt/{root,proc,sys,home,tmp}
+
+ Note: You may miss some device files. If so, please create them
+ with mknod. Or you can use tar instead of cp.
+
+ 2. modify DomU's fstab::
+
+ # vi /mnt/etc/fstab
+ /dev/xvda1 / ext3 defaults 1 1
+ none /dev/pts devpts gid=5,mode=620 0 0
+ none /dev/shm tmpfs defaults 0 0
+ none /proc proc defaults 0 0
+ none /sys sysfs defaults 0 0
+
+ 3. modify inittab
+
+ set runlevel to 3 to avoid X trying to start::
+
+ # vi /mnt/etc/inittab
+ id:3:initdefault:
+
+ Start a getty on the hvc0 console::
+
+ X0:2345:respawn:/sbin/mingetty hvc0
+
+ tty1-6 mingetty can be commented out
+
+ 4. add hvc0 into /etc/securetty::
+
+ # vi /mnt/etc/securetty (add hvc0)
+
+ 5. umount::
+
+ # umount /mnt
+
+FYI, virt-manager can also make a disk image for guest OS.
+It's GUI tools and easy to make it.
+
+Boot Xen & Domain0
+==================
+
+ 1. replace elilo
+ elilo of RHEL5 can boot Xen and Dom0.
+ If you use old elilo (e.g RHEL4), please download from the below
+ http://elilo.sourceforge.net/cgi-bin/blosxom
+ and copy into /boot/efi/efi/redhat/::
+
+ # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi
+
+ 2. modify elilo.conf (like the below)::
+
+ # vi /boot/efi/efi/redhat/elilo.conf
+ prompt
+ timeout=20
+ default=xen
+ relocatable
+
+ image=vmlinuz-2.6.18.8-xen
+ label=xen
+ vmm=xen.gz
+ initrd=initrd-2.6.18.8-xen.img
+ read-only
+ append=" -- rhgb root=/dev/sda2"
+
+The append options before "--" are for xen hypervisor,
+the options after "--" are for dom0.
+
+FYI, your machine may need console options like
+"com1=19200,8n1 console=vga,com1". For example,
+append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \
+console=ttyS0 root=/dev/sda2"
+
+Getting and Building domU with pv_ops
+=====================================
+
+ 1. get pv_ops tree::
+
+ # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/
+
+ 2. git branch (if necessary)::
+
+ # cd linux-2.6-xen-ia64/
+ # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19
+
+ Note:
+ The current branch is xen-ia64-domu-minimal-2008may19.
+ But you would find the new branch. You can see with
+ "git branch -r" to get the branch lists.
+
+ http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/
+
+ is also available.
+
+ The tree is based on
+
+ git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test)
+
+ 3. copy .config for pv_ops of domU::
+
+ # cp arch/ia64/configs/xen_domu_wip_defconfig .config
+
+ 4. make kernel with pv_ops::
+
+ # make oldconfig
+ # make
+
+ 5. install the kernel and initrd::
+
+ # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU
+ # make modules_install
+ # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \
+ 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \
+ --builtin mptbase --builtin mptscsih --builtin uhci-hcd \
+ --builtin ohci-hcd --builtin ehci-hcd
+
+Boot DomainU with pv_ops
+========================
+
+ 1. make config of DomU::
+
+ # vi /etc/xen/rhel5
+ kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU"
+ ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img"
+ vcpus = 1
+ memory = 512
+ name = "rhel5"
+ disk = [ 'file:/root/rhel5.img,xvda1,w' ]
+ root = "/dev/xvda1 ro"
+ extra= "rhgb console=hvc0"
+
+ 2. After boot xen and dom0, start xend::
+
+ # /etc/init.d/xend start
+
+ ( In the debugging case, `# XEND_DEBUG=1 xend trace_start` )
+
+ 3. start domU::
+
+ # xm create -c rhel5
+
+Reference
+=========
+- Wiki of Xen/IA64 upstream merge
+ http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge
+
+Written by Akio Takebe <takebe_akio@jp.fujitsu.com> on 28 May 2008
diff --git a/Documentation/ia64/xen.txt b/Documentation/ia64/xen.txt
deleted file mode 100644
index a12c74ce2773..000000000000
--- a/Documentation/ia64/xen.txt
+++ /dev/null
@@ -1,183 +0,0 @@
- Recipe for getting/building/running Xen/ia64 with pv_ops
- --------------------------------------------------------
-
-This recipe describes how to get xen-ia64 source and build it,
-and run domU with pv_ops.
-
-============
-Requirements
-============
-
- - python
- - mercurial
- it (aka "hg") is an open-source source code
- management software. See the below.
- http://www.selenic.com/mercurial/wiki/
- - git
- - bridge-utils
-
-=================================
-Getting and Building Xen and Dom0
-=================================
-
- My environment is;
- Machine : Tiger4
- Domain0 OS : RHEL5
- DomainU OS : RHEL5
-
- 1. Download source
- # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg
- # cd xen-unstable.hg
- # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg
-
- 2. # make world
-
- 3. # make install-tools
-
- 4. copy kernels and xen
- # cp xen/xen.gz /boot/efi/efi/redhat/
- # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \
- /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen
-
- 5. make initrd for Dom0/DomU
- # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \
- O=$(pwd)/build-linux-2.6.18-xen_ia64
- # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \
- 2.6.18.8-xen --builtin mptspi --builtin mptbase \
- --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \
- --builtin ehci-hcd
-
-================================
-Making a disk image for guest OS
-================================
-
- 1. make file
- # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0
- # mke2fs -F -j /root/rhel5.img
- # mount -o loop /root/rhel5.img /mnt
- # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt
- # mkdir /mnt/{root,proc,sys,home,tmp}
-
- Note: You may miss some device files. If so, please create them
- with mknod. Or you can use tar instead of cp.
-
- 2. modify DomU's fstab
- # vi /mnt/etc/fstab
- /dev/xvda1 / ext3 defaults 1 1
- none /dev/pts devpts gid=5,mode=620 0 0
- none /dev/shm tmpfs defaults 0 0
- none /proc proc defaults 0 0
- none /sys sysfs defaults 0 0
-
- 3. modify inittab
- set runlevel to 3 to avoid X trying to start
- # vi /mnt/etc/inittab
- id:3:initdefault:
- Start a getty on the hvc0 console
- X0:2345:respawn:/sbin/mingetty hvc0
- tty1-6 mingetty can be commented out
-
- 4. add hvc0 into /etc/securetty
- # vi /mnt/etc/securetty (add hvc0)
-
- 5. umount
- # umount /mnt
-
-FYI, virt-manager can also make a disk image for guest OS.
-It's GUI tools and easy to make it.
-
-==================
-Boot Xen & Domain0
-==================
-
- 1. replace elilo
- elilo of RHEL5 can boot Xen and Dom0.
- If you use old elilo (e.g RHEL4), please download from the below
- http://elilo.sourceforge.net/cgi-bin/blosxom
- and copy into /boot/efi/efi/redhat/
- # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi
-
- 2. modify elilo.conf (like the below)
- # vi /boot/efi/efi/redhat/elilo.conf
- prompt
- timeout=20
- default=xen
- relocatable
-
- image=vmlinuz-2.6.18.8-xen
- label=xen
- vmm=xen.gz
- initrd=initrd-2.6.18.8-xen.img
- read-only
- append=" -- rhgb root=/dev/sda2"
-
-The append options before "--" are for xen hypervisor,
-the options after "--" are for dom0.
-
-FYI, your machine may need console options like
-"com1=19200,8n1 console=vga,com1". For example,
-append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \
-console=ttyS0 root=/dev/sda2"
-
-=====================================
-Getting and Building domU with pv_ops
-=====================================
-
- 1. get pv_ops tree
- # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/
-
- 2. git branch (if necessary)
- # cd linux-2.6-xen-ia64/
- # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19
- (Note: The current branch is xen-ia64-domu-minimal-2008may19.
- But you would find the new branch. You can see with
- "git branch -r" to get the branch lists.
- http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/
- is also available. The tree is based on
- git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test)
-
-
- 3. copy .config for pv_ops of domU
- # cp arch/ia64/configs/xen_domu_wip_defconfig .config
-
- 4. make kernel with pv_ops
- # make oldconfig
- # make
-
- 5. install the kernel and initrd
- # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU
- # make modules_install
- # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \
- 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \
- --builtin mptbase --builtin mptscsih --builtin uhci-hcd \
- --builtin ohci-hcd --builtin ehci-hcd
-
-========================
-Boot DomainU with pv_ops
-========================
-
- 1. make config of DomU
- # vi /etc/xen/rhel5
- kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU"
- ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img"
- vcpus = 1
- memory = 512
- name = "rhel5"
- disk = [ 'file:/root/rhel5.img,xvda1,w' ]
- root = "/dev/xvda1 ro"
- extra= "rhgb console=hvc0"
-
- 2. After boot xen and dom0, start xend
- # /etc/init.d/xend start
- ( In the debugging case, # XEND_DEBUG=1 xend trace_start )
-
- 3. start domU
- # xm create -c rhel5
-
-=========
-Reference
-=========
-- Wiki of Xen/IA64 upstream merge
- http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge
-
-Written by Akio Takebe <takebe_akio@jp.fujitsu.com> on 28 May 2008
diff --git a/MAINTAINERS b/MAINTAINERS
index 969225e6bfce..f8f2394f9e84 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14263,7 +14263,7 @@ SGI SN-IA64 (Altix) SERIAL CONSOLE DRIVER
M: Pat Gefre <pfg@sgi.com>
L: linux-ia64@vger.kernel.org
S: Supported
-F: Documentation/ia64/serial.txt
+F: Documentation/ia64/serial.rst
F: drivers/tty/serial/ioc?_serial.c
F: include/linux/ioc?.h
diff --git a/arch/ia64/kernel/efi.c b/arch/ia64/kernel/efi.c
index 8f106638913c..3795d18276c4 100644
--- a/arch/ia64/kernel/efi.c
+++ b/arch/ia64/kernel/efi.c
@@ -852,7 +852,7 @@ valid_phys_addr_range (phys_addr_t phys_addr, unsigned long size)
* /dev/mem reads and writes use copy_to_user(), which implicitly
* uses a granule-sized kernel identity mapping. It's really
* only safe to do this for regions in kern_memmap. For more
- * details, see Documentation/ia64/aliasing.txt.
+ * details, see Documentation/ia64/aliasing.rst.
*/
attr = kern_mem_attribute(phys_addr, size);
if (attr & EFI_MEMORY_WB || attr & EFI_MEMORY_UC)
diff --git a/arch/ia64/kernel/fsys.S b/arch/ia64/kernel/fsys.S
index d80c99a5f55d..0750a716adc7 100644
--- a/arch/ia64/kernel/fsys.S
+++ b/arch/ia64/kernel/fsys.S
@@ -28,7 +28,7 @@
#include <asm/native/inst.h>
/*
- * See Documentation/ia64/fsys.txt for details on fsyscalls.
+ * See Documentation/ia64/fsys.rst for details on fsyscalls.
*
* On entry to an fsyscall handler:
* r10 = 0 (i.e., defaults to "successful syscall return")
diff --git a/arch/ia64/mm/ioremap.c b/arch/ia64/mm/ioremap.c
index 43964cde6214..c7da3376b6f8 100644
--- a/arch/ia64/mm/ioremap.c
+++ b/arch/ia64/mm/ioremap.c
@@ -45,7 +45,7 @@ ioremap (unsigned long phys_addr, unsigned long size)
/*
* For things in kern_memmap, we must use the same attribute
* as the rest of the kernel. For more details, see
- * Documentation/ia64/aliasing.txt.
+ * Documentation/ia64/aliasing.rst.
*/
attr = kern_mem_attribute(phys_addr, size);
if (attr & EFI_MEMORY_WB)
diff --git a/arch/ia64/pci/pci.c b/arch/ia64/pci/pci.c
index e308196c2229..165e561dc81a 100644
--- a/arch/ia64/pci/pci.c
+++ b/arch/ia64/pci/pci.c
@@ -450,7 +450,7 @@ pci_mmap_legacy_page_range(struct pci_bus *bus, struct vm_area_struct *vma,
return -ENOSYS;
/*
- * Avoid attribute aliasing. See Documentation/ia64/aliasing.txt
+ * Avoid attribute aliasing. See Documentation/ia64/aliasing.rst
* for more details.
*/
if (!valid_mmap_phys_addr_range(vma->vm_pgoff, size))
--
2.21.0
^ permalink raw reply related
* [PATCH v1 18/31] docs: accounting: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Balbir Singh, Tejun Heo, Li Zefan,
Johannes Weiner, cgroups
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the accounting documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{cgroupstats.txt => cgroupstats.rst} | 14 ++--
...ay-accounting.txt => delay-accounting.rst} | 61 ++++++++------
Documentation/accounting/index.rst | 14 ++++
Documentation/accounting/{psi.txt => psi.rst} | 40 +++++-----
...kstats-struct.txt => taskstats-struct.rst} | 79 ++++++++++++-------
.../{taskstats.txt => taskstats.rst} | 15 ++--
Documentation/admin-guide/cgroup-v2.rst | 6 +-
init/Kconfig | 2 +-
8 files changed, 139 insertions(+), 92 deletions(-)
rename Documentation/accounting/{cgroupstats.txt => cgroupstats.rst} (77%)
rename Documentation/accounting/{delay-accounting.txt => delay-accounting.rst} (77%)
create mode 100644 Documentation/accounting/index.rst
rename Documentation/accounting/{psi.txt => psi.rst} (91%)
rename Documentation/accounting/{taskstats-struct.txt => taskstats-struct.rst} (78%)
rename Documentation/accounting/{taskstats.txt => taskstats.rst} (95%)
diff --git a/Documentation/accounting/cgroupstats.txt b/Documentation/accounting/cgroupstats.rst
similarity index 77%
rename from Documentation/accounting/cgroupstats.txt
rename to Documentation/accounting/cgroupstats.rst
index d16a9849e60e..b9afc48f4ea2 100644
--- a/Documentation/accounting/cgroupstats.txt
+++ b/Documentation/accounting/cgroupstats.rst
@@ -1,3 +1,7 @@
+==================
+Control Groupstats
+==================
+
Control Groupstats is inspired by the discussion at
http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as
suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
@@ -19,9 +23,9 @@ about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
information will not be available.
To extract cgroup statistics a utility very similar to getdelays.c
-has been developed, the sample output of the utility is shown below
+has been developed, the sample output of the utility is shown below::
-~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a"
-sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
-~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup"
-sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
+ ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a"
+ sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
+ ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup"
+ sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
diff --git a/Documentation/accounting/delay-accounting.txt b/Documentation/accounting/delay-accounting.rst
similarity index 77%
rename from Documentation/accounting/delay-accounting.txt
rename to Documentation/accounting/delay-accounting.rst
index 042ea59b5853..7cc7f5852da0 100644
--- a/Documentation/accounting/delay-accounting.txt
+++ b/Documentation/accounting/delay-accounting.rst
@@ -1,5 +1,6 @@
+================
Delay accounting
-----------------
+================
Tasks encounter delays in execution when they wait
for some kernel resource to become available e.g. a
@@ -39,7 +40,9 @@ in detail in a separate document in this directory. Taskstats returns a
generic data structure to userspace corresponding to per-pid and per-tgid
statistics. The delay accounting functionality populates specific fields of
this structure. See
+
include/linux/taskstats.h
+
for a description of the fields pertaining to delay accounting.
It will generally be in the form of counters returning the cumulative
delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
@@ -61,13 +64,16 @@ also serves as an example of using the taskstats interface.
Usage
-----
-Compile the kernel with
+Compile the kernel with::
+
CONFIG_TASK_DELAY_ACCT=y
CONFIG_TASKSTATS=y
Delay accounting is enabled by default at boot up.
-To disable, add
+To disable, add::
+
nodelayacct
+
to the kernel boot options. The rest of the instructions
below assume this has not been done.
@@ -78,40 +84,43 @@ The utility also allows a given command to be
executed and the corresponding delays to be
seen.
-General format of the getdelays command
+General format of the getdelays command::
-getdelays [-t tgid] [-p pid] [-c cmd...]
+ getdelays [-t tgid] [-p pid] [-c cmd...]
-Get delays, since system boot, for pid 10
-# ./getdelays -p 10
-(output similar to next case)
+Get delays, since system boot, for pid 10::
-Get sum of delays, since system boot, for all pids with tgid 5
-# ./getdelays -t 5
+ # ./getdelays -p 10
+ (output similar to next case)
+Get sum of delays, since system boot, for all pids with tgid 5::
-CPU count real total virtual total delay total
- 7876 92005750 100000000 24001500
-IO count delay total
- 0 0
-SWAP count delay total
- 0 0
-RECLAIM count delay total
- 0 0
+ # ./getdelays -t 5
-Get delays seen in executing a given simple command
-# ./getdelays -c ls /
-bin data1 data3 data5 dev home media opt root srv sys usr
-boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var
+ CPU count real total virtual total delay total
+ 7876 92005750 100000000 24001500
+ IO count delay total
+ 0 0
+ SWAP count delay total
+ 0 0
+ RECLAIM count delay total
+ 0 0
+Get delays seen in executing a given simple command::
-CPU count real total virtual total delay total
+ # ./getdelays -c ls /
+
+ bin data1 data3 data5 dev home media opt root srv sys usr
+ boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var
+
+
+ CPU count real total virtual total delay total
6 4000250 4000000 0
-IO count delay total
+ IO count delay total
0 0
-SWAP count delay total
+ SWAP count delay total
0 0
-RECLAIM count delay total
+ RECLAIM count delay total
0 0
diff --git a/Documentation/accounting/index.rst b/Documentation/accounting/index.rst
new file mode 100644
index 000000000000..e1f6284b5ff3
--- /dev/null
+++ b/Documentation/accounting/index.rst
@@ -0,0 +1,14 @@
+:orphan:
+
+==========
+Accounting
+==========
+
+.. toctree::
+ :maxdepth: 1
+
+ cgroupstats
+ delay-accounting
+ psi
+ taskstats
+ taskstats-struct
diff --git a/Documentation/accounting/psi.txt b/Documentation/accounting/psi.rst
similarity index 91%
rename from Documentation/accounting/psi.txt
rename to Documentation/accounting/psi.rst
index 5cbe5659e3b7..621111ce5740 100644
--- a/Documentation/accounting/psi.txt
+++ b/Documentation/accounting/psi.rst
@@ -35,14 +35,14 @@ Pressure interface
Pressure information for each resource is exported through the
respective file in /proc/pressure/ -- cpu, memory, and io.
-The format for CPU is as such:
+The format for CPU is as such::
-some avg10=0.00 avg60=0.00 avg300=0.00 total=0
+ some avg10=0.00 avg60=0.00 avg300=0.00 total=0
-and for memory and IO:
+and for memory and IO::
-some avg10=0.00 avg60=0.00 avg300=0.00 total=0
-full avg10=0.00 avg60=0.00 avg300=0.00 total=0
+ some avg10=0.00 avg60=0.00 avg300=0.00 total=0
+ full avg10=0.00 avg60=0.00 avg300=0.00 total=0
The "some" line indicates the share of time in which at least some
tasks are stalled on a given resource.
@@ -77,9 +77,9 @@ To register a trigger user has to open psi interface file under
/proc/pressure/ representing the resource to be monitored and write the
desired threshold and time window. The open file descriptor should be
used to wait for trigger events using select(), poll() or epoll().
-The following format is used:
+The following format is used::
-<some|full> <stall amount in us> <time window in us>
+ <some|full> <stall amount in us> <time window in us>
For example writing "some 150000 1000000" into /proc/pressure/memory
would add 150ms threshold for partial memory stall measured within
@@ -115,18 +115,20 @@ trigger is closed.
Userspace monitor usage example
===============================
-#include <errno.h>
-#include <fcntl.h>
-#include <stdio.h>
-#include <poll.h>
-#include <string.h>
-#include <unistd.h>
+::
-/*
- * Monitor memory partial stall with 1s tracking window size
- * and 150ms threshold.
- */
-int main() {
+ #include <errno.h>
+ #include <fcntl.h>
+ #include <stdio.h>
+ #include <poll.h>
+ #include <string.h>
+ #include <unistd.h>
+
+ /*
+ * Monitor memory partial stall with 1s tracking window size
+ * and 150ms threshold.
+ */
+ int main() {
const char trig[] = "some 150000 1000000";
struct pollfd fds;
int n;
@@ -165,7 +167,7 @@ int main() {
}
return 0;
-}
+ }
Cgroup2 interface
=================
diff --git a/Documentation/accounting/taskstats-struct.txt b/Documentation/accounting/taskstats-struct.rst
similarity index 78%
rename from Documentation/accounting/taskstats-struct.txt
rename to Documentation/accounting/taskstats-struct.rst
index e7512c061c15..ca90fd489c9a 100644
--- a/Documentation/accounting/taskstats-struct.txt
+++ b/Documentation/accounting/taskstats-struct.rst
@@ -1,5 +1,6 @@
+====================
The struct taskstats
---------------------
+====================
This document contains an explanation of the struct taskstats fields.
@@ -10,16 +11,24 @@ There are three different groups of fields in the struct taskstats:
the common fields and basic accounting fields are collected for
delivery at do_exit() of a task.
2) Delay accounting fields
- These fields are placed between
- /* Delay accounting fields start */
- and
- /* Delay accounting fields end */
+ These fields are placed between::
+
+ /* Delay accounting fields start */
+
+ and::
+
+ /* Delay accounting fields end */
+
Their values are collected if CONFIG_TASK_DELAY_ACCT is set.
3) Extended accounting fields
- These fields are placed between
- /* Extended accounting fields start */
- and
- /* Extended accounting fields end */
+ These fields are placed between::
+
+ /* Extended accounting fields start */
+
+ and::
+
+ /* Extended accounting fields end */
+
Their values are collected if CONFIG_TASK_XACCT is set.
4) Per-task and per-thread context switch count statistics
@@ -31,31 +40,33 @@ There are three different groups of fields in the struct taskstats:
Future extension should add fields to the end of the taskstats struct, and
should not change the relative position of each field within the struct.
+::
-struct taskstats {
+ struct taskstats {
+
+1) Common and basic accounting fields::
-1) Common and basic accounting fields:
/* The version number of this struct. This field is always set to
* TAKSTATS_VERSION, which is defined in <linux/taskstats.h>.
* Each time the struct is changed, the value should be incremented.
*/
__u16 version;
- /* The exit code of a task. */
+ /* The exit code of a task. */
__u32 ac_exitcode; /* Exit status */
- /* The accounting flags of a task as defined in <linux/acct.h>
+ /* The accounting flags of a task as defined in <linux/acct.h>
* Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG.
*/
__u8 ac_flag; /* Record flags */
- /* The value of task_nice() of a task. */
+ /* The value of task_nice() of a task. */
__u8 ac_nice; /* task_nice */
- /* The name of the command that started this task. */
+ /* The name of the command that started this task. */
char ac_comm[TS_COMM_LEN]; /* Command name */
- /* The scheduling discipline as set in task->policy field. */
+ /* The scheduling discipline as set in task->policy field. */
__u8 ac_sched; /* Scheduling discipline */
__u8 ac_pad[3];
@@ -64,26 +75,27 @@ struct taskstats {
__u32 ac_pid; /* Process ID */
__u32 ac_ppid; /* Parent process ID */
- /* The time when a task begins, in [secs] since 1970. */
+ /* The time when a task begins, in [secs] since 1970. */
__u32 ac_btime; /* Begin time [sec since 1970] */
- /* The elapsed time of a task, in [usec]. */
+ /* The elapsed time of a task, in [usec]. */
__u64 ac_etime; /* Elapsed time [usec] */
- /* The user CPU time of a task, in [usec]. */
+ /* The user CPU time of a task, in [usec]. */
__u64 ac_utime; /* User CPU time [usec] */
- /* The system CPU time of a task, in [usec]. */
+ /* The system CPU time of a task, in [usec]. */
__u64 ac_stime; /* System CPU time [usec] */
- /* The minor page fault count of a task, as set in task->min_flt. */
+ /* The minor page fault count of a task, as set in task->min_flt. */
__u64 ac_minflt; /* Minor Page Fault Count */
/* The major page fault count of a task, as set in task->maj_flt. */
__u64 ac_majflt; /* Major Page Fault Count */
-2) Delay accounting fields:
+2) Delay accounting fields::
+
/* Delay accounting fields start
*
* All values, until the comment "Delay accounting fields end" are
@@ -134,7 +146,8 @@ struct taskstats {
/* version 1 ends here */
-3) Extended accounting fields
+3) Extended accounting fields::
+
/* Extended accounting fields start */
/* Accumulated RSS usage in duration of a task, in MBytes-usecs.
@@ -145,15 +158,15 @@ struct taskstats {
*/
__u64 coremem; /* accumulated RSS usage in MB-usec */
- /* Accumulated virtual memory usage in duration of a task.
+ /* Accumulated virtual memory usage in duration of a task.
* Same as acct_rss_mem1 above except that we keep track of VM usage.
*/
__u64 virtmem; /* accumulated VM usage in MB-usec */
- /* High watermark of RSS usage in duration of a task, in KBytes. */
+ /* High watermark of RSS usage in duration of a task, in KBytes. */
__u64 hiwater_rss; /* High-watermark of RSS usage */
- /* High watermark of VM usage in duration of a task, in KBytes. */
+ /* High watermark of VM usage in duration of a task, in KBytes. */
__u64 hiwater_vm; /* High-water virtual memory usage */
/* The following four fields are I/O statistics of a task. */
@@ -164,17 +177,23 @@ struct taskstats {
/* Extended accounting fields end */
-4) Per-task and per-thread statistics
+4) Per-task and per-thread statistics::
+
__u64 nvcsw; /* Context voluntary switch counter */
__u64 nivcsw; /* Context involuntary switch counter */
-5) Time accounting for SMT machines
+5) Time accounting for SMT machines::
+
__u64 ac_utimescaled; /* utime scaled on frequency etc */
__u64 ac_stimescaled; /* stime scaled on frequency etc */
__u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */
-6) Extended delay accounting fields for memory reclaim
+6) Extended delay accounting fields for memory reclaim::
+
/* Delay waiting for memory reclaim */
__u64 freepages_count;
__u64 freepages_delay_total;
-}
+
+::
+
+ }
diff --git a/Documentation/accounting/taskstats.txt b/Documentation/accounting/taskstats.rst
similarity index 95%
rename from Documentation/accounting/taskstats.txt
rename to Documentation/accounting/taskstats.rst
index ff06b738bb88..2a28b7f55c10 100644
--- a/Documentation/accounting/taskstats.txt
+++ b/Documentation/accounting/taskstats.rst
@@ -1,5 +1,6 @@
+=============================
Per-task statistics interface
------------------------------
+=============================
Taskstats is a netlink-based interface for sending per-task and
@@ -65,7 +66,7 @@ taskstats.h file.
The data exchanged between user and kernel space is a netlink message belonging
to the NETLINK_GENERIC family and using the netlink attributes interface.
-The messages are in the format
+The messages are in the format::
+----------+- - -+-------------+-------------------+
| nlmsghdr | Pad | genlmsghdr | taskstats payload |
@@ -167,15 +168,13 @@ extended and the number of cpus grows large.
To avoid losing statistics, userspace should do one or more of the following:
- increase the receive buffer sizes for the netlink sockets opened by
-listeners to receive exit data.
+ listeners to receive exit data.
- create more listeners and reduce the number of cpus being listened to by
-each listener. In the extreme case, there could be one listener for each cpu.
-Users may also consider setting the cpu affinity of the listener to the subset
-of cpus to which it listens, especially if they are listening to just one cpu.
+ each listener. In the extreme case, there could be one listener for each cpu.
+ Users may also consider setting the cpu affinity of the listener to the subset
+ of cpus to which it listens, especially if they are listening to just one cpu.
Despite these measures, if the userspace receives ENOBUFS error messages
indicated overflow of receive buffers, it should take measures to handle the
loss of data.
-
-----
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 110c3d34df71..4b971a0bc99a 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1014,7 +1014,7 @@ All time durations are in microseconds.
A read-only nested-key file which exists on non-root cgroups.
Shows pressure stall information for CPU. See
- Documentation/accounting/psi.txt for details.
+ Documentation/accounting/psi.rst for details.
Memory
@@ -1361,7 +1361,7 @@ PAGE_SIZE multiple when read back.
A read-only nested-key file which exists on non-root cgroups.
Shows pressure stall information for memory. See
- Documentation/accounting/psi.txt for details.
+ Documentation/accounting/psi.rst for details.
Usage Guidelines
@@ -1504,7 +1504,7 @@ IO Interface Files
A read-only nested-key file which exists on non-root cgroups.
Shows pressure stall information for IO. See
- Documentation/accounting/psi.txt for details.
+ Documentation/accounting/psi.rst for details.
Writeback
diff --git a/init/Kconfig b/init/Kconfig
index 6db89d4155d8..1707cf0802a7 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -517,7 +517,7 @@ config PSI
have cpu.pressure, memory.pressure, and io.pressure files,
which aggregate pressure stalls for the grouped tasks only.
- For more details see Documentation/accounting/psi.txt.
+ For more details see Documentation/accounting/psi.rst.
Say N if unsure.
--
2.21.0
^ permalink raw reply related
* [PATCH v1 09/31] docs: driver-model: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Linus Walleij, Bartosz Golaszewski, Jean Delvare,
Guenter Roeck, Greg Kroah-Hartman, Rafael J. Wysocki,
Jeff Kirsher, David S. Miller, Julia Lawall, Gilles Muller,
Nicolas Palix, Michal Marek, linux-gpio, linux-hwmon,
intel-wired-lan, netdev, cocci
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Convert the various documents at the driver-model, preparing
them to be part of the driver-api book.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/gpio/driver.rst | 2 +-
.../driver-model/{binding.txt => binding.rst} | 20 +-
.../driver-model/{bus.txt => bus.rst} | 69 ++--
.../driver-model/{class.txt => class.rst} | 74 ++--
...esign-patterns.txt => design-patterns.rst} | 106 +++---
.../driver-model/{device.txt => device.rst} | 57 +--
.../driver-model/{devres.txt => devres.rst} | 50 +--
.../driver-model/{driver.txt => driver.rst} | 112 +++---
Documentation/driver-model/index.rst | 26 ++
.../{overview.txt => overview.rst} | 37 +-
.../{platform.txt => platform.rst} | 30 +-
.../driver-model/{porting.txt => porting.rst} | 333 +++++++++---------
Documentation/eisa.txt | 4 +-
Documentation/hwmon/submitting-patches.rst | 2 +-
drivers/base/platform.c | 2 +-
drivers/gpio/gpio-cs5535.c | 2 +-
drivers/net/ethernet/intel/ice/ice_main.c | 2 +-
scripts/coccinelle/free/devm_free.cocci | 2 +-
18 files changed, 489 insertions(+), 441 deletions(-)
rename Documentation/driver-model/{binding.txt => binding.rst} (92%)
rename Documentation/driver-model/{bus.txt => bus.rst} (76%)
rename Documentation/driver-model/{class.txt => class.rst} (75%)
rename Documentation/driver-model/{design-patterns.txt => design-patterns.rst} (59%)
rename Documentation/driver-model/{device.txt => device.rst} (71%)
rename Documentation/driver-model/{devres.txt => devres.rst} (93%)
rename Documentation/driver-model/{driver.txt => driver.rst} (75%)
create mode 100644 Documentation/driver-model/index.rst
rename Documentation/driver-model/{overview.txt => overview.rst} (90%)
rename Documentation/driver-model/{platform.txt => platform.rst} (95%)
rename Documentation/driver-model/{porting.txt => porting.rst} (62%)
diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 4af9aae724f0..349f2dc33029 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -399,7 +399,7 @@ symbol:
will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the
callbacks need to embed the gpio_chip in its state container and obtain a
pointer to the container using container_of().
- (See Documentation/driver-model/design-patterns.txt)
+ (See Documentation/driver-model/design-patterns.rst)
- gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip,
as discussed above regarding different types of cascaded irqchips. The
diff --git a/Documentation/driver-model/binding.txt b/Documentation/driver-model/binding.rst
similarity index 92%
rename from Documentation/driver-model/binding.txt
rename to Documentation/driver-model/binding.rst
index abfc8e290d53..7ea1d7a41e1d 100644
--- a/Documentation/driver-model/binding.txt
+++ b/Documentation/driver-model/binding.rst
@@ -1,5 +1,6 @@
-
+==============
Driver Binding
+==============
Driver binding is the process of associating a device with a device
driver that can control it. Bus drivers have typically handled this
@@ -25,7 +26,7 @@ device_register
When a new device is added, the bus's list of drivers is iterated over
to find one that supports it. In order to determine that, the device
ID of the device must match one of the device IDs that the driver
-supports. The format and semantics for comparing IDs is bus-specific.
+supports. The format and semantics for comparing IDs is bus-specific.
Instead of trying to derive a complex state machine and matching
algorithm, it is up to the bus driver to provide a callback to compare
a device against the IDs of a driver. The bus returns 1 if a match was
@@ -36,14 +37,14 @@ int match(struct device * dev, struct device_driver * drv);
If a match is found, the device's driver field is set to the driver
and the driver's probe callback is called. This gives the driver a
chance to verify that it really does support the hardware, and that
-it's in a working state.
+it's in a working state.
Device Class
~~~~~~~~~~~~
Upon the successful completion of probe, the device is registered with
the class to which it belongs. Device drivers belong to one and only one
-class, and that is set in the driver's devclass field.
+class, and that is set in the driver's devclass field.
devclass_add_device is called to enumerate the device within the class
and actually register it with the class, which happens with the
class's register_dev callback.
@@ -53,7 +54,7 @@ Driver
~~~~~~
When a driver is attached to a device, the device is inserted into the
-driver's list of devices.
+driver's list of devices.
sysfs
@@ -67,18 +68,18 @@ to the device's directory in the physical hierarchy.
A directory for the device is created in the class's directory. A
symlink is created in that directory that points to the device's
-physical location in the sysfs tree.
+physical location in the sysfs tree.
A symlink can be created (though this isn't done yet) in the device's
physical directory to either its class directory, or the class's
top-level directory. One can also be created to point to its driver's
-directory also.
+directory also.
driver_register
~~~~~~~~~~~~~~~
-The process is almost identical for when a new driver is added.
+The process is almost identical for when a new driver is added.
The bus's list of devices is iterated over to find a match. Devices
that already have a driver are skipped. All the devices are iterated
over, to bind as many devices as possible to the driver.
@@ -94,5 +95,4 @@ of the driver is decremented. All symlinks between the two are removed.
When a driver is removed, the list of devices that it supports is
iterated over, and the driver's remove callback is called for each
-one. The device is removed from that list and the symlinks removed.
-
+one. The device is removed from that list and the symlinks removed.
diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.rst
similarity index 76%
rename from Documentation/driver-model/bus.txt
rename to Documentation/driver-model/bus.rst
index c247b488a567..016b15a6e8ea 100644
--- a/Documentation/driver-model/bus.txt
+++ b/Documentation/driver-model/bus.rst
@@ -1,5 +1,6 @@
-
-Bus Types
+=========
+Bus Types
+=========
Definition
~~~~~~~~~~
@@ -13,12 +14,12 @@ Declaration
Each bus type in the kernel (PCI, USB, etc) should declare one static
object of this type. They must initialize the name field, and may
-optionally initialize the match callback.
+optionally initialize the match callback::
-struct bus_type pci_bus_type = {
- .name = "pci",
- .match = pci_bus_match,
-};
+ struct bus_type pci_bus_type = {
+ .name = "pci",
+ .match = pci_bus_match,
+ };
The structure should be exported to drivers in a header file:
@@ -30,8 +31,8 @@ Registration
When a bus driver is initialized, it calls bus_register. This
initializes the rest of the fields in the bus object and inserts it
-into a global list of bus types. Once the bus object is registered,
-the fields in it are usable by the bus driver.
+into a global list of bus types. Once the bus object is registered,
+the fields in it are usable by the bus driver.
Callbacks
@@ -43,17 +44,17 @@ match(): Attaching Drivers to Devices
The format of device ID structures and the semantics for comparing
them are inherently bus-specific. Drivers typically declare an array
of device IDs of devices they support that reside in a bus-specific
-driver structure.
+driver structure.
The purpose of the match callback is to give the bus an opportunity to
determine if a particular driver supports a particular device by
comparing the device IDs the driver supports with the device ID of a
particular device, without sacrificing bus-specific functionality or
-type-safety.
+type-safety.
When a driver is registered with the bus, the bus's list of devices is
iterated over, and the match callback is called for each device that
-does not have a driver associated with it.
+does not have a driver associated with it.
@@ -64,22 +65,23 @@ The lists of devices and drivers are intended to replace the local
lists that many buses keep. They are lists of struct devices and
struct device_drivers, respectively. Bus drivers are free to use the
lists as they please, but conversion to the bus-specific type may be
-necessary.
+necessary.
-The LDM core provides helper functions for iterating over each list.
+The LDM core provides helper functions for iterating over each list::
-int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data,
- int (*fn)(struct device *, void *));
+ int bus_for_each_dev(struct bus_type * bus, struct device * start,
+ void * data,
+ int (*fn)(struct device *, void *));
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
- void * data, int (*fn)(struct device_driver *, void *));
+ int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+ void * data, int (*fn)(struct device_driver *, void *));
These helpers iterate over the respective list, and call the callback
for each device or driver in the list. All list accesses are
synchronized by taking the bus's lock (read currently). The reference
count on each object in the list is incremented before the callback is
called; it is decremented after the next object has been obtained. The
-lock is not held when calling the callback.
+lock is not held when calling the callback.
sysfs
@@ -87,14 +89,14 @@ sysfs
There is a top-level directory named 'bus'.
Each bus gets a directory in the bus directory, along with two default
-directories:
+directories::
/sys/bus/pci/
|-- devices
`-- drivers
Drivers registered with the bus get a directory in the bus's drivers
-directory:
+directory::
/sys/bus/pci/
|-- devices
@@ -106,7 +108,7 @@ directory:
Each device that is discovered on a bus of that type gets a symlink in
the bus's devices directory to the device's directory in the physical
-hierarchy:
+hierarchy::
/sys/bus/pci/
|-- devices
@@ -118,26 +120,27 @@ hierarchy:
Exporting Attributes
~~~~~~~~~~~~~~~~~~~~
-struct bus_attribute {
+
+::
+
+ struct bus_attribute {
struct attribute attr;
ssize_t (*show)(struct bus_type *, char * buf);
ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
-};
+ };
Bus drivers can export attributes using the BUS_ATTR_RW macro that works
similarly to the DEVICE_ATTR_RW macro for devices. For example, a
-definition like this:
+definition like this::
-static BUS_ATTR_RW(debug);
+ static BUS_ATTR_RW(debug);
-is equivalent to declaring:
+is equivalent to declaring::
-static bus_attribute bus_attr_debug;
+ static bus_attribute bus_attr_debug;
This can then be used to add and remove the attribute from the bus's
-sysfs directory using:
-
-int bus_create_file(struct bus_type *, struct bus_attribute *);
-void bus_remove_file(struct bus_type *, struct bus_attribute *);
-
+sysfs directory using::
+ int bus_create_file(struct bus_type *, struct bus_attribute *);
+ void bus_remove_file(struct bus_type *, struct bus_attribute *);
diff --git a/Documentation/driver-model/class.txt b/Documentation/driver-model/class.rst
similarity index 75%
rename from Documentation/driver-model/class.txt
rename to Documentation/driver-model/class.rst
index 1fefc480a80b..fff55b80e86a 100644
--- a/Documentation/driver-model/class.txt
+++ b/Documentation/driver-model/class.rst
@@ -1,6 +1,6 @@
-
+==============
Device Classes
-
+==============
Introduction
~~~~~~~~~~~~
@@ -13,37 +13,37 @@ device. The following device classes have been identified:
Each device class defines a set of semantics and a programming interface
that devices of that class adhere to. Device drivers are the
implementation of that programming interface for a particular device on
-a particular bus.
+a particular bus.
Device classes are agnostic with respect to what bus a device resides
-on.
+on.
Programming Interface
~~~~~~~~~~~~~~~~~~~~~
-The device class structure looks like:
+The device class structure looks like::
-typedef int (*devclass_add)(struct device *);
-typedef void (*devclass_remove)(struct device *);
+ typedef int (*devclass_add)(struct device *);
+ typedef void (*devclass_remove)(struct device *);
See the kerneldoc for the struct class.
-A typical device class definition would look like:
+A typical device class definition would look like::
-struct device_class input_devclass = {
+ struct device_class input_devclass = {
.name = "input",
.add_device = input_add_device,
.remove_device = input_remove_device,
-};
+ };
Each device class structure should be exported in a header file so it
can be used by drivers, extensions and interfaces.
-Device classes are registered and unregistered with the core using:
+Device classes are registered and unregistered with the core using::
-int devclass_register(struct device_class * cls);
-void devclass_unregister(struct device_class * cls);
+ int devclass_register(struct device_class * cls);
+ void devclass_unregister(struct device_class * cls);
Devices
@@ -52,16 +52,16 @@ As devices are bound to drivers, they are added to the device class
that the driver belongs to. Before the driver model core, this would
typically happen during the driver's probe() callback, once the device
has been initialized. It now happens after the probe() callback
-finishes from the core.
+finishes from the core.
The device is enumerated in the class. Each time a device is added to
the class, the class's devnum field is incremented and assigned to the
device. The field is never decremented, so if the device is removed
from the class and re-added, it will receive a different enumerated
-value.
+value.
The class is allowed to create a class-specific structure for the
-device and store it in the device's class_data pointer.
+device and store it in the device's class_data pointer.
There is no list of devices in the device class. Each driver has a
list of devices that it supports. The device class has a list of
@@ -73,15 +73,15 @@ Device Drivers
~~~~~~~~~~~~~~
Device drivers are added to device classes when they are registered
with the core. A driver specifies the class it belongs to by setting
-the struct device_driver::devclass field.
+the struct device_driver::devclass field.
sysfs directory structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is a top-level sysfs directory named 'class'.
+There is a top-level sysfs directory named 'class'.
Each class gets a directory in the class directory, along with two
-default subdirectories:
+default subdirectories::
class/
`-- input
@@ -89,8 +89,8 @@ default subdirectories:
`-- drivers
-Drivers registered with the class get a symlink in the drivers/ directory
-that points to the driver's directory (under its bus directory):
+Drivers registered with the class get a symlink in the drivers/ directory
+that points to the driver's directory (under its bus directory)::
class/
`-- input
@@ -99,8 +99,8 @@ that points to the driver's directory (under its bus directory):
`-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
-Each device gets a symlink in the devices/ directory that points to the
-device's directory in the physical hierarchy:
+Each device gets a symlink in the devices/ directory that points to the
+device's directory in the physical hierarchy::
class/
`-- input
@@ -111,37 +111,39 @@ device's directory in the physical hierarchy:
Exporting Attributes
~~~~~~~~~~~~~~~~~~~~
-struct devclass_attribute {
+
+::
+
+ struct devclass_attribute {
struct attribute attr;
ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
-};
+ };
Class drivers can export attributes using the DEVCLASS_ATTR macro that works
-similarly to the DEVICE_ATTR macro for devices. For example, a definition
-like this:
+similarly to the DEVICE_ATTR macro for devices. For example, a definition
+like this::
-static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
+ static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
-is equivalent to declaring:
+is equivalent to declaring::
-static devclass_attribute devclass_attr_debug;
+ static devclass_attribute devclass_attr_debug;
The bus driver can add and remove the attribute from the class's
-sysfs directory using:
+sysfs directory using::
-int devclass_create_file(struct device_class *, struct devclass_attribute *);
-void devclass_remove_file(struct device_class *, struct devclass_attribute *);
+ int devclass_create_file(struct device_class *, struct devclass_attribute *);
+ void devclass_remove_file(struct device_class *, struct devclass_attribute *);
In the example above, the file will be named 'debug' in placed in the
-class's directory in sysfs.
+class's directory in sysfs.
Interfaces
~~~~~~~~~~
There may exist multiple mechanisms for accessing the same device of a
-particular class type. Device interfaces describe these mechanisms.
+particular class type. Device interfaces describe these mechanisms.
When a device is added to a device class, the core attempts to add it
to every interface that is registered with the device class.
-
diff --git a/Documentation/driver-model/design-patterns.txt b/Documentation/driver-model/design-patterns.rst
similarity index 59%
rename from Documentation/driver-model/design-patterns.txt
rename to Documentation/driver-model/design-patterns.rst
index ba7b2df64904..41eb8f41f7dd 100644
--- a/Documentation/driver-model/design-patterns.txt
+++ b/Documentation/driver-model/design-patterns.rst
@@ -1,6 +1,6 @@
-
+=============================
Device Driver Design Patterns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================
This document describes a few common design patterns found in device drivers.
It is likely that subsystem maintainers will ask driver developers to
@@ -19,23 +19,23 @@ that the device the driver binds to will appear in several instances. This
means that the probe() function and all callbacks need to be reentrant.
The most common way to achieve this is to use the state container design
-pattern. It usually has this form:
+pattern. It usually has this form::
-struct foo {
- spinlock_t lock; /* Example member */
- (...)
-};
+ struct foo {
+ spinlock_t lock; /* Example member */
+ (...)
+ };
-static int foo_probe(...)
-{
- struct foo *foo;
+ static int foo_probe(...)
+ {
+ struct foo *foo;
- foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
- if (!foo)
- return -ENOMEM;
- spin_lock_init(&foo->lock);
- (...)
-}
+ foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
+ if (!foo)
+ return -ENOMEM;
+ spin_lock_init(&foo->lock);
+ (...)
+ }
This will create an instance of struct foo in memory every time probe() is
called. This is our state container for this instance of the device driver.
@@ -43,21 +43,21 @@ Of course it is then necessary to always pass this instance of the
state around to all functions that need access to the state and its members.
For example, if the driver is registering an interrupt handler, you would
-pass around a pointer to struct foo like this:
+pass around a pointer to struct foo like this::
-static irqreturn_t foo_handler(int irq, void *arg)
-{
- struct foo *foo = arg;
- (...)
-}
+ static irqreturn_t foo_handler(int irq, void *arg)
+ {
+ struct foo *foo = arg;
+ (...)
+ }
-static int foo_probe(...)
-{
- struct foo *foo;
+ static int foo_probe(...)
+ {
+ struct foo *foo;
- (...)
- ret = request_irq(irq, foo_handler, 0, "foo", foo);
-}
+ (...)
+ ret = request_irq(irq, foo_handler, 0, "foo", foo);
+ }
This way you always get a pointer back to the correct instance of foo in
your interrupt handler.
@@ -66,38 +66,38 @@ your interrupt handler.
2. container_of()
~~~~~~~~~~~~~~~~~
-Continuing on the above example we add an offloaded work:
+Continuing on the above example we add an offloaded work::
-struct foo {
- spinlock_t lock;
- struct workqueue_struct *wq;
- struct work_struct offload;
- (...)
-};
+ struct foo {
+ spinlock_t lock;
+ struct workqueue_struct *wq;
+ struct work_struct offload;
+ (...)
+ };
-static void foo_work(struct work_struct *work)
-{
- struct foo *foo = container_of(work, struct foo, offload);
+ static void foo_work(struct work_struct *work)
+ {
+ struct foo *foo = container_of(work, struct foo, offload);
- (...)
-}
+ (...)
+ }
-static irqreturn_t foo_handler(int irq, void *arg)
-{
- struct foo *foo = arg;
+ static irqreturn_t foo_handler(int irq, void *arg)
+ {
+ struct foo *foo = arg;
- queue_work(foo->wq, &foo->offload);
- (...)
-}
+ queue_work(foo->wq, &foo->offload);
+ (...)
+ }
-static int foo_probe(...)
-{
- struct foo *foo;
+ static int foo_probe(...)
+ {
+ struct foo *foo;
- foo->wq = create_singlethread_workqueue("foo-wq");
- INIT_WORK(&foo->offload, foo_work);
- (...)
-}
+ foo->wq = create_singlethread_workqueue("foo-wq");
+ INIT_WORK(&foo->offload, foo_work);
+ (...)
+ }
The design pattern is the same for an hrtimer or something similar that will
return a single argument which is a pointer to a struct member in the
diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.rst
similarity index 71%
rename from Documentation/driver-model/device.txt
rename to Documentation/driver-model/device.rst
index 2403eb856187..2b868d49d349 100644
--- a/Documentation/driver-model/device.txt
+++ b/Documentation/driver-model/device.rst
@@ -1,6 +1,6 @@
-
+==========================
The Basic Device Structure
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
See the kerneldoc for the struct device.
@@ -8,9 +8,9 @@ See the kerneldoc for the struct device.
Programming Interface
~~~~~~~~~~~~~~~~~~~~~
The bus driver that discovers the device uses this to register the
-device with the core:
+device with the core::
-int device_register(struct device * dev);
+ int device_register(struct device * dev);
The bus should initialize the following fields:
@@ -20,30 +20,33 @@ The bus should initialize the following fields:
- bus
A device is removed from the core when its reference count goes to
-0. The reference count can be adjusted using:
+0. The reference count can be adjusted using::
-struct device * get_device(struct device * dev);
-void put_device(struct device * dev);
+ struct device * get_device(struct device * dev);
+ void put_device(struct device * dev);
get_device() will return a pointer to the struct device passed to it
if the reference is not already 0 (if it's in the process of being
removed already).
-A driver can access the lock in the device structure using:
+A driver can access the lock in the device structure using::
-void lock_device(struct device * dev);
-void unlock_device(struct device * dev);
+ void lock_device(struct device * dev);
+ void unlock_device(struct device * dev);
Attributes
~~~~~~~~~~
-struct device_attribute {
+
+::
+
+ struct device_attribute {
struct attribute attr;
ssize_t (*show)(struct device *dev, struct device_attribute *attr,
char *buf);
ssize_t (*store)(struct device *dev, struct device_attribute *attr,
const char *buf, size_t count);
-};
+ };
Attributes of devices can be exported by a device driver through sysfs.
@@ -54,39 +57,39 @@ As explained in Documentation/kobject.txt, device attributes must be
created before the KOBJ_ADD uevent is generated. The only way to realize
that is by defining an attribute group.
-Attributes are declared using a macro called DEVICE_ATTR:
+Attributes are declared using a macro called DEVICE_ATTR::
-#define DEVICE_ATTR(name,mode,show,store)
+ #define DEVICE_ATTR(name,mode,show,store)
-Example:
+Example:::
-static DEVICE_ATTR(type, 0444, show_type, NULL);
-static DEVICE_ATTR(power, 0644, show_power, store_power);
+ static DEVICE_ATTR(type, 0444, show_type, NULL);
+ static DEVICE_ATTR(power, 0644, show_power, store_power);
This declares two structures of type struct device_attribute with respective
names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be
-organized as follows into a group:
+organized as follows into a group::
-static struct attribute *dev_attrs[] = {
+ static struct attribute *dev_attrs[] = {
&dev_attr_type.attr,
&dev_attr_power.attr,
NULL,
-};
+ };
-static struct attribute_group dev_attr_group = {
+ static struct attribute_group dev_attr_group = {
.attrs = dev_attrs,
-};
+ };
-static const struct attribute_group *dev_attr_groups[] = {
+ static const struct attribute_group *dev_attr_groups[] = {
&dev_attr_group,
NULL,
-};
+ };
This array of groups can then be associated with a device by setting the
-group pointer in struct device before device_register() is invoked:
+group pointer in struct device before device_register() is invoked::
- dev->groups = dev_attr_groups;
- device_register(dev);
+ dev->groups = dev_attr_groups;
+ device_register(dev);
The device_register() function will use the 'groups' pointer to create the
device attributes and the device_unregister() function will use this pointer
diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.rst
similarity index 93%
rename from Documentation/driver-model/devres.txt
rename to Documentation/driver-model/devres.rst
index 69c7fa7f616c..4ac99122b5f1 100644
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.rst
@@ -1,3 +1,4 @@
+================================
Devres - Managed Device Resource
================================
@@ -5,17 +6,18 @@ Tejun Heo <teheo@suse.de>
First draft 10 January 2007
+.. contents
-1. Intro : Huh? Devres?
-2. Devres : Devres in a nutshell
-3. Devres Group : Group devres'es and release them together
-4. Details : Life time rules, calling context, ...
-5. Overhead : How much do we have to pay for this?
-6. List of managed interfaces : Currently implemented managed interfaces
+ 1. Intro : Huh? Devres?
+ 2. Devres : Devres in a nutshell
+ 3. Devres Group : Group devres'es and release them together
+ 4. Details : Life time rules, calling context, ...
+ 5. Overhead : How much do we have to pay for this?
+ 6. List of managed interfaces: Currently implemented managed interfaces
- 1. Intro
- --------
+1. Intro
+--------
devres came up while trying to convert libata to use iomap. Each
iomapped address should be kept and unmapped on driver detach. For
@@ -42,8 +44,8 @@ would leak resources or even cause oops when failure occurs. iomap
adds more to this mix. So do msi and msix.
- 2. Devres
- ---------
+2. Devres
+---------
devres is basically linked list of arbitrarily sized memory areas
associated with a struct device. Each devres entry is associated with
@@ -58,7 +60,7 @@ using dma_alloc_coherent(). The managed version is called
dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except
for the DMA memory allocated using it is managed and will be
automatically released on driver detach. Implementation looks like
-the following.
+the following::
struct dma_devres {
size_t size;
@@ -98,7 +100,7 @@ If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
freed whether initialization fails half-way or the device gets
detached. If most resources are acquired using managed interface, a
driver can have much simpler init and exit code. Init path basically
-looks like the following.
+looks like the following::
my_init_one()
{
@@ -119,7 +121,7 @@ looks like the following.
return register_to_upper_layer(d);
}
-And exit path,
+And exit path::
my_remove_one()
{
@@ -140,13 +142,13 @@ on you. In some cases this may mean introducing checks that were not
necessary before moving to the managed devm_* calls.
- 3. Devres group
- ---------------
+3. Devres group
+---------------
Devres entries can be grouped using devres group. When a group is
released, all contained normal devres entries and properly nested
groups are released. One usage is to rollback series of acquired
-resources on failure. For example,
+resources on failure. For example::
if (!devres_open_group(dev, NULL, GFP_KERNEL))
return -ENOMEM;
@@ -172,7 +174,7 @@ like above are usually useful in midlayer driver (e.g. libata core
layer) where interface function shouldn't have side effect on failure.
For LLDs, just returning error code suffices in most cases.
-Each group is identified by void *id. It can either be explicitly
+Each group is identified by `void *id`. It can either be explicitly
specified by @id argument to devres_open_group() or automatically
created by passing NULL as @id as in the above example. In both
cases, devres_open_group() returns the group's id. The returned id
@@ -180,7 +182,7 @@ can be passed to other devres functions to select the target group.
If NULL is given to those functions, the latest open group is
selected.
-For example, you can do something like the following.
+For example, you can do something like the following::
int my_midlayer_create_something()
{
@@ -199,8 +201,8 @@ For example, you can do something like the following.
}
- 4. Details
- ----------
+4. Details
+----------
Lifetime of a devres entry begins on devres allocation and finishes
when it is released or destroyed (removed and freed) - no reference
@@ -220,8 +222,8 @@ All devres interface functions can be called without context if the
right gfp mask is given.
- 5. Overhead
- -----------
+5. Overhead
+-----------
Each devres bookkeeping info is allocated together with requested data
area. With debug option turned off, bookkeeping info occupies 16
@@ -237,8 +239,8 @@ and 400 bytes on 32bit machine after naive conversion (we can
certainly invest a bit more effort into libata core layer).
- 6. List of managed interfaces
- -----------------------------
+6. List of managed interfaces
+-----------------------------
CLOCK
devm_clk_get()
diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.rst
similarity index 75%
rename from Documentation/driver-model/driver.txt
rename to Documentation/driver-model/driver.rst
index d661e6f7e6a0..11d281506a04 100644
--- a/Documentation/driver-model/driver.txt
+++ b/Documentation/driver-model/driver.rst
@@ -1,5 +1,6 @@
-
+==============
Device Drivers
+==============
See the kerneldoc for the struct device_driver.
@@ -26,50 +27,50 @@ Declaration
As stated above, struct device_driver objects are statically
allocated. Below is an example declaration of the eepro100
driver. This declaration is hypothetical only; it relies on the driver
-being converted completely to the new model.
+being converted completely to the new model::
-static struct device_driver eepro100_driver = {
- .name = "eepro100",
- .bus = &pci_bus_type,
-
- .probe = eepro100_probe,
- .remove = eepro100_remove,
- .suspend = eepro100_suspend,
- .resume = eepro100_resume,
-};
+ static struct device_driver eepro100_driver = {
+ .name = "eepro100",
+ .bus = &pci_bus_type,
+
+ .probe = eepro100_probe,
+ .remove = eepro100_remove,
+ .suspend = eepro100_suspend,
+ .resume = eepro100_resume,
+ };
Most drivers will not be able to be converted completely to the new
model because the bus they belong to has a bus-specific structure with
-bus-specific fields that cannot be generalized.
+bus-specific fields that cannot be generalized.
The most common example of this are device ID structures. A driver
typically defines an array of device IDs that it supports. The format
of these structures and the semantics for comparing device IDs are
completely bus-specific. Defining them as bus-specific entities would
-sacrifice type-safety, so we keep bus-specific structures around.
+sacrifice type-safety, so we keep bus-specific structures around.
Bus-specific drivers should include a generic struct device_driver in
-the definition of the bus-specific driver. Like this:
+the definition of the bus-specific driver. Like this::
-struct pci_driver {
- const struct pci_device_id *id_table;
- struct device_driver driver;
-};
+ struct pci_driver {
+ const struct pci_device_id *id_table;
+ struct device_driver driver;
+ };
A definition that included bus-specific fields would look like
-(using the eepro100 driver again):
+(using the eepro100 driver again)::
-static struct pci_driver eepro100_driver = {
- .id_table = eepro100_pci_tbl,
- .driver = {
+ static struct pci_driver eepro100_driver = {
+ .id_table = eepro100_pci_tbl,
+ .driver = {
.name = "eepro100",
.bus = &pci_bus_type,
.probe = eepro100_probe,
.remove = eepro100_remove,
.suspend = eepro100_suspend,
.resume = eepro100_resume,
- },
-};
+ },
+ };
Some may find the syntax of embedded struct initialization awkward or
even a bit ugly. So far, it's the best way we've found to do what we want...
@@ -77,12 +78,14 @@ even a bit ugly. So far, it's the best way we've found to do what we want...
Registration
~~~~~~~~~~~~
-int driver_register(struct device_driver * drv);
+::
+
+ int driver_register(struct device_driver *drv);
The driver registers the structure on startup. For drivers that have
no bus-specific fields (i.e. don't have a bus-specific driver
structure), they would use driver_register and pass a pointer to their
-struct device_driver object.
+struct device_driver object.
Most drivers, however, will have a bus-specific structure and will
need to register with the bus using something like pci_driver_register.
@@ -101,7 +104,7 @@ By defining wrapper functions, the transition to the new model can be
made easier. Drivers can ignore the generic structure altogether and
let the bus wrapper fill in the fields. For the callbacks, the bus can
define generic callbacks that forward the call to the bus-specific
-callbacks of the drivers.
+callbacks of the drivers.
This solution is intended to be only temporary. In order to get class
information in the driver, the drivers must be modified anyway. Since
@@ -113,16 +116,16 @@ Access
~~~~~~
Once the object has been registered, it may access the common fields of
-the object, like the lock and the list of devices.
+the object, like the lock and the list of devices::
-int driver_for_each_dev(struct device_driver * drv, void * data,
- int (*callback)(struct device * dev, void * data));
+ int driver_for_each_dev(struct device_driver *drv, void *data,
+ int (*callback)(struct device *dev, void *data));
The devices field is a list of all the devices that have been bound to
the driver. The LDM core provides a helper function to operate on all
the devices a driver controls. This helper locks the driver on each
node access, and does proper reference counting on each device as it
-accesses it.
+accesses it.
sysfs
@@ -142,7 +145,9 @@ supports.
Callbacks
~~~~~~~~~
- int (*probe) (struct device * dev);
+::
+
+ int (*probe) (struct device *dev);
The probe() entry is called in task context, with the bus's rwsem locked
and the driver partially bound to the device. Drivers commonly use
@@ -162,9 +167,9 @@ the driver to that device.
A driver's probe() may return a negative errno value to indicate that
the driver did not bind to this device, in which case it should have
-released all resources it allocated.
+released all resources it allocated::
- int (*remove) (struct device * dev);
+ int (*remove) (struct device *dev);
remove is called to unbind a driver from a device. This may be
called if a device is physically removed from the system, if the
@@ -173,43 +178,46 @@ in other cases.
It is up to the driver to determine if the device is present or
not. It should free any resources allocated specifically for the
-device; i.e. anything in the device's driver_data field.
+device; i.e. anything in the device's driver_data field.
If the device is still present, it should quiesce the device and place
-it into a supported low-power state.
+it into a supported low-power state::
- int (*suspend) (struct device * dev, pm_message_t state);
+ int (*suspend) (struct device *dev, pm_message_t state);
-suspend is called to put the device in a low power state.
+suspend is called to put the device in a low power state::
- int (*resume) (struct device * dev);
+ int (*resume) (struct device *dev);
Resume is used to bring a device back from a low power state.
Attributes
~~~~~~~~~~
-struct driver_attribute {
- struct attribute attr;
- ssize_t (*show)(struct device_driver *driver, char *buf);
- ssize_t (*store)(struct device_driver *, const char * buf, size_t count);
-};
-Device drivers can export attributes via their sysfs directories.
+::
+
+ struct driver_attribute {
+ struct attribute attr;
+ ssize_t (*show)(struct device_driver *driver, char *buf);
+ ssize_t (*store)(struct device_driver *, const char *buf, size_t count);
+ };
+
+Device drivers can export attributes via their sysfs directories.
Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO
macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO
macros.
-Example:
+Example::
-DRIVER_ATTR_RW(debug);
+ DRIVER_ATTR_RW(debug);
-This is equivalent to declaring:
+This is equivalent to declaring::
-struct driver_attribute driver_attr_debug;
+ struct driver_attribute driver_attr_debug;
This can then be used to add and remove the attribute from the
-driver's directory using:
+driver's directory using::
-int driver_create_file(struct device_driver *, const struct driver_attribute *);
-void driver_remove_file(struct device_driver *, const struct driver_attribute *);
+ int driver_create_file(struct device_driver *, const struct driver_attribute *);
+ void driver_remove_file(struct device_driver *, const struct driver_attribute *);
diff --git a/Documentation/driver-model/index.rst b/Documentation/driver-model/index.rst
new file mode 100644
index 000000000000..9f85d579ce56
--- /dev/null
+++ b/Documentation/driver-model/index.rst
@@ -0,0 +1,26 @@
+:orphan:
+
+============
+Driver Model
+============
+
+.. toctree::
+ :maxdepth: 1
+
+ binding
+ bus
+ class
+ design-patterns
+ device
+ devres
+ driver
+ overview
+ platform
+ porting
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/driver-model/overview.txt b/Documentation/driver-model/overview.rst
similarity index 90%
rename from Documentation/driver-model/overview.txt
rename to Documentation/driver-model/overview.rst
index 6a8f9a8075d8..d4d1e9b40e0c 100644
--- a/Documentation/driver-model/overview.txt
+++ b/Documentation/driver-model/overview.rst
@@ -1,4 +1,6 @@
+=============================
The Linux Kernel Device Model
+=============================
Patrick Mochel <mochel@digitalimplant.org>
@@ -41,14 +43,14 @@ data structure. These fields must still be accessed by the bus layers,
and sometimes by the device-specific drivers.
Other bus layers are encouraged to do what has been done for the PCI layer.
-struct pci_dev now looks like this:
+struct pci_dev now looks like this::
-struct pci_dev {
+ struct pci_dev {
...
struct device dev; /* Generic device interface */
...
-};
+ };
Note first that the struct device dev within the struct pci_dev is
statically allocated. This means only one allocation on device discovery.
@@ -80,26 +82,26 @@ easy. This has been accomplished by implementing a special purpose virtual
file system named sysfs.
Almost all mainstream Linux distros mount this filesystem automatically; you
-can see some variation of the following in the output of the "mount" command:
+can see some variation of the following in the output of the "mount" command::
-$ mount
-...
-none on /sys type sysfs (rw,noexec,nosuid,nodev)
-...
-$
+ $ mount
+ ...
+ none on /sys type sysfs (rw,noexec,nosuid,nodev)
+ ...
+ $
The auto-mounting of sysfs is typically accomplished by an entry similar to
-the following in the /etc/fstab file:
+the following in the /etc/fstab file::
-none /sys sysfs defaults 0 0
+ none /sys sysfs defaults 0 0
-or something similar in the /lib/init/fstab file on Debian-based systems:
+or something similar in the /lib/init/fstab file on Debian-based systems::
-none /sys sysfs nodev,noexec,nosuid 0 0
+ none /sys sysfs nodev,noexec,nosuid 0 0
-If sysfs is not automatically mounted, you can always do it manually with:
+If sysfs is not automatically mounted, you can always do it manually with::
-# mount -t sysfs sysfs /sys
+ # mount -t sysfs sysfs /sys
Whenever a device is inserted into the tree, a directory is created for it.
This directory may be populated at each layer of discovery - the global layer,
@@ -108,7 +110,7 @@ the bus layer, or the device layer.
The global layer currently creates two files - 'name' and 'power'. The
former only reports the name of the device. The latter reports the
current power state of the device. It will also be used to set the current
-power state.
+power state.
The bus layer may also create files for the devices it finds while probing the
bus. For example, the PCI layer currently creates 'irq' and 'resource' files
@@ -118,6 +120,5 @@ A device-specific driver may also export files in its directory to expose
device-specific data or tunable interfaces.
More information about the sysfs directory layout can be found in
-the other documents in this directory and in the file
+the other documents in this directory and in the file
Documentation/filesystems/sysfs.txt.
-
diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.rst
similarity index 95%
rename from Documentation/driver-model/platform.txt
rename to Documentation/driver-model/platform.rst
index 9d9e47dfc013..334dd4071ae4 100644
--- a/Documentation/driver-model/platform.txt
+++ b/Documentation/driver-model/platform.rst
@@ -1,5 +1,7 @@
+============================
Platform Devices and Drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
+
See <linux/platform_device.h> for the driver model interface to the
platform bus: platform_device, and platform_driver. This pseudo-bus
is used to connect devices on busses with minimal infrastructure,
@@ -19,15 +21,15 @@ be connected through a segment of some other kind of bus; but its
registers will still be directly addressable.
Platform devices are given a name, used in driver binding, and a
-list of resources such as addresses and IRQs.
+list of resources such as addresses and IRQs::
-struct platform_device {
+ struct platform_device {
const char *name;
u32 id;
struct device dev;
u32 num_resources;
struct resource *resource;
-};
+ };
Platform drivers
@@ -35,9 +37,9 @@ Platform drivers
Platform drivers follow the standard driver model convention, where
discovery/enumeration is handled outside the drivers, and drivers
provide probe() and remove() methods. They support power management
-and shutdown notifications using the standard conventions.
+and shutdown notifications using the standard conventions::
-struct platform_driver {
+ struct platform_driver {
int (*probe)(struct platform_device *);
int (*remove)(struct platform_device *);
void (*shutdown)(struct platform_device *);
@@ -46,25 +48,25 @@ struct platform_driver {
int (*resume_early)(struct platform_device *);
int (*resume)(struct platform_device *);
struct device_driver driver;
-};
+ };
Note that probe() should in general verify that the specified device hardware
actually exists; sometimes platform setup code can't be sure. The probing
can use device resources, including clocks, and device platform_data.
-Platform drivers register themselves the normal way:
+Platform drivers register themselves the normal way::
int platform_driver_register(struct platform_driver *drv);
Or, in common situations where the device is known not to be hot-pluggable,
the probe() routine can live in an init section to reduce the driver's
-runtime memory footprint:
+runtime memory footprint::
int platform_driver_probe(struct platform_driver *drv,
int (*probe)(struct platform_device *))
Kernel modules can be composed of several platform drivers. The platform core
-provides helpers to register and unregister an array of drivers:
+provides helpers to register and unregister an array of drivers::
int __platform_register_drivers(struct platform_driver * const *drivers,
unsigned int count, struct module *owner);
@@ -73,7 +75,7 @@ provides helpers to register and unregister an array of drivers:
If one of the drivers fails to register, all drivers registered up to that
point will be unregistered in reverse order. Note that there is a convenience
-macro that passes THIS_MODULE as owner parameter:
+macro that passes THIS_MODULE as owner parameter::
#define platform_register_drivers(drivers, count)
@@ -81,7 +83,7 @@ macro that passes THIS_MODULE as owner parameter:
Device Enumeration
~~~~~~~~~~~~~~~~~~
As a rule, platform specific (and often board-specific) setup code will
-register platform devices:
+register platform devices::
int platform_device_register(struct platform_device *pdev);
@@ -133,14 +135,14 @@ tend to already have "normal" modes, such as ones using device nodes that
were created by PNP or by platform device setup.
None the less, there are some APIs to support such legacy drivers. Avoid
-using these calls except with such hotplug-deficient drivers.
+using these calls except with such hotplug-deficient drivers::
struct platform_device *platform_device_alloc(
const char *name, int id);
You can use platform_device_alloc() to dynamically allocate a device, which
you will then initialize with resources and platform_device_register().
-A better solution is usually:
+A better solution is usually::
struct platform_device *platform_device_register_simple(
const char *name, int id,
diff --git a/Documentation/driver-model/porting.txt b/Documentation/driver-model/porting.rst
similarity index 62%
rename from Documentation/driver-model/porting.txt
rename to Documentation/driver-model/porting.rst
index 453053f1661f..ae4bf843c1d6 100644
--- a/Documentation/driver-model/porting.txt
+++ b/Documentation/driver-model/porting.rst
@@ -1,5 +1,6 @@
-
+=======================================
Porting Drivers to the New Driver Model
+=======================================
Patrick Mochel
@@ -8,8 +9,8 @@ Patrick Mochel
Overview
-Please refer to Documentation/driver-model/*.txt for definitions of
-various driver types and concepts.
+Please refer to `Documentation/driver-model/*.rst` for definitions of
+various driver types and concepts.
Most of the work of porting devices drivers to the new model happens
at the bus driver layer. This was intentional, to minimize the
@@ -18,11 +19,11 @@ of bus drivers.
In a nutshell, the driver model consists of a set of objects that can
be embedded in larger, bus-specific objects. Fields in these generic
-objects can replace fields in the bus-specific objects.
+objects can replace fields in the bus-specific objects.
The generic objects must be registered with the driver model core. By
doing so, they will exported via the sysfs filesystem. sysfs can be
-mounted by doing
+mounted by doing::
# mount -t sysfs sysfs /sys
@@ -30,108 +31,109 @@ mounted by doing
The Process
-Step 0: Read include/linux/device.h for object and function definitions.
+Step 0: Read include/linux/device.h for object and function definitions.
-Step 1: Registering the bus driver.
+Step 1: Registering the bus driver.
-- Define a struct bus_type for the bus driver.
+- Define a struct bus_type for the bus driver::
-struct bus_type pci_bus_type = {
- .name = "pci",
-};
+ struct bus_type pci_bus_type = {
+ .name = "pci",
+ };
- Register the bus type.
+
This should be done in the initialization function for the bus type,
- which is usually the module_init(), or equivalent, function.
+ which is usually the module_init(), or equivalent, function::
-static int __init pci_driver_init(void)
-{
- return bus_register(&pci_bus_type);
-}
+ static int __init pci_driver_init(void)
+ {
+ return bus_register(&pci_bus_type);
+ }
-subsys_initcall(pci_driver_init);
+ subsys_initcall(pci_driver_init);
The bus type may be unregistered (if the bus driver may be compiled
- as a module) by doing:
+ as a module) by doing::
bus_unregister(&pci_bus_type);
-- Export the bus type for others to use.
+- Export the bus type for others to use.
- Other code may wish to reference the bus type, so declare it in a
+ Other code may wish to reference the bus type, so declare it in a
shared header file and export the symbol.
-From include/linux/pci.h:
+From include/linux/pci.h::
-extern struct bus_type pci_bus_type;
+ extern struct bus_type pci_bus_type;
-From file the above code appears in:
+From file the above code appears in::
-EXPORT_SYMBOL(pci_bus_type);
+ EXPORT_SYMBOL(pci_bus_type);
- This will cause the bus to show up in /sys/bus/pci/ with two
- subdirectories: 'devices' and 'drivers'.
+ subdirectories: 'devices' and 'drivers'::
-# tree -d /sys/bus/pci/
-/sys/bus/pci/
-|-- devices
-`-- drivers
+ # tree -d /sys/bus/pci/
+ /sys/bus/pci/
+ |-- devices
+ `-- drivers
-Step 2: Registering Devices.
+Step 2: Registering Devices.
struct device represents a single device. It mainly contains metadata
-describing the relationship the device has to other entities.
+describing the relationship the device has to other entities.
-- Embed a struct device in the bus-specific device type.
+- Embed a struct device in the bus-specific device type::
-struct pci_dev {
- ...
- struct device dev; /* Generic device interface */
- ...
-};
+ struct pci_dev {
+ ...
+ struct device dev; /* Generic device interface */
+ ...
+ };
- It is recommended that the generic device not be the first item in
+ It is recommended that the generic device not be the first item in
the struct to discourage programmers from doing mindless casts
between the object types. Instead macros, or inline functions,
- should be created to convert from the generic object type.
+ should be created to convert from the generic object type::
-#define to_pci_dev(n) container_of(n, struct pci_dev, dev)
+ #define to_pci_dev(n) container_of(n, struct pci_dev, dev)
-or
+ or
-static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
-{
+ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
+ {
return container_of(n, struct pci_dev, dev);
-}
+ }
- This allows the compiler to verify type-safety of the operations
+ This allows the compiler to verify type-safety of the operations
that are performed (which is Good).
- Initialize the device on registration.
- When devices are discovered or registered with the bus type, the
+ When devices are discovered or registered with the bus type, the
bus driver should initialize the generic device. The most important
things to initialize are the bus_id, parent, and bus fields.
The bus_id is an ASCII string that contains the device's address on
the bus. The format of this string is bus-specific. This is
- necessary for representing devices in sysfs.
+ necessary for representing devices in sysfs.
parent is the physical parent of the device. It is important that
- the bus driver sets this field correctly.
+ the bus driver sets this field correctly.
The driver model maintains an ordered list of devices that it uses
for power management. This list must be in order to guarantee that
@@ -140,13 +142,13 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
devices.
Also, the location of the device's sysfs directory depends on a
- device's parent. sysfs exports a directory structure that mirrors
+ device's parent. sysfs exports a directory structure that mirrors
the device hierarchy. Accurately setting the parent guarantees that
sysfs will accurately represent the hierarchy.
The device's bus field is a pointer to the bus type the device
belongs to. This should be set to the bus_type that was declared
- and initialized before.
+ and initialized before.
Optionally, the bus driver may set the device's name and release
fields.
@@ -155,107 +157,107 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
"ATI Technologies Inc Radeon QD"
- The release field is a callback that the driver model core calls
- when the device has been removed, and all references to it have
+ The release field is a callback that the driver model core calls
+ when the device has been removed, and all references to it have
been released. More on this in a moment.
-- Register the device.
+- Register the device.
Once the generic device has been initialized, it can be registered
- with the driver model core by doing:
+ with the driver model core by doing::
device_register(&dev->dev);
- It can later be unregistered by doing:
+ It can later be unregistered by doing::
device_unregister(&dev->dev);
- This should happen on buses that support hotpluggable devices.
+ This should happen on buses that support hotpluggable devices.
If a bus driver unregisters a device, it should not immediately free
- it. It should instead wait for the driver model core to call the
- device's release method, then free the bus-specific object.
+ it. It should instead wait for the driver model core to call the
+ device's release method, then free the bus-specific object.
(There may be other code that is currently referencing the device
- structure, and it would be rude to free the device while that is
+ structure, and it would be rude to free the device while that is
happening).
- When the device is registered, a directory in sysfs is created.
- The PCI tree in sysfs looks like:
+ When the device is registered, a directory in sysfs is created.
+ The PCI tree in sysfs looks like::
-/sys/devices/pci0/
-|-- 00:00.0
-|-- 00:01.0
-| `-- 01:00.0
-|-- 00:02.0
-| `-- 02:1f.0
-| `-- 03:00.0
-|-- 00:1e.0
-| `-- 04:04.0
-|-- 00:1f.0
-|-- 00:1f.1
-| |-- ide0
-| | |-- 0.0
-| | `-- 0.1
-| `-- ide1
-| `-- 1.0
-|-- 00:1f.2
-|-- 00:1f.3
-`-- 00:1f.5
+ /sys/devices/pci0/
+ |-- 00:00.0
+ |-- 00:01.0
+ | `-- 01:00.0
+ |-- 00:02.0
+ | `-- 02:1f.0
+ | `-- 03:00.0
+ |-- 00:1e.0
+ | `-- 04:04.0
+ |-- 00:1f.0
+ |-- 00:1f.1
+ | |-- ide0
+ | | |-- 0.0
+ | | `-- 0.1
+ | `-- ide1
+ | `-- 1.0
+ |-- 00:1f.2
+ |-- 00:1f.3
+ `-- 00:1f.5
Also, symlinks are created in the bus's 'devices' directory
- that point to the device's directory in the physical hierarchy.
+ that point to the device's directory in the physical hierarchy::
-/sys/bus/pci/devices/
-|-- 00:00.0 -> ../../../devices/pci0/00:00.0
-|-- 00:01.0 -> ../../../devices/pci0/00:01.0
-|-- 00:02.0 -> ../../../devices/pci0/00:02.0
-|-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
-|-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
-|-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
-|-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
-|-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
-|-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
-|-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
-|-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
-|-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
-`-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
+ /sys/bus/pci/devices/
+ |-- 00:00.0 -> ../../../devices/pci0/00:00.0
+ |-- 00:01.0 -> ../../../devices/pci0/00:01.0
+ |-- 00:02.0 -> ../../../devices/pci0/00:02.0
+ |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
+ |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
+ |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
+ |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
+ |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
+ |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
+ |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
+ |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
+ |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
+ `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
Step 3: Registering Drivers.
struct device_driver is a simple driver structure that contains a set
-of operations that the driver model core may call.
+of operations that the driver model core may call.
-- Embed a struct device_driver in the bus-specific driver.
+- Embed a struct device_driver in the bus-specific driver.
- Just like with devices, do something like:
+ Just like with devices, do something like::
-struct pci_driver {
- ...
- struct device_driver driver;
-};
+ struct pci_driver {
+ ...
+ struct device_driver driver;
+ };
-- Initialize the generic driver structure.
+- Initialize the generic driver structure.
When the driver registers with the bus (e.g. doing pci_register_driver()),
initialize the necessary fields of the driver: the name and bus
- fields.
+ fields.
- Register the driver.
- After the generic driver has been initialized, call
+ After the generic driver has been initialized, call::
driver_register(&drv->driver);
to register the driver with the core.
When the driver is unregistered from the bus, unregister it from the
- core by doing:
+ core by doing::
driver_unregister(&drv->driver);
@@ -265,15 +267,15 @@ struct pci_driver {
- Sysfs representation.
- Drivers are exported via sysfs in their bus's 'driver's directory.
- For example:
+ Drivers are exported via sysfs in their bus's 'driver's directory.
+ For example::
-/sys/bus/pci/drivers/
-|-- 3c59x
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-|-- e100
-`-- serial
+ /sys/bus/pci/drivers/
+ |-- 3c59x
+ |-- Ensoniq AudioPCI
+ |-- agpgart-amdk7
+ |-- e100
+ `-- serial
Step 4: Define Generic Methods for Drivers.
@@ -281,30 +283,30 @@ Step 4: Define Generic Methods for Drivers.
struct device_driver defines a set of operations that the driver model
core calls. Most of these operations are probably similar to
operations the bus already defines for drivers, but taking different
-parameters.
+parameters.
It would be difficult and tedious to force every driver on a bus to
simultaneously convert their drivers to generic format. Instead, the
bus driver should define single instances of the generic methods that
-forward call to the bus-specific drivers. For instance:
+forward call to the bus-specific drivers. For instance::
-static int pci_device_remove(struct device * dev)
-{
- struct pci_dev * pci_dev = to_pci_dev(dev);
- struct pci_driver * drv = pci_dev->driver;
+ static int pci_device_remove(struct device * dev)
+ {
+ struct pci_dev * pci_dev = to_pci_dev(dev);
+ struct pci_driver * drv = pci_dev->driver;
- if (drv) {
- if (drv->remove)
- drv->remove(pci_dev);
- pci_dev->driver = NULL;
- }
- return 0;
-}
+ if (drv) {
+ if (drv->remove)
+ drv->remove(pci_dev);
+ pci_dev->driver = NULL;
+ }
+ return 0;
+ }
The generic driver should be initialized with these methods before it
-is registered.
+is registered::
/* initialize common driver fields */
drv->driver.name = drv->name;
@@ -320,23 +322,23 @@ is registered.
Ideally, the bus should only initialize the fields if they are not
already set. This allows the drivers to implement their own generic
-methods.
+methods.
-Step 5: Support generic driver binding.
+Step 5: Support generic driver binding.
The model assumes that a device or driver can be dynamically
registered with the bus at any time. When registration happens,
devices must be bound to a driver, or drivers must be bound to all
-devices that it supports.
+devices that it supports.
A driver typically contains a list of device IDs that it supports. The
-bus driver compares these IDs to the IDs of devices registered with it.
+bus driver compares these IDs to the IDs of devices registered with it.
The format of the device IDs, and the semantics for comparing them are
-bus-specific, so the generic model does attempt to generalize them.
+bus-specific, so the generic model does attempt to generalize them.
Instead, a bus may supply a method in struct bus_type that does the
-comparison:
+comparison::
int (*match)(struct device * dev, struct device_driver * drv);
@@ -346,59 +348,59 @@ and zero otherwise. It may also return error code (for example
not possible.
When a device is registered, the bus's list of drivers is iterated
-over. bus->match() is called for each one until a match is found.
+over. bus->match() is called for each one until a match is found.
When a driver is registered, the bus's list of devices is iterated
over. bus->match() is called for each device that is not already
-claimed by a driver.
+claimed by a driver.
When a device is successfully bound to a driver, device->driver is
set, the device is added to a per-driver list of devices, and a
symlink is created in the driver's sysfs directory that points to the
-device's physical directory:
+device's physical directory::
-/sys/bus/pci/drivers/
-|-- 3c59x
-| `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-| `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
-|-- e100
-| `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
-`-- serial
+ /sys/bus/pci/drivers/
+ |-- 3c59x
+ | `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
+ |-- Ensoniq AudioPCI
+ |-- agpgart-amdk7
+ | `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
+ |-- e100
+ | `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
+ `-- serial
This driver binding should replace the existing driver binding
-mechanism the bus currently uses.
+mechanism the bus currently uses.
Step 6: Supply a hotplug callback.
Whenever a device is registered with the driver model core, the
-userspace program /sbin/hotplug is called to notify userspace.
+userspace program /sbin/hotplug is called to notify userspace.
Users can define actions to perform when a device is inserted or
-removed.
+removed.
The driver model core passes several arguments to userspace via
environment variables, including
- ACTION: set to 'add' or 'remove'
-- DEVPATH: set to the device's physical path in sysfs.
+- DEVPATH: set to the device's physical path in sysfs.
A bus driver may also supply additional parameters for userspace to
consume. To do this, a bus must implement the 'hotplug' method in
-struct bus_type:
+struct bus_type::
- int (*hotplug) (struct device *dev, char **envp,
+ int (*hotplug) (struct device *dev, char **envp,
int num_envp, char *buffer, int buffer_size);
-This is called immediately before /sbin/hotplug is executed.
+This is called immediately before /sbin/hotplug is executed.
Step 7: Cleaning up the bus driver.
The generic bus, device, and driver structures provide several fields
-that can replace those defined privately to the bus driver.
+that can replace those defined privately to the bus driver.
- Device list.
@@ -407,36 +409,36 @@ type. This includes all devices on all instances of that bus type.
An internal list that the bus uses may be removed, in favor of using
this one.
-The core provides an iterator to access these devices.
+The core provides an iterator to access these devices::
-int bus_for_each_dev(struct bus_type * bus, struct device * start,
- void * data, int (*fn)(struct device *, void *));
+ int bus_for_each_dev(struct bus_type * bus, struct device * start,
+ void * data, int (*fn)(struct device *, void *));
- Driver list.
struct bus_type also contains a list of all drivers registered with
-it. An internal list of drivers that the bus driver maintains may
-be removed in favor of using the generic one.
+it. An internal list of drivers that the bus driver maintains may
+be removed in favor of using the generic one.
-The drivers may be iterated over, like devices:
+The drivers may be iterated over, like devices::
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
- void * data, int (*fn)(struct device_driver *, void *));
+ int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+ void * data, int (*fn)(struct device_driver *, void *));
Please see drivers/base/bus.c for more information.
-- rwsem
+- rwsem
struct bus_type contains an rwsem that protects all core accesses to
the device and driver lists. This can be used by the bus driver
internally, and should be used when accessing the device or driver
-lists the bus maintains.
+lists the bus maintains.
-- Device and driver fields.
+- Device and driver fields.
Some of the fields in struct device and struct device_driver duplicate
fields in the bus-specific representations of these objects. Feel free
@@ -444,4 +446,3 @@ to remove the bus-specific ones and favor the generic ones. Note
though, that this will likely mean fixing up all the drivers that
reference the bus-specific fields (though those should all be 1-line
changes).
-
diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt
index 2806e5544e43..f388545a85a7 100644
--- a/Documentation/eisa.txt
+++ b/Documentation/eisa.txt
@@ -103,7 +103,7 @@ id_table an array of NULL terminated EISA id strings,
(driver_data).
driver a generic driver, such as described in
- Documentation/driver-model/driver.txt. Only .name,
+ Documentation/driver-model/driver.rst. Only .name,
.probe and .remove members are mandatory.
=============== ====================================================
@@ -152,7 +152,7 @@ state set of flags indicating the state of the device. Current
flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED.
res set of four 256 bytes I/O regions allocated to this device
dma_mask DMA mask set from the parent device.
-dev generic device (see Documentation/driver-model/device.txt)
+dev generic device (see Documentation/driver-model/device.rst)
======== ============================================================
You can get the 'struct eisa_device' from 'struct device' using the
diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst
index f9796b9d9db6..d5b05d3e54ba 100644
--- a/Documentation/hwmon/submitting-patches.rst
+++ b/Documentation/hwmon/submitting-patches.rst
@@ -89,7 +89,7 @@ increase the chances of your change being accepted.
console. Excessive logging can seriously affect system performance.
* Use devres functions whenever possible to allocate resources. For rationale
- and supported functions, please see Documentation/driver-model/devres.txt.
+ and supported functions, please see Documentation/driver-model/devres.rst.
If a function is not supported by devres, consider using devm_add_action().
* If the driver has a detect function, make sure it is silent. Debug messages
diff --git a/drivers/base/platform.c b/drivers/base/platform.c
index 4d1729853d1a..713903290385 100644
--- a/drivers/base/platform.c
+++ b/drivers/base/platform.c
@@ -5,7 +5,7 @@
* Copyright (c) 2002-3 Patrick Mochel
* Copyright (c) 2002-3 Open Source Development Labs
*
- * Please see Documentation/driver-model/platform.txt for more
+ * Please see Documentation/driver-model/platform.rst for more
* information.
*/
diff --git a/drivers/gpio/gpio-cs5535.c b/drivers/gpio/gpio-cs5535.c
index 6314225dbed0..3611a0571667 100644
--- a/drivers/gpio/gpio-cs5535.c
+++ b/drivers/gpio/gpio-cs5535.c
@@ -41,7 +41,7 @@ MODULE_PARM_DESC(mask, "GPIO channel mask.");
/*
* FIXME: convert this singleton driver to use the state container
- * design pattern, see Documentation/driver-model/design-patterns.txt
+ * design pattern, see Documentation/driver-model/design-patterns.rst
*/
static struct cs5535_gpio_chip {
struct gpio_chip chip;
diff --git a/drivers/net/ethernet/intel/ice/ice_main.c b/drivers/net/ethernet/intel/ice/ice_main.c
index 28ec0d57941d..41c90f2ddb31 100644
--- a/drivers/net/ethernet/intel/ice/ice_main.c
+++ b/drivers/net/ethernet/intel/ice/ice_main.c
@@ -2286,7 +2286,7 @@ ice_probe(struct pci_dev *pdev, const struct pci_device_id __always_unused *ent)
struct ice_hw *hw;
int err;
- /* this driver uses devres, see Documentation/driver-model/devres.txt */
+ /* this driver uses devres, see Documentation/driver-model/devres.rst */
err = pcim_enable_device(pdev);
if (err)
return err;
diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci
index b2a2cf8bf81f..e32236a979a8 100644
--- a/scripts/coccinelle/free/devm_free.cocci
+++ b/scripts/coccinelle/free/devm_free.cocci
@@ -2,7 +2,7 @@
/// functions. Values allocated using the devm_functions are freed when
/// the device is detached, and thus the use of the standard freeing
/// function would cause a double free.
-/// See Documentation/driver-model/devres.txt for more information.
+/// See Documentation/driver-model/devres.rst for more information.
///
/// A difficulty of detecting this problem is that the standard freeing
/// function might be called from a different function than the one
--
2.21.0
^ permalink raw reply related
* [PATCH v1 23/31] docs: laptops: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mattia Dongili, Arnd Bergmann,
Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
platform-driver-x86
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the laptops documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/testing/sysfs-block-device | 2 +-
.../ABI/testing/sysfs-platform-asus-laptop | 2 +-
.../admin-guide/kernel-parameters.txt | 2 +-
.../{asus-laptop.txt => asus-laptop.rst} | 92 ++--
...otection.txt => disk-shock-protection.rst} | 32 +-
Documentation/laptops/index.rst | 17 +
.../{laptop-mode.txt => laptop-mode.rst} | 509 +++++++++---------
.../{sony-laptop.txt => sony-laptop.rst} | 58 +-
.../laptops/{sonypi.txt => sonypi.rst} | 28 +-
.../{thinkpad-acpi.txt => thinkpad-acpi.rst} | 363 ++++++++-----
.../{toshiba_haps.txt => toshiba_haps.rst} | 47 +-
Documentation/sysctl/vm.txt | 4 +-
MAINTAINERS | 2 +-
drivers/char/Kconfig | 2 +-
drivers/platform/x86/Kconfig | 4 +-
15 files changed, 660 insertions(+), 504 deletions(-)
rename Documentation/laptops/{asus-laptop.txt => asus-laptop.rst} (84%)
rename Documentation/laptops/{disk-shock-protection.txt => disk-shock-protection.rst} (91%)
create mode 100644 Documentation/laptops/index.rst
rename Documentation/laptops/{laptop-mode.txt => laptop-mode.rst} (62%)
rename Documentation/laptops/{sony-laptop.txt => sony-laptop.rst} (85%)
rename Documentation/laptops/{sonypi.txt => sonypi.rst} (87%)
rename Documentation/laptops/{thinkpad-acpi.txt => thinkpad-acpi.rst} (89%)
rename Documentation/laptops/{toshiba_haps.txt => toshiba_haps.rst} (60%)
diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 82ef6eab042d..0d57bbb4fddc 100644
--- a/Documentation/ABI/testing/sysfs-block-device
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -45,7 +45,7 @@ Description:
- Values below -2 are rejected with -EINVAL
For more information, see
- Documentation/laptops/disk-shock-protection.txt
+ Documentation/laptops/disk-shock-protection.rst
What: /sys/block/*/device/ncq_prio_enable
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
index cd9d667c3da2..d67fa4bafa70 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -31,7 +31,7 @@ Description:
To control the LED display, use the following :
echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
where T control the 3 letters display, and DDD the 3 digits display.
- The DDD table can be found in Documentation/laptops/asus-laptop.txt
+ The DDD table can be found in Documentation/laptops/asus-laptop.rst
What: /sys/devices/platform/asus_laptop/bluetooth
Date: January 2007
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 3faf37b8b001..7abe677f8c5e 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4356,7 +4356,7 @@
Format: <integer>
sonypi.*= [HW] Sony Programmable I/O Control Device driver
- See Documentation/laptops/sonypi.txt
+ See Documentation/laptops/sonypi.rst
spectre_v2= [X86] Control mitigation of Spectre variant 2
(indirect branch speculation) vulnerability.
diff --git a/Documentation/laptops/asus-laptop.txt b/Documentation/laptops/asus-laptop.rst
similarity index 84%
rename from Documentation/laptops/asus-laptop.txt
rename to Documentation/laptops/asus-laptop.rst
index 5f2858712aa0..95176321a25a 100644
--- a/Documentation/laptops/asus-laptop.txt
+++ b/Documentation/laptops/asus-laptop.rst
@@ -1,6 +1,9 @@
+==================
Asus Laptop Extras
+==================
Version 0.1
+
August 6, 2009
Corentin Chary <corentincj@iksaif.net>
@@ -10,11 +13,12 @@ http://acpi4asus.sf.net/
It may also support some MEDION, JVC or VICTOR laptops (such as MEDION 9675 or
VICTOR XP7210 for example). It makes all the extra buttons generate input
events (like keyboards).
+
On some models adds support for changing the display brightness and output,
switching the LCD backlight on and off, and most importantly, allows you to
blink those fancy LEDs intended for reporting mail and wireless status.
-This driver supercedes the old asus_acpi driver.
+This driver supersedes the old asus_acpi driver.
Requirements
------------
@@ -49,7 +53,7 @@ Usage
see some lines like this :
Asus Laptop Extras version 0.42
- L2D model detected.
+ - L2D model detected.
If it is not the output you have on your laptop, send it (and the laptop's
DSDT) to me.
@@ -68,9 +72,12 @@ Usage
LEDs
----
- You can modify LEDs be echoing values to /sys/class/leds/asus::*/brightness :
+ You can modify LEDs be echoing values to `/sys/class/leds/asus/*/brightness`::
+
echo 1 > /sys/class/leds/asus::mail/brightness
+
will switch the mail LED on.
+
You can also know if they are on/off by reading their content and use
kernel triggers like disk-activity or heartbeat.
@@ -81,7 +88,7 @@ Backlight
/sys/class/backlight/asus-laptop/. Brightness Values are between 0 and 15.
Wireless devices
----------------
+----------------
You can turn the internal Bluetooth adapter on/off with the bluetooth entry
(only on models with Bluetooth). This usually controls the associated LED.
@@ -93,18 +100,20 @@ Display switching
Note: the display switching code is currently considered EXPERIMENTAL.
Switching works for the following models:
- L3800C
- A2500H
- L5800C
- M5200N
- W1000N (albeit with some glitches)
- M6700R
- A6JC
- F3J
+
+ - L3800C
+ - A2500H
+ - L5800C
+ - M5200N
+ - W1000N (albeit with some glitches)
+ - M6700R
+ - A6JC
+ - F3J
Switching doesn't work for the following:
- M3700N
- L2X00D (locks the laptop under certain conditions)
+
+ - M3700N
+ - L2X00D (locks the laptop under certain conditions)
To switch the displays, echo values from 0 to 15 to
/sys/devices/platform/asus-laptop/display. The significance of those values
@@ -113,48 +122,51 @@ Display switching
+-------+-----+-----+-----+-----+-----+
| Bin | Val | DVI | TV | CRT | LCD |
+-------+-----+-----+-----+-----+-----+
- + 0000 + 0 + + + + +
+ | 0000 | 0 | | | | |
+-------+-----+-----+-----+-----+-----+
- + 0001 + 1 + + + + X +
+ | 0001 | 1 | | | | X |
+-------+-----+-----+-----+-----+-----+
- + 0010 + 2 + + + X + +
+ | 0010 | 2 | | | X | |
+-------+-----+-----+-----+-----+-----+
- + 0011 + 3 + + + X + X +
+ | 0011 | 3 | | | X | X |
+-------+-----+-----+-----+-----+-----+
- + 0100 + 4 + + X + + +
+ | 0100 | 4 | | X | | |
+-------+-----+-----+-----+-----+-----+
- + 0101 + 5 + + X + + X +
+ | 0101 | 5 | | X | | X |
+-------+-----+-----+-----+-----+-----+
- + 0110 + 6 + + X + X + +
+ | 0110 | 6 | | X | X | |
+-------+-----+-----+-----+-----+-----+
- + 0111 + 7 + + X + X + X +
+ | 0111 | 7 | | X | X | X |
+-------+-----+-----+-----+-----+-----+
- + 1000 + 8 + X + + + +
+ | 1000 | 8 | X | | | |
+-------+-----+-----+-----+-----+-----+
- + 1001 + 9 + X + + + X +
+ | 1001 | 9 | X | | | X |
+-------+-----+-----+-----+-----+-----+
- + 1010 + 10 + X + + X + +
+ | 1010 | 10 | X | | X | |
+-------+-----+-----+-----+-----+-----+
- + 1011 + 11 + X + + X + X +
+ | 1011 | 11 | X | | X | X |
+-------+-----+-----+-----+-----+-----+
- + 1100 + 12 + X + X + + +
+ | 1100 | 12 | X | X | | |
+-------+-----+-----+-----+-----+-----+
- + 1101 + 13 + X + X + + X +
+ | 1101 | 13 | X | X | | X |
+-------+-----+-----+-----+-----+-----+
- + 1110 + 14 + X + X + X + +
+ | 1110 | 14 | X | X | X | |
+-------+-----+-----+-----+-----+-----+
- + 1111 + 15 + X + X + X + X +
+ | 1111 | 15 | X | X | X | X |
+-------+-----+-----+-----+-----+-----+
In most cases, the appropriate displays must be plugged in for the above
combinations to work. TV-Out may need to be initialized at boot time.
Debugging:
+
1) Check whether the Fn+F8 key:
+
a) does not lock the laptop (try a boot with noapic / nolapic if it does)
b) generates events (0x6n, where n is the value corresponding to the
configuration above)
c) actually works
+
Record the disp value at every configuration.
2) Echo values from 0 to 15 to /sys/devices/platform/asus-laptop/display.
Record its value, note any change. If nothing changes, try a broader range,
@@ -164,7 +176,7 @@ Display switching
Note: on some machines (e.g. L3C), after the module has been loaded, only 0x6n
events are generated and no actual switching occurs. In such a case, a line
- like:
+ like::
echo $((10#$arg-60)) > /sys/devices/platform/asus-laptop/display
@@ -180,15 +192,16 @@ LED display
several items of information.
LED display works for the following models:
- W1000N
- W1J
- To control the LED display, use the following :
+ - W1000N
+ - W1J
+
+ To control the LED display, use the following::
echo 0x0T000DDD > /sys/devices/platform/asus-laptop/
where T control the 3 letters display, and DDD the 3 digits display,
- according to the tables below.
+ according to the tables below::
DDD (digits)
000 to 999 = display digits
@@ -208,8 +221,8 @@ LED display
For example "echo 0x01000001 >/sys/devices/platform/asus-laptop/ledd"
would display "DVD001".
-Driver options:
----------------
+Driver options
+--------------
Options can be passed to the asus-laptop driver using the standard
module argument syntax (<param>=<value> when passing the option to the
@@ -219,6 +232,7 @@ Driver options:
wapf: WAPF defines the behavior of the Fn+Fx wlan key
The significance of values is yet to be found, but
most of the time:
+
- 0x0 should do nothing
- 0x1 should allow to control the device with Fn+Fx key.
- 0x4 should send an ACPI event (0x88) while pressing the Fn+Fx key
@@ -237,7 +251,7 @@ Unsupported models
- ASUS L7300G
- ASUS L8400
-Patches, Errors, Questions:
+Patches, Errors, Questions
--------------------------
I appreciate any success or failure
@@ -253,5 +267,5 @@ Patches, Errors, Questions:
Any other comments or patches are also more than welcome.
acpi4asus-user@lists.sourceforge.net
+
http://sourceforge.net/projects/acpi4asus
-
diff --git a/Documentation/laptops/disk-shock-protection.txt b/Documentation/laptops/disk-shock-protection.rst
similarity index 91%
rename from Documentation/laptops/disk-shock-protection.txt
rename to Documentation/laptops/disk-shock-protection.rst
index 0e6ba2663834..e97c5f78d8c3 100644
--- a/Documentation/laptops/disk-shock-protection.txt
+++ b/Documentation/laptops/disk-shock-protection.rst
@@ -1,17 +1,18 @@
+==========================
Hard disk shock protection
==========================
Author: Elias Oltmanns <eo@nebensachen.de>
+
Last modified: 2008-10-03
-0. Contents
------------
+.. 0. Contents
-1. Intro
-2. The interface
-3. References
-4. CREDITS
+ 1. Intro
+ 2. The interface
+ 3. References
+ 4. CREDITS
1. Intro
@@ -36,8 +37,8 @@ that).
----------------
For each ATA device, the kernel exports the file
-block/*/device/unload_heads in sysfs (here assumed to be mounted under
-/sys). Access to /sys/block/*/device/unload_heads is denied with
+`block/*/device/unload_heads` in sysfs (here assumed to be mounted under
+/sys). Access to `/sys/block/*/device/unload_heads` is denied with
-EOPNOTSUPP if the device does not support the unload feature.
Otherwise, writing an integer value to this file will take the heads
of the respective drive off the platter and block all I/O operations
@@ -54,18 +55,18 @@ cancel a previously set timeout and resume normal operation
immediately by specifying a timeout of 0. Values below -2 are rejected
with -EINVAL (see below for the special meaning of -1 and -2). If the
timeout specified for a recent head park request has not yet expired,
-reading from /sys/block/*/device/unload_heads will report the number
+reading from `/sys/block/*/device/unload_heads` will report the number
of milliseconds remaining until normal operation will be resumed;
otherwise, reading the unload_heads attribute will return 0.
For example, do the following in order to park the heads of drive
-/dev/sda and stop all I/O operations for five seconds:
+/dev/sda and stop all I/O operations for five seconds::
-# echo 5000 > /sys/block/sda/device/unload_heads
+ # echo 5000 > /sys/block/sda/device/unload_heads
-A simple
+A simple::
-# cat /sys/block/sda/device/unload_heads
+ # cat /sys/block/sda/device/unload_heads
will show you how many milliseconds are left before normal operation
will be resumed.
@@ -112,9 +113,9 @@ unload_heads attribute. If you know that your device really does
support the unload feature (for instance, because the vendor of your
laptop or the hard drive itself told you so), then you can tell the
kernel to enable the usage of this feature for that drive by writing
-the special value -1 to the unload_heads attribute:
+the special value -1 to the unload_heads attribute::
-# echo -1 > /sys/block/sda/device/unload_heads
+ # echo -1 > /sys/block/sda/device/unload_heads
will enable the feature for /dev/sda, and giving -2 instead of -1 will
disable it again.
@@ -135,6 +136,7 @@ for use. Please feel free to add projects that have been the victims
of my ignorance.
- http://www.thinkwiki.org/wiki/HDAPS
+
See this page for information about Linux support of the hard disk
active protection system as implemented in IBM/Lenovo Thinkpads.
diff --git a/Documentation/laptops/index.rst b/Documentation/laptops/index.rst
new file mode 100644
index 000000000000..001a30910d09
--- /dev/null
+++ b/Documentation/laptops/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+==============
+Laptop Drivers
+==============
+
+.. toctree::
+ :maxdepth: 1
+
+ asus-laptop
+ disk-shock-protection
+ laptop-mode
+ lg-laptop
+ sony-laptop
+ sonypi
+ thinkpad-acpi
+ toshiba_haps
diff --git a/Documentation/laptops/laptop-mode.txt b/Documentation/laptops/laptop-mode.rst
similarity index 62%
rename from Documentation/laptops/laptop-mode.txt
rename to Documentation/laptops/laptop-mode.rst
index 1c707fc9b141..c984c4262f2e 100644
--- a/Documentation/laptops/laptop-mode.txt
+++ b/Documentation/laptops/laptop-mode.rst
@@ -1,8 +1,11 @@
+===============================================
How to conserve battery power using laptop-mode
------------------------------------------------
+===============================================
Document Author: Bart Samwel (bart@samwel.tk)
+
Date created: January 2, 2004
+
Last modified: December 06, 2004
Introduction
@@ -12,17 +15,16 @@ Laptop mode is used to minimize the time that the hard disk needs to be spun up,
to conserve battery power on laptops. It has been reported to cause significant
power savings.
-Contents
---------
+.. Contents
-* Introduction
-* Installation
-* Caveats
-* The Details
-* Tips & Tricks
-* Control script
-* ACPI integration
-* Monitoring tool
+ * Introduction
+ * Installation
+ * Caveats
+ * The Details
+ * Tips & Tricks
+ * Control script
+ * ACPI integration
+ * Monitoring tool
Installation
@@ -33,7 +35,7 @@ or anything. Simply install all the files included in this document, and
laptop mode will automatically be started when you're on battery. For
your convenience, a tarball containing an installer can be downloaded at:
-http://www.samwel.tk/laptop_mode/laptop_mode/
+ http://www.samwel.tk/laptop_mode/laptop_mode/
To configure laptop mode, you need to edit the configuration file, which is
located in /etc/default/laptop-mode on Debian-based systems, or in
@@ -209,7 +211,7 @@ Tips & Tricks
this on powerbooks too. I hope that this is a piece of information that
might be useful to the Laptop Mode patch or its users."
-* In syslog.conf, you can prefix entries with a dash ``-'' to omit syncing the
+* In syslog.conf, you can prefix entries with a dash `-` to omit syncing the
file after every logging. When you're using laptop-mode and your disk doesn't
spin down, this is a likely culprit.
@@ -233,83 +235,82 @@ configuration file
It should be installed as /etc/default/laptop-mode on Debian, and as
/etc/sysconfig/laptop-mode on Red Hat, SUSE, Mandrake, and other work-alikes.
---------------------CONFIG FILE BEGIN-------------------------------------------
-# Maximum time, in seconds, of hard drive spindown time that you are
-# comfortable with. Worst case, it's possible that you could lose this
-# amount of work if your battery fails you while in laptop mode.
-#MAX_AGE=600
+Config file::
-# Automatically disable laptop mode when the number of minutes of battery
-# that you have left goes below this threshold.
-MINIMUM_BATTERY_MINUTES=10
+ # Maximum time, in seconds, of hard drive spindown time that you are
+ # comfortable with. Worst case, it's possible that you could lose this
+ # amount of work if your battery fails you while in laptop mode.
+ #MAX_AGE=600
-# Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
-# by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
-# will read a complete MP3 at once, and will then spin down while the MP3/OGG is
-# playing.
-#READAHEAD=4096
+ # Automatically disable laptop mode when the number of minutes of battery
+ # that you have left goes below this threshold.
+ MINIMUM_BATTERY_MINUTES=10
-# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
-#DO_REMOUNTS=1
+ # Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
+ # by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
+ # will read a complete MP3 at once, and will then spin down while the MP3/OGG is
+ # playing.
+ #READAHEAD=4096
-# And shall we add the "noatime" option to that as well? (1=yes)
-#DO_REMOUNT_NOATIME=1
+ # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
+ #DO_REMOUNTS=1
-# Dirty synchronous ratio. At this percentage of dirty pages the process
-# which
-# calls write() does its own writeback
-#DIRTY_RATIO=40
+ # And shall we add the "noatime" option to that as well? (1=yes)
+ #DO_REMOUNT_NOATIME=1
-#
-# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
-# exceeded, the kernel will wake flusher threads which will then reduce the
-# amount of dirty memory to dirty_background_ratio. Set this nice and low,
-# so once some writeout has commenced, we do a lot of it.
-#
-#DIRTY_BACKGROUND_RATIO=5
+ # Dirty synchronous ratio. At this percentage of dirty pages the process
+ # which
+ # calls write() does its own writeback
+ #DIRTY_RATIO=40
-# kernel default dirty buffer age
-#DEF_AGE=30
-#DEF_UPDATE=5
-#DEF_DIRTY_BACKGROUND_RATIO=10
-#DEF_DIRTY_RATIO=40
-#DEF_XFS_AGE_BUFFER=15
-#DEF_XFS_SYNC_INTERVAL=30
-#DEF_XFS_BUFD_INTERVAL=1
+ #
+ # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
+ # exceeded, the kernel will wake flusher threads which will then reduce the
+ # amount of dirty memory to dirty_background_ratio. Set this nice and low,
+ # so once some writeout has commenced, we do a lot of it.
+ #
+ #DIRTY_BACKGROUND_RATIO=5
-# This must be adjusted manually to the value of HZ in the running kernel
-# on 2.4, until the XFS people change their 2.4 external interfaces to work in
-# centisecs. This can be automated, but it's a work in progress that still
-# needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
-# external interfaces, and that is currently always set to 100. So you don't
-# need to change this on 2.6.
-#XFS_HZ=100
+ # kernel default dirty buffer age
+ #DEF_AGE=30
+ #DEF_UPDATE=5
+ #DEF_DIRTY_BACKGROUND_RATIO=10
+ #DEF_DIRTY_RATIO=40
+ #DEF_XFS_AGE_BUFFER=15
+ #DEF_XFS_SYNC_INTERVAL=30
+ #DEF_XFS_BUFD_INTERVAL=1
-# Should the maximum CPU frequency be adjusted down while on battery?
-# Requires CPUFreq to be setup.
-# See Documentation/admin-guide/pm/cpufreq.rst for more info
-#DO_CPU=0
+ # This must be adjusted manually to the value of HZ in the running kernel
+ # on 2.4, until the XFS people change their 2.4 external interfaces to work in
+ # centisecs. This can be automated, but it's a work in progress that still
+ # needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
+ # external interfaces, and that is currently always set to 100. So you don't
+ # need to change this on 2.6.
+ #XFS_HZ=100
-# When on battery what is the maximum CPU speed that the system should
-# use? Legal values are "slowest" for the slowest speed that your
-# CPU is able to operate at, or a value listed in:
-# /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
-# Only applicable if DO_CPU=1.
-#CPU_MAXFREQ=slowest
+ # Should the maximum CPU frequency be adjusted down while on battery?
+ # Requires CPUFreq to be setup.
+ # See Documentation/admin-guide/pm/cpufreq.rst for more info
+ #DO_CPU=0
-# Idle timeout for your hard drive (man hdparm for valid values, -S option)
-# Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
-#AC_HD=244
-#BATT_HD=4
+ # When on battery what is the maximum CPU speed that the system should
+ # use? Legal values are "slowest" for the slowest speed that your
+ # CPU is able to operate at, or a value listed in:
+ # /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
+ # Only applicable if DO_CPU=1.
+ #CPU_MAXFREQ=slowest
-# The drives for which to adjust the idle timeout. Separate them by a space,
-# e.g. HD="/dev/hda /dev/hdb".
-#HD="/dev/hda"
+ # Idle timeout for your hard drive (man hdparm for valid values, -S option)
+ # Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
+ #AC_HD=244
+ #BATT_HD=4
-# Set the spindown timeout on a hard drive?
-#DO_HD=1
+ # The drives for which to adjust the idle timeout. Separate them by a space,
+ # e.g. HD="/dev/hda /dev/hdb".
+ #HD="/dev/hda"
---------------------CONFIG FILE END---------------------------------------------
+ # Set the spindown timeout on a hard drive?
+ #DO_HD=1
Control script
@@ -318,125 +319,126 @@ Control script
Please note that this control script works for the Linux 2.4 and 2.6 series (thanks
to Kiko Piris).
---------------------CONTROL SCRIPT BEGIN----------------------------------------
-#!/bin/bash
+Control script::
-# start or stop laptop_mode, best run by a power management daemon when
-# ac gets connected/disconnected from a laptop
-#
-# install as /sbin/laptop_mode
-#
-# Contributors to this script: Kiko Piris
-# Bart Samwel
-# Micha Feigin
-# Andrew Morton
-# Herve Eychenne
-# Dax Kelson
-#
-# Original Linux 2.4 version by: Jens Axboe
+ #!/bin/bash
-#############################################################################
+ # start or stop laptop_mode, best run by a power management daemon when
+ # ac gets connected/disconnected from a laptop
+ #
+ # install as /sbin/laptop_mode
+ #
+ # Contributors to this script: Kiko Piris
+ # Bart Samwel
+ # Micha Feigin
+ # Andrew Morton
+ # Herve Eychenne
+ # Dax Kelson
+ #
+ # Original Linux 2.4 version by: Jens Axboe
-# Source config
-if [ -f /etc/default/laptop-mode ] ; then
+ #############################################################################
+
+ # Source config
+ if [ -f /etc/default/laptop-mode ] ; then
# Debian
. /etc/default/laptop-mode
-elif [ -f /etc/sysconfig/laptop-mode ] ; then
+ elif [ -f /etc/sysconfig/laptop-mode ] ; then
# Others
- . /etc/sysconfig/laptop-mode
-fi
+ . /etc/sysconfig/laptop-mode
+ fi
-# Don't raise an error if the config file is incomplete
-# set defaults instead:
+ # Don't raise an error if the config file is incomplete
+ # set defaults instead:
-# Maximum time, in seconds, of hard drive spindown time that you are
-# comfortable with. Worst case, it's possible that you could lose this
-# amount of work if your battery fails you while in laptop mode.
-MAX_AGE=${MAX_AGE:-'600'}
+ # Maximum time, in seconds, of hard drive spindown time that you are
+ # comfortable with. Worst case, it's possible that you could lose this
+ # amount of work if your battery fails you while in laptop mode.
+ MAX_AGE=${MAX_AGE:-'600'}
-# Read-ahead, in kilobytes
-READAHEAD=${READAHEAD:-'4096'}
+ # Read-ahead, in kilobytes
+ READAHEAD=${READAHEAD:-'4096'}
-# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
-DO_REMOUNTS=${DO_REMOUNTS:-'1'}
+ # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
+ DO_REMOUNTS=${DO_REMOUNTS:-'1'}
-# And shall we add the "noatime" option to that as well? (1=yes)
-DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
+ # And shall we add the "noatime" option to that as well? (1=yes)
+ DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
-# Shall we adjust the idle timeout on a hard drive?
-DO_HD=${DO_HD:-'1'}
+ # Shall we adjust the idle timeout on a hard drive?
+ DO_HD=${DO_HD:-'1'}
-# Adjust idle timeout on which hard drive?
-HD="${HD:-'/dev/hda'}"
+ # Adjust idle timeout on which hard drive?
+ HD="${HD:-'/dev/hda'}"
-# spindown time for HD (hdparm -S values)
-AC_HD=${AC_HD:-'244'}
-BATT_HD=${BATT_HD:-'4'}
+ # spindown time for HD (hdparm -S values)
+ AC_HD=${AC_HD:-'244'}
+ BATT_HD=${BATT_HD:-'4'}
-# Dirty synchronous ratio. At this percentage of dirty pages the process which
-# calls write() does its own writeback
-DIRTY_RATIO=${DIRTY_RATIO:-'40'}
+ # Dirty synchronous ratio. At this percentage of dirty pages the process which
+ # calls write() does its own writeback
+ DIRTY_RATIO=${DIRTY_RATIO:-'40'}
-# cpu frequency scaling
-# See Documentation/admin-guide/pm/cpufreq.rst for more info
-DO_CPU=${CPU_MANAGE:-'0'}
-CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
+ # cpu frequency scaling
+ # See Documentation/admin-guide/pm/cpufreq.rst for more info
+ DO_CPU=${CPU_MANAGE:-'0'}
+ CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
-#
-# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
-# exceeded, the kernel will wake flusher threads which will then reduce the
-# amount of dirty memory to dirty_background_ratio. Set this nice and low,
-# so once some writeout has commenced, we do a lot of it.
-#
-DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
+ #
+ # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been
+ # exceeded, the kernel will wake flusher threads which will then reduce the
+ # amount of dirty memory to dirty_background_ratio. Set this nice and low,
+ # so once some writeout has commenced, we do a lot of it.
+ #
+ DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
-# kernel default dirty buffer age
-DEF_AGE=${DEF_AGE:-'30'}
-DEF_UPDATE=${DEF_UPDATE:-'5'}
-DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
-DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
-DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
-DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
-DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
+ # kernel default dirty buffer age
+ DEF_AGE=${DEF_AGE:-'30'}
+ DEF_UPDATE=${DEF_UPDATE:-'5'}
+ DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
+ DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
+ DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
+ DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
+ DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
-# This must be adjusted manually to the value of HZ in the running kernel
-# on 2.4, until the XFS people change their 2.4 external interfaces to work in
-# centisecs. This can be automated, but it's a work in progress that still needs
-# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
-# interfaces, and that is currently always set to 100. So you don't need to
-# change this on 2.6.
-XFS_HZ=${XFS_HZ:-'100'}
+ # This must be adjusted manually to the value of HZ in the running kernel
+ # on 2.4, until the XFS people change their 2.4 external interfaces to work in
+ # centisecs. This can be automated, but it's a work in progress that still needs
+ # some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
+ # interfaces, and that is currently always set to 100. So you don't need to
+ # change this on 2.6.
+ XFS_HZ=${XFS_HZ:-'100'}
-#############################################################################
+ #############################################################################
-KLEVEL="$(uname -r |
- {
+ KLEVEL="$(uname -r |
+ {
IFS='.' read a b c
echo $a.$b
}
-)"
-case "$KLEVEL" in
+ )"
+ case "$KLEVEL" in
"2.4"|"2.6")
;;
*)
echo "Unhandled kernel version: $KLEVEL ('uname -r' = '$(uname -r)')" >&2
exit 1
;;
-esac
+ esac
-if [ ! -e /proc/sys/vm/laptop_mode ] ; then
+ if [ ! -e /proc/sys/vm/laptop_mode ] ; then
echo "Kernel is not patched with laptop_mode patch." >&2
exit 1
-fi
+ fi
-if [ ! -w /proc/sys/vm/laptop_mode ] ; then
+ if [ ! -w /proc/sys/vm/laptop_mode ] ; then
echo "You do not have enough privileges to enable laptop_mode." >&2
exit 1
-fi
+ fi
-# Remove an option (the first parameter) of the form option=<number> from
-# a mount options string (the rest of the parameters).
-parse_mount_opts () {
+ # Remove an option (the first parameter) of the form option=<number> from
+ # a mount options string (the rest of the parameters).
+ parse_mount_opts () {
OPT="$1"
shift
echo ",$*," | sed \
@@ -444,11 +446,11 @@ parse_mount_opts () {
-e 's/,,*/,/g' \
-e 's/^,//' \
-e 's/,$//'
-}
+ }
-# Remove an option (the first parameter) without any arguments from
-# a mount option string (the rest of the parameters).
-parse_nonumber_mount_opts () {
+ # Remove an option (the first parameter) without any arguments from
+ # a mount option string (the rest of the parameters).
+ parse_nonumber_mount_opts () {
OPT="$1"
shift
echo ",$*," | sed \
@@ -456,20 +458,20 @@ parse_nonumber_mount_opts () {
-e 's/,,*/,/g' \
-e 's/^,//' \
-e 's/,$//'
-}
+ }
-# Find out the state of a yes/no option (e.g. "atime"/"noatime") in
-# fstab for a given filesystem, and use this state to replace the
-# value of the option in another mount options string. The device
-# is the first argument, the option name the second, and the default
-# value the third. The remainder is the mount options string.
-#
-# Example:
-# parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
-#
-# If fstab contains, say, "rw" for this filesystem, then the result
-# will be "defaults,atime".
-parse_yesno_opts_wfstab () {
+ # Find out the state of a yes/no option (e.g. "atime"/"noatime") in
+ # fstab for a given filesystem, and use this state to replace the
+ # value of the option in another mount options string. The device
+ # is the first argument, the option name the second, and the default
+ # value the third. The remainder is the mount options string.
+ #
+ # Example:
+ # parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
+ #
+ # If fstab contains, say, "rw" for this filesystem, then the result
+ # will be "defaults,atime".
+ parse_yesno_opts_wfstab () {
L_DEV="$1"
OPT="$2"
DEF_OPT="$3"
@@ -491,21 +493,21 @@ parse_yesno_opts_wfstab () {
# option not specified in fstab -- choose the default.
echo "$PARSEDOPTS1,$DEF_OPT"
fi
-}
+ }
-# Find out the state of a numbered option (e.g. "commit=NNN") in
-# fstab for a given filesystem, and use this state to replace the
-# value of the option in another mount options string. The device
-# is the first argument, and the option name the second. The
-# remainder is the mount options string in which the replacement
-# must be done.
-#
-# Example:
-# parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
-#
-# If fstab contains, say, "commit=3,rw" for this filesystem, then the
-# result will be "rw,commit=3".
-parse_mount_opts_wfstab () {
+ # Find out the state of a numbered option (e.g. "commit=NNN") in
+ # fstab for a given filesystem, and use this state to replace the
+ # value of the option in another mount options string. The device
+ # is the first argument, and the option name the second. The
+ # remainder is the mount options string in which the replacement
+ # must be done.
+ #
+ # Example:
+ # parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
+ #
+ # If fstab contains, say, "commit=3,rw" for this filesystem, then the
+ # result will be "rw,commit=3".
+ parse_mount_opts_wfstab () {
L_DEV="$1"
OPT="$2"
shift 2
@@ -523,9 +525,9 @@ parse_mount_opts_wfstab () {
# option not specified in fstab: set it to 0
echo "$PARSEDOPTS1,$OPT=0"
fi
-}
+ }
-deduce_fstype () {
+ deduce_fstype () {
MP="$1"
# My root filesystem unfortunately has
# type "unknown" in /etc/mtab. If we encounter
@@ -538,13 +540,13 @@ deduce_fstype () {
exit 0
fi
done
-}
+ }
-if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
+ if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
NOATIME_OPT=",noatime"
-fi
+ fi
-case "$1" in
+ case "$1" in
start)
AGE=$((100*$MAX_AGE))
XFS_AGE=$(($XFS_HZ*$MAX_AGE))
@@ -687,10 +689,9 @@ case "$1" in
exit 1
;;
-esac
+ esac
-exit 0
---------------------CONTROL SCRIPT END------------------------------------------
+ exit 0
ACPI integration
@@ -701,78 +702,76 @@ kick off the laptop_mode script and run hdparm. The part that
automatically disables laptop mode when the battery is low was
written by Jan Topinski.
------------------/etc/acpi/events/ac_adapter BEGIN------------------------------
-event=ac_adapter
-action=/etc/acpi/actions/ac.sh %e
-----------------/etc/acpi/events/ac_adapter END---------------------------------
+/etc/acpi/events/ac_adapter::
+ event=ac_adapter
+ action=/etc/acpi/actions/ac.sh %e
------------------/etc/acpi/events/battery BEGIN---------------------------------
-event=battery.*
-action=/etc/acpi/actions/battery.sh %e
-----------------/etc/acpi/events/battery END------------------------------------
+/etc/acpi/events/battery::
+ event=battery.*
+ action=/etc/acpi/actions/battery.sh %e
-----------------/etc/acpi/actions/ac.sh BEGIN-----------------------------------
-#!/bin/bash
+/etc/acpi/actions/ac.sh::
-# ac on/offline event handler
+ #!/bin/bash
-status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
+ # ac on/offline event handler
-case $status in
- "on-line")
- /sbin/laptop_mode stop
- exit 0
- ;;
- "off-line")
- /sbin/laptop_mode start
- exit 0
- ;;
-esac
----------------------------/etc/acpi/actions/ac.sh END--------------------------
+ status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
+ case $status in
+ "on-line")
+ /sbin/laptop_mode stop
+ exit 0
+ ;;
+ "off-line")
+ /sbin/laptop_mode start
+ exit 0
+ ;;
+ esac
----------------------------/etc/acpi/actions/battery.sh BEGIN-------------------
-#! /bin/bash
-# Automatically disable laptop mode when the battery almost runs out.
+/etc/acpi/actions/battery.sh::
-BATT_INFO=/proc/acpi/battery/$2/state
+ #! /bin/bash
-if [[ -f /proc/sys/vm/laptop_mode ]]
-then
- LM=`cat /proc/sys/vm/laptop_mode`
- if [[ $LM -gt 0 ]]
- then
- if [[ -f $BATT_INFO ]]
+ # Automatically disable laptop mode when the battery almost runs out.
+
+ BATT_INFO=/proc/acpi/battery/$2/state
+
+ if [[ -f /proc/sys/vm/laptop_mode ]]
+ then
+ LM=`cat /proc/sys/vm/laptop_mode`
+ if [[ $LM -gt 0 ]]
then
- # Source the config file only now that we know we need
- if [ -f /etc/default/laptop-mode ] ; then
- # Debian
- . /etc/default/laptop-mode
- elif [ -f /etc/sysconfig/laptop-mode ] ; then
- # Others
- . /etc/sysconfig/laptop-mode
- fi
- MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
+ if [[ -f $BATT_INFO ]]
+ then
+ # Source the config file only now that we know we need
+ if [ -f /etc/default/laptop-mode ] ; then
+ # Debian
+ . /etc/default/laptop-mode
+ elif [ -f /etc/sysconfig/laptop-mode ] ; then
+ # Others
+ . /etc/sysconfig/laptop-mode
+ fi
+ MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
- ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
- if [[ ACTION -eq "discharging" ]]
- then
- PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
- REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
- fi
- if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
- then
- /sbin/laptop_mode stop
- fi
- else
- logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
+ ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
+ if [[ ACTION -eq "discharging" ]]
+ then
+ PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
+ REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" `
+ fi
+ if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
+ then
+ /sbin/laptop_mode stop
+ fi
+ else
+ logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
+ fi
fi
- fi
-fi
----------------------------/etc/acpi/actions/battery.sh END--------------------
+ fi
Monitoring tool
diff --git a/Documentation/laptops/sony-laptop.txt b/Documentation/laptops/sony-laptop.rst
similarity index 85%
rename from Documentation/laptops/sony-laptop.txt
rename to Documentation/laptops/sony-laptop.rst
index 978b1e615155..9edcc7f6612f 100644
--- a/Documentation/laptops/sony-laptop.txt
+++ b/Documentation/laptops/sony-laptop.rst
@@ -1,7 +1,9 @@
+=========================================
Sony Notebook Control Driver (SNC) Readme
------------------------------------------
- Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
- Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
+=========================================
+
+ - Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
+ - Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
This mini-driver drives the SNC and SPIC device present in the ACPI BIOS of the
Sony Vaio laptops. This driver mixes both devices functions under the same
@@ -10,6 +12,7 @@ obsoleted by sony-laptop now.
Fn keys (hotkeys):
------------------
+
Some models report hotkeys through the SNC or SPIC devices, such events are
reported both through the ACPI subsystem as acpi events and through the INPUT
subsystem. See the logs of /proc/bus/input/devices to find out what those
@@ -28,11 +31,14 @@ If your laptop model supports it, you will find sysfs files in the
/sys/class/backlight/sony/
directory. You will be able to query and set the current screen
brightness:
+
+ ====================== =========================================
brightness get/set screen brightness (an integer
between 0 and 7)
actual_brightness reading from this file will query the HW
to get real brightness value
max_brightness the maximum brightness value
+ ====================== =========================================
Platform specific:
@@ -45,6 +51,8 @@ You then read/write integer values from/to those files by using
standard UNIX tools.
The files are:
+
+ ====================== ==========================================
brightness_default screen brightness which will be set
when the laptop will be rebooted
cdpower power on/off the internal CD drive
@@ -53,21 +61,39 @@ The files are:
(only in debug mode)
bluetoothpower power on/off the internal bluetooth device
fanspeed get/set the fan speed
+ ====================== ==========================================
Note that some files may be missing if they are not supported
by your particular laptop model.
-Example usage:
+Example usage::
+
# echo "1" > /sys/devices/platform/sony-laptop/brightness_default
-sets the lowest screen brightness for the next and later reboots,
+
+sets the lowest screen brightness for the next and later reboots
+
+::
+
# echo "8" > /sys/devices/platform/sony-laptop/brightness_default
-sets the highest screen brightness for the next and later reboots,
+
+sets the highest screen brightness for the next and later reboots
+
+::
+
# cat /sys/devices/platform/sony-laptop/brightness_default
-retrieves the value.
+
+retrieves the value
+
+::
# echo "0" > /sys/devices/platform/sony-laptop/audiopower
-powers off the sound card,
+
+powers off the sound card
+
+::
+
# echo "1" > /sys/devices/platform/sony-laptop/audiopower
+
powers on the sound card.
@@ -76,7 +102,8 @@ RFkill control:
More recent Vaio models expose a consistent set of ACPI methods to
control radio frequency emitting devices. If you are a lucky owner of
such a laptop you will find the necessary rfkill devices under
-/sys/class/rfkill. Check those starting with sony-* in
+/sys/class/rfkill. Check those starting with sony-* in::
+
# grep . /sys/class/rfkill/*/{state,name}
@@ -88,26 +115,29 @@ you are not afraid of any side effects doing strange things with
your ACPI BIOS could have on your laptop), load the driver and
pass the option 'debug=1'.
-REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.
+REPEAT:
+ **DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.**
In your kernel logs you will find the list of all ACPI methods
the SNC device has on your laptop.
* For new models you will see a long list of meaningless method names,
-reading the DSDT table source should reveal that:
+ reading the DSDT table source should reveal that:
+
(1) the SNC device uses an internal capability lookup table
(2) SN00 is used to find values in the lookup table
(3) SN06 and SN07 are used to call into the real methods based on
offsets you can obtain iterating the table using SN00
(4) SN02 used to enable events.
+
Some values in the capability lookup table are more or less known, see
the code for all sony_call_snc_handle calls, others are more obscure.
* For old models you can see the GCDP/GCDP methods used to pwer on/off
-the CD drive, but there are others and they are usually different from
-model to model.
+ the CD drive, but there are others and they are usually different from
+ model to model.
-I HAVE NO IDEA WHAT THOSE METHODS DO.
+**I HAVE NO IDEA WHAT THOSE METHODS DO.**
The sony-laptop driver creates, for some of those methods (the most
current ones found on several Vaio models), an entry under
diff --git a/Documentation/laptops/sonypi.txt b/Documentation/laptops/sonypi.rst
similarity index 87%
rename from Documentation/laptops/sonypi.txt
rename to Documentation/laptops/sonypi.rst
index 606bdb9ce036..2a1975ed7ee4 100644
--- a/Documentation/laptops/sonypi.txt
+++ b/Documentation/laptops/sonypi.rst
@@ -1,11 +1,13 @@
+==================================================
Sony Programmable I/O Control Device Driver Readme
---------------------------------------------------
- Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
- Copyright (C) 2001-2002 Alcôve <www.alcove.com>
- Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
- Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
- Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
- Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
+==================================================
+
+ - Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
+ - Copyright (C) 2001-2002 Alcôve <www.alcove.com>
+ - Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
+ - Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
+ - Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
+ - Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
This driver enables access to the Sony Programmable I/O Control Device which
can be found in many Sony Vaio laptops. Some newer Sony laptops (seems to be
@@ -14,6 +16,7 @@ sonypi device and are not supported at all by this driver.
It will give access (through a user space utility) to some events those laptops
generate, like:
+
- jogdial events (the small wheel on the side of Vaios)
- capture button events (only on Vaio Picturebook series)
- Fn keys
@@ -49,6 +52,7 @@ module argument syntax (<param>=<value> when passing the option to the
module or sonypi.<param>=<value> on the kernel boot line when sonypi is
statically linked into the kernel). Those options are:
+ =============== =======================================================
minor: minor number of the misc device /dev/sonypi,
default is -1 (automatic allocation, see /proc/misc
or kernel logs)
@@ -86,6 +90,8 @@ statically linked into the kernel). Those options are:
will be tried. You can use the following bits to
construct your own event mask (from
drivers/char/sonypi.h):
+
+ ======================== ======
SONYPI_JOGGER_MASK 0x0001
SONYPI_CAPTURE_MASK 0x0002
SONYPI_FNKEY_MASK 0x0004
@@ -100,22 +106,24 @@ statically linked into the kernel). Those options are:
SONYPI_MEMORYSTICK_MASK 0x0800
SONYPI_BATTERY_MASK 0x1000
SONYPI_WIRELESS_MASK 0x2000
+ ======================== ======
useinput: if set (which is the default) two input devices are
created, one which interprets the jogdial events as
mouse events, the other one which acts like a
keyboard reporting the pressing of the special keys.
+ =============== =======================================================
Module use:
-----------
In order to automatically load the sonypi module on use, you can put those
-lines a configuration file in /etc/modprobe.d/:
+lines a configuration file in /etc/modprobe.d/::
alias char-major-10-250 sonypi
options sonypi minor=250
-This supposes the use of minor 250 for the sonypi device:
+This supposes the use of minor 250 for the sonypi device::
# mknod /dev/sonypi c 10 250
@@ -148,5 +156,5 @@ Bugs:
http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2
- since all development was done by reverse engineering, there is
- _absolutely no guarantee_ that this driver will not crash your
+ *absolutely no guarantee* that this driver will not crash your
laptop. Permanently.
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.rst
similarity index 89%
rename from Documentation/laptops/thinkpad-acpi.txt
rename to Documentation/laptops/thinkpad-acpi.rst
index 75ef063622d2..19d52fc3c5e9 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.rst
@@ -1,12 +1,15 @@
- ThinkPad ACPI Extras Driver
+===========================
+ThinkPad ACPI Extras Driver
+===========================
- Version 0.25
- October 16th, 2013
+Version 0.25
- Borislav Deianov <borislav@users.sf.net>
- Henrique de Moraes Holschuh <hmh@hmh.eng.br>
- http://ibm-acpi.sf.net/
+October 16th, 2013
+- Borislav Deianov <borislav@users.sf.net>
+- Henrique de Moraes Holschuh <hmh@hmh.eng.br>
+
+http://ibm-acpi.sf.net/
This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
supports various features of these laptops which are accessible
@@ -91,7 +94,8 @@ yet ready or stabilized, it is expected that this interface will change,
and any and all userspace programs must deal with it.
-Notes about the sysfs interface:
+Notes about the sysfs interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Unlike what was done with the procfs interface, correctness when talking
to the sysfs interfaces will be enforced, as will correctness in the
@@ -129,6 +133,7 @@ Driver version
--------------
procfs: /proc/acpi/ibm/driver
+
sysfs driver attribute: version
The driver name and version. No commands can be written to this file.
@@ -141,9 +146,13 @@ sysfs driver attribute: interface_version
Version of the thinkpad-acpi sysfs interface, as an unsigned long
(output in hex format: 0xAAAABBCC), where:
- AAAA - major revision
- BB - minor revision
- CC - bugfix revision
+
+ AAAA
+ - major revision
+ BB
+ - minor revision
+ CC
+ - bugfix revision
The sysfs interface version changelog for the driver can be found at the
end of this document. Changes to the sysfs interface done by the kernel
@@ -170,6 +179,7 @@ Hot keys
--------
procfs: /proc/acpi/ibm/hotkey
+
sysfs device attribute: hotkey_*
In a ThinkPad, the ACPI HKEY handler is responsible for communicating
@@ -181,7 +191,7 @@ firmware will behave in many situations.
The driver enables the HKEY ("hot key") event reporting automatically
when loaded, and disables it when it is removed.
-The driver will report HKEY events in the following format:
+The driver will report HKEY events in the following format::
ibm/hotkey HKEY 00000080 0000xxxx
@@ -217,9 +227,10 @@ ThinkPads, it is still possible to support some extra hotkeys by
polling the "CMOS NVRAM" at least 10 times per second. The driver
attempts to enables this functionality automatically when required.
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
-The following commands can be written to the /proc/acpi/ibm/hotkey file:
+The following commands can be written to the /proc/acpi/ibm/hotkey file::
echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
@@ -227,7 +238,7 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file:
echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
The following commands have been deprecated and will cause the kernel
-to log a warning:
+to log a warning::
echo enable > /proc/acpi/ibm/hotkey -- does nothing
echo disable > /proc/acpi/ibm/hotkey -- returns an error
@@ -237,7 +248,8 @@ maintain maximum bug-to-bug compatibility, it does not report any masks,
nor does it allow one to manipulate the hot key mask when the firmware
does not support masks at all, even if NVRAM polling is in use.
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
hotkey_bios_enabled:
DEPRECATED, WILL BE REMOVED SOON.
@@ -349,7 +361,8 @@ sysfs notes:
This attribute has poll()/select() support.
-input layer notes:
+input layer notes
+^^^^^^^^^^^^^^^^^
A Hot key is mapped to a single input layer EV_KEY event, possibly
followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
@@ -362,11 +375,13 @@ remapping KEY_UNKNOWN keys.
The events are available in an input device, with the following id:
- Bus: BUS_HOST
- vendor: 0x1014 (PCI_VENDOR_ID_IBM) or
+ ============== ==============================
+ Bus BUS_HOST
+ vendor 0x1014 (PCI_VENDOR_ID_IBM) or
0x17aa (PCI_VENDOR_ID_LENOVO)
- product: 0x5054 ("TP")
- version: 0x4101
+ product 0x5054 ("TP")
+ version 0x4101
+ ============== ==============================
The version will have its LSB incremented if the keymap changes in a
backwards-compatible way. The MSB shall always be 0x41 for this input
@@ -380,9 +395,10 @@ backwards-compatible change for this input device.
Thinkpad-acpi Hot Key event map (version 0x4101):
+======= ======= ============== ==============================================
ACPI Scan
event code Key Notes
-
+======= ======= ============== ==============================================
0x1001 0x00 FN+F1 -
0x1002 0x01 FN+F2 IBM: battery (rare)
@@ -426,7 +442,9 @@ event code Key Notes
or toggle screen expand
0x1009 0x08 FN+F9 -
- .. .. ..
+
+... ... ... ...
+
0x100B 0x0A FN+F11 -
0x100C 0x0B FN+F12 Sleep to disk. You are always
@@ -480,8 +498,11 @@ event code Key Notes
0x1018 0x17 THINKPAD ThinkPad/Access IBM/Lenovo key
0x1019 0x18 unknown
-.. .. ..
+
+... ... ...
+
0x1020 0x1F unknown
+======= ======= ============== ==============================================
The ThinkPad firmware does not allow one to differentiate when most hot
keys are pressed or released (either that, or we don't know how to, yet).
@@ -499,14 +520,17 @@ generate input device EV_KEY events.
In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW
events for switches:
+============== ==============================================
SW_RFKILL_ALL T60 and later hardware rfkill rocker switch
SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A
+============== ==============================================
-Non hotkey ACPI HKEY event map:
--------------------------------
+Non hotkey ACPI HKEY event map
+------------------------------
Events that are never propagated by the driver:
+====== ==================================================
0x2304 System is waking up from suspend to undock
0x2305 System is waking up from suspend to eject bay
0x2404 System is waking up from hibernation to undock
@@ -519,10 +543,12 @@ Events that are never propagated by the driver:
0x6000 KEYBOARD: Numlock key pressed
0x6005 KEYBOARD: Fn key pressed (TO BE VERIFIED)
0x7000 Radio Switch may have changed state
+====== ==================================================
Events that are propagated by the driver to userspace:
+====== =====================================================
0x2313 ALARM: System is waking up from suspend because
the battery is nearly empty
0x2413 ALARM: System is waking up from hibernation because
@@ -544,6 +570,7 @@ Events that are propagated by the driver to userspace:
0x6040 Nvidia Optimus/AC adapter related (TO BE VERIFIED)
0x60C0 X1 Yoga 2016, Tablet mode status changed
0x60F0 Thermal Transformation changed (GMTS, Windows)
+====== =====================================================
Battery nearly empty alarms are a last resort attempt to get the
operating system to hibernate or shutdown cleanly (0x2313), or shutdown
@@ -562,7 +589,8 @@ cycle, or a system shutdown. Obviously, something is very wrong if this
happens.
-Brightness hotkey notes:
+Brightness hotkey notes
+^^^^^^^^^^^^^^^^^^^^^^^
Don't mess with the brightness hotkeys in a Thinkpad. If you want
notifications for OSD, use the sysfs backlight class event support.
@@ -579,7 +607,9 @@ Bluetooth
---------
procfs: /proc/acpi/ibm/bluetooth
+
sysfs device attribute: bluetooth_enable (deprecated)
+
sysfs rfkill class: switch "tpacpi_bluetooth_sw"
This feature shows the presence and current state of a ThinkPad
@@ -588,22 +618,25 @@ Bluetooth device in the internal ThinkPad CDC slot.
If the ThinkPad supports it, the Bluetooth state is stored in NVRAM,
so it is kept across reboots and power-off.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
-If Bluetooth is installed, the following commands can be used:
+If Bluetooth is installed, the following commands can be used::
echo enable > /proc/acpi/ibm/bluetooth
echo disable > /proc/acpi/ibm/bluetooth
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
If the Bluetooth CDC card is installed, it can be enabled /
disabled through the "bluetooth_enable" thinkpad-acpi device
attribute, and its current status can also be queried.
enable:
- 0: disables Bluetooth / Bluetooth is disabled
- 1: enables Bluetooth / Bluetooth is enabled.
+
+ - 0: disables Bluetooth / Bluetooth is disabled
+ - 1: enables Bluetooth / Bluetooth is enabled.
Note: this interface has been superseded by the generic rfkill
class. It has been deprecated, and it will be removed in year
@@ -617,7 +650,7 @@ Video output control -- /proc/acpi/ibm/video
--------------------------------------------
This feature allows control over the devices used for video output -
-LCD, CRT or DVI (if available). The following commands are available:
+LCD, CRT or DVI (if available). The following commands are available::
echo lcd_enable > /proc/acpi/ibm/video
echo lcd_disable > /proc/acpi/ibm/video
@@ -630,9 +663,10 @@ LCD, CRT or DVI (if available). The following commands are available:
echo expand_toggle > /proc/acpi/ibm/video
echo video_switch > /proc/acpi/ibm/video
-NOTE: Access to this feature is restricted to processes owning the
-CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
-enough with some versions of X.org to crash it.
+NOTE:
+ Access to this feature is restricted to processes owning the
+ CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
+ enough with some versions of X.org to crash it.
Each video output device can be enabled or disabled individually.
Reading /proc/acpi/ibm/video shows the status of each device.
@@ -665,18 +699,21 @@ ThinkLight control
------------------
procfs: /proc/acpi/ibm/light
+
sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
The ThinkLight status can be read and set through the procfs interface. A
few models which do not make the status available will show the ThinkLight
-status as "unknown". The available commands are:
+status as "unknown". The available commands are::
echo on > /proc/acpi/ibm/light
echo off > /proc/acpi/ibm/light
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
The ThinkLight sysfs interface is documented by the LED class
documentation, in Documentation/leds/leds-class.rst. The ThinkLight LED name
@@ -691,6 +728,7 @@ CMOS/UCMS control
-----------------
procfs: /proc/acpi/ibm/cmos
+
sysfs device attribute: cmos_command
This feature is mostly used internally by the ACPI firmware to keep the legacy
@@ -707,16 +745,16 @@ The range of valid cmos command numbers is 0 to 21, but not all have an
effect and the behavior varies from model to model. Here is the behavior
on the X40 (tpb is the ThinkPad Buttons utility):
- 0 - Related to "Volume down" key press
- 1 - Related to "Volume up" key press
- 2 - Related to "Mute on" key press
- 3 - Related to "Access IBM" key press
- 4 - Related to "LCD brightness up" key press
- 5 - Related to "LCD brightness down" key press
- 11 - Related to "toggle screen expansion" key press/function
- 12 - Related to "ThinkLight on"
- 13 - Related to "ThinkLight off"
- 14 - Related to "ThinkLight" key press (toggle ThinkLight)
+ - 0 - Related to "Volume down" key press
+ - 1 - Related to "Volume up" key press
+ - 2 - Related to "Mute on" key press
+ - 3 - Related to "Access IBM" key press
+ - 4 - Related to "LCD brightness up" key press
+ - 5 - Related to "LCD brightness down" key press
+ - 11 - Related to "toggle screen expansion" key press/function
+ - 12 - Related to "ThinkLight on"
+ - 13 - Related to "ThinkLight off"
+ - 14 - Related to "ThinkLight" key press (toggle ThinkLight)
The cmos command interface is prone to firmware split-brain problems, as
in newer ThinkPads it is just a compatibility layer. Do not use it, it is
@@ -748,9 +786,10 @@ are aware of the consequences are welcome to enabling it.
Audio mute and microphone mute LEDs are supported, but currently not
visible to userspace. They are used by the snd-hda-intel audio driver.
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
-The available commands are:
+The available commands are::
echo '<LED number> on' >/proc/acpi/ibm/led
echo '<LED number> off' >/proc/acpi/ibm/led
@@ -760,23 +799,24 @@ The <LED number> range is 0 to 15. The set of LEDs that can be
controlled varies from model to model. Here is the common ThinkPad
mapping:
- 0 - power
- 1 - battery (orange)
- 2 - battery (green)
- 3 - UltraBase/dock
- 4 - UltraBay
- 5 - UltraBase battery slot
- 6 - (unknown)
- 7 - standby
- 8 - dock status 1
- 9 - dock status 2
- 10, 11 - (unknown)
- 12 - thinkvantage
- 13, 14, 15 - (unknown)
+ - 0 - power
+ - 1 - battery (orange)
+ - 2 - battery (green)
+ - 3 - UltraBase/dock
+ - 4 - UltraBay
+ - 5 - UltraBase battery slot
+ - 6 - (unknown)
+ - 7 - standby
+ - 8 - dock status 1
+ - 9 - dock status 2
+ - 10, 11 - (unknown)
+ - 12 - thinkvantage
+ - 13, 14, 15 - (unknown)
All of the above can be turned on and off and can be made to blink.
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
The ThinkPad LED sysfs interface is described in detail by the LED class
documentation, in Documentation/leds/leds-class.rst.
@@ -815,7 +855,7 @@ The BEEP method is used internally by the ACPI firmware to provide
audible alerts in various situations. This feature allows the same
sounds to be triggered manually.
-The commands are non-negative integer numbers:
+The commands are non-negative integer numbers::
echo <number> >/proc/acpi/ibm/beep
@@ -823,25 +863,26 @@ The valid <number> range is 0 to 17. Not all numbers trigger sounds
and the sounds vary from model to model. Here is the behavior on the
X40:
- 0 - stop a sound in progress (but use 17 to stop 16)
- 2 - two beeps, pause, third beep ("low battery")
- 3 - single beep
- 4 - high, followed by low-pitched beep ("unable")
- 5 - single beep
- 6 - very high, followed by high-pitched beep ("AC/DC")
- 7 - high-pitched beep
- 9 - three short beeps
- 10 - very long beep
- 12 - low-pitched beep
- 15 - three high-pitched beeps repeating constantly, stop with 0
- 16 - one medium-pitched beep repeating constantly, stop with 17
- 17 - stop 16
+ - 0 - stop a sound in progress (but use 17 to stop 16)
+ - 2 - two beeps, pause, third beep ("low battery")
+ - 3 - single beep
+ - 4 - high, followed by low-pitched beep ("unable")
+ - 5 - single beep
+ - 6 - very high, followed by high-pitched beep ("AC/DC")
+ - 7 - high-pitched beep
+ - 9 - three short beeps
+ - 10 - very long beep
+ - 12 - low-pitched beep
+ - 15 - three high-pitched beeps repeating constantly, stop with 0
+ - 16 - one medium-pitched beep repeating constantly, stop with 17
+ - 17 - stop 16
Temperature sensors
-------------------
procfs: /proc/acpi/ibm/thermal
+
sysfs device attributes: (hwmon "thinkpad") temp*_input
Most ThinkPads include six or more separate temperature sensors but only
@@ -850,10 +891,14 @@ feature shows readings from up to eight different sensors on older
ThinkPads, and up to sixteen different sensors on newer ThinkPads.
For example, on the X40, a typical output may be:
-temperatures: 42 42 45 41 36 -128 33 -128
+
+temperatures:
+ 42 42 45 41 36 -128 33 -128
On the T43/p, a typical output may be:
-temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
+
+temperatures:
+ 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
The mapping of thermal sensors to physical locations varies depending on
system-board model (and thus, on ThinkPad model).
@@ -863,46 +908,53 @@ tries to track down these locations for various models.
Most (newer?) models seem to follow this pattern:
-1: CPU
-2: (depends on model)
-3: (depends on model)
-4: GPU
-5: Main battery: main sensor
-6: Bay battery: main sensor
-7: Main battery: secondary sensor
-8: Bay battery: secondary sensor
-9-15: (depends on model)
+- 1: CPU
+- 2: (depends on model)
+- 3: (depends on model)
+- 4: GPU
+- 5: Main battery: main sensor
+- 6: Bay battery: main sensor
+- 7: Main battery: secondary sensor
+- 8: Bay battery: secondary sensor
+- 9-15: (depends on model)
For the R51 (source: Thomas Gruber):
-2: Mini-PCI
-3: Internal HDD
+
+- 2: Mini-PCI
+- 3: Internal HDD
For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
-2: System board, left side (near PCMCIA slot), reported as HDAPS temp
-3: PCMCIA slot
-9: MCH (northbridge) to DRAM Bus
-10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
- card, under touchpad
-11: Power regulator, underside of system board, below F2 key
+
+- 2: System board, left side (near PCMCIA slot), reported as HDAPS temp
+- 3: PCMCIA slot
+- 9: MCH (northbridge) to DRAM Bus
+- 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
+ card, under touchpad
+- 11: Power regulator, underside of system board, below F2 key
The A31 has a very atypical layout for the thermal sensors
(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
-1: CPU
-2: Main Battery: main sensor
-3: Power Converter
-4: Bay Battery: main sensor
-5: MCH (northbridge)
-6: PCMCIA/ambient
-7: Main Battery: secondary sensor
-8: Bay Battery: secondary sensor
+- 1: CPU
+- 2: Main Battery: main sensor
+- 3: Power Converter
+- 4: Bay Battery: main sensor
+- 5: MCH (northbridge)
+- 6: PCMCIA/ambient
+- 7: Main Battery: secondary sensor
+- 8: Bay Battery: secondary sensor
+
+
+Procfs notes
+^^^^^^^^^^^^
-Procfs notes:
Readings from sensors that are not available return -128.
No commands can be written to this file.
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
+
Sensors that are not available return the ENXIO error. This
status may change at runtime, as there are hotplug thermal
sensors, like those inside the batteries and docks.
@@ -921,6 +973,7 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec
Use it to determine the register holding the fan
speed on some models. To do that, do the following:
+
- make sure the battery is fully charged
- make sure the fan is running
- use above mentioned tool to read out the EC
@@ -941,6 +994,7 @@ LCD brightness control
----------------------
procfs: /proc/acpi/ibm/brightness
+
sysfs backlight device "thinkpad_screen"
This feature allows software control of the LCD brightness on ThinkPad
@@ -985,15 +1039,17 @@ brightness_enable=0 forces it to be disabled. brightness_enable=1
forces it to be enabled when available, even if the standard ACPI
interface is also available.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
- The available commands are:
+The available commands are::
echo up >/proc/acpi/ibm/brightness
echo down >/proc/acpi/ibm/brightness
echo 'level <level>' >/proc/acpi/ibm/brightness
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
The interface is implemented through the backlight sysfs class, which is
poorly documented at this time.
@@ -1038,6 +1094,7 @@ Volume control (Console Audio control)
--------------------------------------
procfs: /proc/acpi/ibm/volume
+
ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC"
NOTE: by default, the volume control interface operates in read-only
@@ -1053,7 +1110,8 @@ Software volume control should be done only in the main AC97/HDA
mixer.
-About the ThinkPad Console Audio control:
+About the ThinkPad Console Audio control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ThinkPads have a built-in amplifier and muting circuit that drives the
console headphone and speakers. This circuit is after the main AC97
@@ -1092,13 +1150,14 @@ normal key presses to the operating system (thinkpad-acpi is not
involved).
-The ThinkPad-ACPI volume control:
+The ThinkPad-ACPI volume control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The preferred way to interact with the Console Audio control is the
ALSA interface.
The legacy procfs interface allows one to read the current state,
-and if volume control is enabled, accepts the following commands:
+and if volume control is enabled, accepts the following commands::
echo up >/proc/acpi/ibm/volume
echo down >/proc/acpi/ibm/volume
@@ -1137,13 +1196,15 @@ Fan control and monitoring: fan speed, fan enable/disable
---------------------------------------------------------
procfs: /proc/acpi/ibm/fan
-sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1,
- pwm1_enable, fan2_input
+
+sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, pwm1_enable, fan2_input
+
sysfs hwmon driver attributes: fan_watchdog
-NOTE NOTE NOTE: fan control operations are disabled by default for
-safety reasons. To enable them, the module parameter "fan_control=1"
-must be given to thinkpad-acpi.
+NOTE NOTE NOTE:
+ fan control operations are disabled by default for
+ safety reasons. To enable them, the module parameter "fan_control=1"
+ must be given to thinkpad-acpi.
This feature attempts to show the current fan speed, control mode and
other fan data that might be available. The speed is read directly
@@ -1154,7 +1215,8 @@ value on other models.
Some Lenovo ThinkPads support a secondary fan. This fan cannot be
controlled separately, it shares the main fan control.
-Fan levels:
+Fan levels
+^^^^^^^^^^
Most ThinkPad fans work in "levels" at the firmware interface. Level 0
stops the fan. The higher the level, the higher the fan speed, although
@@ -1209,9 +1271,10 @@ therefore, not suitable to protect against fan mode changes made through
means other than the "enable", "disable", and "level" procfs fan
commands, or the hwmon fan control sysfs interface.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
-The fan may be enabled or disabled with the following commands:
+The fan may be enabled or disabled with the following commands::
echo enable >/proc/acpi/ibm/fan
echo disable >/proc/acpi/ibm/fan
@@ -1219,7 +1282,7 @@ The fan may be enabled or disabled with the following commands:
Placing a fan on level 0 is the same as disabling it. Enabling a fan
will try to place it in a safe level if it is too slow or disabled.
-The fan level can be controlled with the command:
+The fan level can be controlled with the command::
echo 'level <level>' > /proc/acpi/ibm/fan
@@ -1231,7 +1294,7 @@ compatibility.
On the X31 and X40 (and ONLY on those models), the fan speed can be
controlled to a certain degree. Once the fan is running, it can be
-forced to run faster or slower with the following command:
+forced to run faster or slower with the following command::
echo 'speed <speed>' > /proc/acpi/ibm/fan
@@ -1241,13 +1304,14 @@ effect or the fan speed eventually settles somewhere in that range. The
fan cannot be stopped or started with this command. This functionality
is incomplete, and not available through the sysfs interface.
-To program the safety watchdog, use the "watchdog" command.
+To program the safety watchdog, use the "watchdog" command::
echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
If you want to disable the watchdog, use 0 as the interval.
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
The sysfs interface follows the hwmon subsystem guidelines for the most
part, and the exception is the fan safety watchdog.
@@ -1261,10 +1325,10 @@ to the firmware).
Features not yet implemented by the driver return ENOSYS.
hwmon device attribute pwm1_enable:
- 0: PWM offline (fan is set to full-speed mode)
- 1: Manual PWM control (use pwm1 to set fan level)
- 2: Hardware PWM control (EC "auto" mode)
- 3: reserved (Software PWM control, not implemented yet)
+ - 0: PWM offline (fan is set to full-speed mode)
+ - 1: Manual PWM control (use pwm1 to set fan level)
+ - 2: Hardware PWM control (EC "auto" mode)
+ - 3: reserved (Software PWM control, not implemented yet)
Modes 0 and 2 are not supported by all ThinkPads, and the
driver is not always able to detect this. If it does know a
@@ -1304,7 +1368,9 @@ WAN
---
procfs: /proc/acpi/ibm/wan
+
sysfs device attribute: wwan_enable (deprecated)
+
sysfs rfkill class: switch "tpacpi_wwan_sw"
This feature shows the presence and current state of the built-in
@@ -1316,22 +1382,24 @@ so it is kept across reboots and power-off.
It was tested on a Lenovo ThinkPad X60. It should probably work on other
ThinkPad models which come with this module installed.
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
-If the W-WAN card is installed, the following commands can be used:
+If the W-WAN card is installed, the following commands can be used::
echo enable > /proc/acpi/ibm/wan
echo disable > /proc/acpi/ibm/wan
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
If the W-WAN card is installed, it can be enabled /
disabled through the "wwan_enable" thinkpad-acpi device
attribute, and its current status can also be queried.
enable:
- 0: disables WWAN card / WWAN card is disabled
- 1: enables WWAN card / WWAN card is enabled.
+ - 0: disables WWAN card / WWAN card is disabled
+ - 1: enables WWAN card / WWAN card is enabled.
Note: this interface has been superseded by the generic rfkill
class. It has been deprecated, and it will be removed in year
@@ -1354,7 +1422,8 @@ sysfs rfkill class: switch "tpacpi_uwb_sw"
This feature exports an rfkill controller for the UWB device, if one is
present and enabled in the BIOS.
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
rfkill controller switch "tpacpi_uwb_sw": refer to
Documentation/rfkill.txt for details.
@@ -1368,11 +1437,11 @@ This sysfs attribute controls the keyboard "face" that will be shown on the
Lenovo X1 Carbon 2nd gen (2014)'s adaptive keyboard. The value can be read
and set.
-1 = Home mode
-2 = Web-browser mode
-3 = Web-conference mode
-4 = Function mode
-5 = Layflat mode
+- 1 = Home mode
+- 2 = Web-browser mode
+- 3 = Web-conference mode
+- 4 = Function mode
+- 5 = Layflat mode
For more details about which buttons will appear depending on the mode, please
review the laptop's user guide:
@@ -1382,13 +1451,13 @@ Multiple Commands, Module Parameters
------------------------------------
Multiple commands can be written to the proc files in one shot by
-separating them with commas, for example:
+separating them with commas, for example::
echo enable,0xffff > /proc/acpi/ibm/hotkey
echo lcd_disable,crt_enable > /proc/acpi/ibm/video
Commands can also be specified when loading the thinkpad-acpi module,
-for example:
+for example::
modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
@@ -1397,14 +1466,16 @@ Enabling debugging output
-------------------------
The module takes a debug parameter which can be used to selectively
-enable various classes of debugging output, for example:
+enable various classes of debugging output, for example::
modprobe thinkpad_acpi debug=0xffff
will enable all debugging output classes. It takes a bitmask, so
to enable more than one output class, just add their values.
+ ============= ======================================
Debug bitmask Description
+ ============= ======================================
0x8000 Disclose PID of userspace programs
accessing some functions of the driver
0x0001 Initialization and probing
@@ -1415,6 +1486,7 @@ to enable more than one output class, just add their values.
0x0010 Fan control
0x0020 Backlight brightness
0x0040 Audio mixer/volume control
+ ============= ======================================
There is also a kernel build option to enable more debugging
information, which may be necessary to debug driver problems.
@@ -1432,8 +1504,10 @@ the module parameter force_load=1. Regardless of whether this works or
not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
-Sysfs interface changelog:
+Sysfs interface changelog
+^^^^^^^^^^^^^^^^^^^^^^^^^
+========= ===============================================================
0x000100: Initial sysfs support, as a single platform driver and
device.
0x000200: Hot key support for 32 hot keys, and radio slider switch
@@ -1485,3 +1559,4 @@ Sysfs interface changelog:
0x030000: Thermal and fan sysfs attributes were moved to the hwmon
device instead of being attached to the backing platform
device.
+========= ===============================================================
diff --git a/Documentation/laptops/toshiba_haps.txt b/Documentation/laptops/toshiba_haps.rst
similarity index 60%
rename from Documentation/laptops/toshiba_haps.txt
rename to Documentation/laptops/toshiba_haps.rst
index 0c1d88dedbde..11dfc428c080 100644
--- a/Documentation/laptops/toshiba_haps.txt
+++ b/Documentation/laptops/toshiba_haps.rst
@@ -1,18 +1,19 @@
-Kernel driver toshiba_haps
+====================================
Toshiba HDD Active Protection Sensor
====================================
+Kernel driver: toshiba_haps
+
Author: Azael Avalos <coproscefalo@gmail.com>
-0. Contents
------------
+.. 0. Contents
-1. Description
-2. Interface
-3. Accelerometer axes
-4. Supported devices
-5. Usage
+ 1. Description
+ 2. Interface
+ 3. Accelerometer axes
+ 4. Supported devices
+ 5. Usage
1. Description
@@ -32,17 +33,20 @@ file to set the desired protection level or sensor sensibility.
------------
This device comes with 3 methods:
-_STA - Checks existence of the device, returning Zero if the device does not
+
+==== =====================================================================
+_STA Checks existence of the device, returning Zero if the device does not
exists or is not supported.
-PTLV - Sets the desired protection level.
-RSSS - Shuts down the HDD protection interface for a few seconds,
+PTLV Sets the desired protection level.
+RSSS Shuts down the HDD protection interface for a few seconds,
then restores normal operation.
+==== =====================================================================
Note:
-The presence of Solid State Drives (SSD) can make this driver to fail loading,
-given the fact that such drives have no movable parts, and thus, not requiring
-any "protection" as well as failing during the evaluation of the _STA method
-found under this device.
+ The presence of Solid State Drives (SSD) can make this driver to fail loading,
+ given the fact that such drives have no movable parts, and thus, not requiring
+ any "protection" as well as failing during the evaluation of the _STA method
+ found under this device.
3. Accelerometer axes
@@ -66,11 +70,18 @@ conventional HDD and not only SSD, or a combination of both HDD and SSD.
--------
The sysfs files under /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/ are:
-protection_level - The protection_level is readable and writeable, and
+
+================ ============================================================
+protection_level The protection_level is readable and writeable, and
provides a way to let userspace query the current protection
level, as well as set the desired protection level, the
available protection levels are:
- 0 - Disabled | 1 - Low | 2 - Medium | 3 - High
-reset_protection - The reset_protection entry is writeable only, being "1"
+
+ ============ ======= ========== ========
+ 0 - Disabled 1 - Low 2 - Medium 3 - High
+ ============ ======= ========== ========
+
+reset_protection The reset_protection entry is writeable only, being "1"
the only parameter it accepts, it is used to trigger
a reset of the protection interface.
+================ ============================================================
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index 749322060f10..c5f0d44433a2 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -102,7 +102,7 @@ Changing this takes effect whenever an application requests memory.
block_dump
block_dump enables block I/O debugging when set to a nonzero value. More
-information on block I/O debugging is in Documentation/laptops/laptop-mode.txt.
+information on block I/O debugging is in Documentation/laptops/laptop-mode.rst.
==============================================================
@@ -286,7 +286,7 @@ shared memory segment using hugetlb page.
laptop_mode
laptop_mode is a knob that controls "laptop mode". All the things that are
-controlled by this knob are discussed in Documentation/laptops/laptop-mode.txt.
+controlled by this knob are discussed in Documentation/laptops/laptop-mode.rst.
==============================================================
diff --git a/MAINTAINERS b/MAINTAINERS
index 73000e7d7f19..c63b1b9cbed4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14753,7 +14753,7 @@ M: Mattia Dongili <malattia@linux.it>
L: platform-driver-x86@vger.kernel.org
W: http://www.linux.it/~malattia/wiki/index.php/Sony_drivers
S: Maintained
-F: Documentation/laptops/sony-laptop.txt
+F: Documentation/laptops/sony-laptop.rst
F: drivers/char/sonypi.c
F: drivers/platform/x86/sony-laptop.c
F: include/linux/sony-laptop.h
diff --git a/drivers/char/Kconfig b/drivers/char/Kconfig
index 466ebd84ad17..bb734066075f 100644
--- a/drivers/char/Kconfig
+++ b/drivers/char/Kconfig
@@ -382,7 +382,7 @@ config SONYPI
Device which can be found in many (all ?) Sony Vaio laptops.
If you have one of those laptops, read
- <file:Documentation/laptops/sonypi.txt>, and say Y or M here.
+ <file:Documentation/laptops/sonypi.rst>, and say Y or M here.
To compile this driver as a module, choose M here: the
module will be called sonypi.
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index 5d5cc6111081..e53c915761e7 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -451,7 +451,7 @@ config SONY_LAPTOP
screen brightness control, Fn keys and allows powering on/off some
devices.
- Read <file:Documentation/laptops/sony-laptop.txt> for more information.
+ Read <file:Documentation/laptops/sony-laptop.rst> for more information.
config SONYPI_COMPAT
bool "Sonypi compatibility"
@@ -503,7 +503,7 @@ config THINKPAD_ACPI
support for Fn-Fx key combinations, Bluetooth control, video
output switching, ThinkLight control, UltraBay eject and more.
For more information about this driver see
- <file:Documentation/laptops/thinkpad-acpi.txt> and
+ <file:Documentation/laptops/thinkpad-acpi.rst> and
<http://ibm-acpi.sf.net/> .
This driver was formerly known as ibm-acpi.
--
2.21.0
^ permalink raw reply related
* [PATCH v1 30/31] docs: xtensa: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Chris Zankel, Max Filippov, linux-xtensa
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the xtensa documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../xtensa/{atomctl.txt => atomctl.rst} | 13 +-
.../xtensa/{booting.txt => booting.rst} | 5 +-
Documentation/xtensa/index.rst | 12 ++
Documentation/xtensa/mmu.rst | 195 ++++++++++++++++++
Documentation/xtensa/mmu.txt | 189 -----------------
arch/xtensa/include/asm/initialize_mmu.h | 2 +-
6 files changed, 222 insertions(+), 194 deletions(-)
rename Documentation/xtensa/{atomctl.txt => atomctl.rst} (81%)
rename Documentation/xtensa/{booting.txt => booting.rst} (91%)
create mode 100644 Documentation/xtensa/index.rst
create mode 100644 Documentation/xtensa/mmu.rst
delete mode 100644 Documentation/xtensa/mmu.txt
diff --git a/Documentation/xtensa/atomctl.txt b/Documentation/xtensa/atomctl.rst
similarity index 81%
rename from Documentation/xtensa/atomctl.txt
rename to Documentation/xtensa/atomctl.rst
index 1da783ac200c..1ecbd0ba9a2e 100644
--- a/Documentation/xtensa/atomctl.txt
+++ b/Documentation/xtensa/atomctl.rst
@@ -1,3 +1,7 @@
+===========================================
+Atomic Operation Control (ATOMCTL) Register
+===========================================
+
We Have Atomic Operation Control (ATOMCTL) Register.
This register determines the effect of using a S32C1I instruction
with various combinations of:
@@ -8,7 +12,7 @@ with various combinations of:
2. With and without An Intelligent Memory Controller which
can do Atomic Transactions itself.
-The Core comes up with a default value of for the three types of cache ops:
+The Core comes up with a default value of for the three types of cache ops::
0x28: (WB: Internal, WT: Internal, BY:Exception)
@@ -30,15 +34,18 @@ CUSTOMER-WARNING:
Developers might find using RCW in Bypass mode convenient when testing
with the cache being bypassed; for example studying cache alias problems.
-See Section 4.3.12.4 of ISA; Bits:
+See Section 4.3.12.4 of ISA; Bits::
WB WT BY
5 4 | 3 2 | 1 0
+
+========= ================== ================== ===============
2 Bit
Field
Values WB - Write Back WT - Write Thru BY - Bypass
---------- --------------- ----------------- ----------------
+========= ================== ================== ===============
0 Exception Exception Exception
1 RCW Transaction RCW Transaction RCW Transaction
2 Internal Operation Internal Operation Reserved
3 Reserved Reserved Reserved
+========= ================== ================== ===============
diff --git a/Documentation/xtensa/booting.txt b/Documentation/xtensa/booting.rst
similarity index 91%
rename from Documentation/xtensa/booting.txt
rename to Documentation/xtensa/booting.rst
index 402b33a2619f..e1b83707e5b6 100644
--- a/Documentation/xtensa/booting.txt
+++ b/Documentation/xtensa/booting.rst
@@ -1,10 +1,13 @@
-Passing boot parameters to the kernel.
+=====================================
+Passing boot parameters to the kernel
+=====================================
Boot parameters are represented as a TLV list in the memory. Please see
arch/xtensa/include/asm/bootparam.h for definition of the bp_tag structure and
tag value constants. First entry in the list must have type BP_TAG_FIRST, last
entry must have type BP_TAG_LAST. The address of the first list entry is
passed to the kernel in the register a2. The address type depends on MMU type:
+
- For configurations without MMU, with region protection or with MPU the
address must be the physical address.
- For configurations with region translarion MMU or with MMUv3 and CONFIG_MMU=n
diff --git a/Documentation/xtensa/index.rst b/Documentation/xtensa/index.rst
new file mode 100644
index 000000000000..5a24e365e35f
--- /dev/null
+++ b/Documentation/xtensa/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+===================
+Xtensa Architecture
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ atomctl
+ booting
+ mmu
diff --git a/Documentation/xtensa/mmu.rst b/Documentation/xtensa/mmu.rst
new file mode 100644
index 000000000000..e52a12960fdc
--- /dev/null
+++ b/Documentation/xtensa/mmu.rst
@@ -0,0 +1,195 @@
+=============================
+MMUv3 initialization sequence
+=============================
+
+The code in the initialize_mmu macro sets up MMUv3 memory mapping
+identically to MMUv2 fixed memory mapping. Depending on
+CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is
+located in addresses it was linked for (symbol undefined), or not
+(symbol defined), so it needs to be position-independent.
+
+The code has the following assumptions:
+
+ - This code fragment is run only on an MMU v3.
+ - TLBs are in their reset state.
+ - ITLBCFG and DTLBCFG are zero (reset state).
+ - RASID is 0x04030201 (reset state).
+ - PS.RING is zero (reset state).
+ - LITBASE is zero (reset state, PC-relative literals); required to be PIC.
+
+TLB setup proceeds along the following steps.
+
+ Legend:
+
+ - VA = virtual address (two upper nibbles of it);
+ - PA = physical address (two upper nibbles of it);
+ - pc = physical range that contains this code;
+
+After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff
+or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below
+0x40000000 or above. That address corresponds to next instruction to execute
+in this code. After step 4, we jump to intended (linked) address of this code.
+The scheme below assumes that the kernel is loaded below 0x40000000.
+
+ ====== ===== ===== ===== ===== ====== ===== =====
+ - Step0 Step1 Step2 Step3 Step4 Step5
+
+ VA PA PA PA PA VA PA PA
+ ====== ===== ===== ===== ===== ====== ===== =====
+ E0..FF -> E0 -> E0 -> E0 F0..FF -> F0 -> F0
+ C0..DF -> C0 -> C0 -> C0 E0..EF -> F0 -> F0
+ A0..BF -> A0 -> A0 -> A0 D8..DF -> 00 -> 00
+ 80..9F -> 80 -> 80 -> 80 D0..D7 -> 00 -> 00
+ 60..7F -> 60 -> 60 -> 60
+ 40..5F -> 40 -> pc -> pc 40..5F -> pc
+ 20..3F -> 20 -> 20 -> 20
+ 00..1F -> 00 -> 00 -> 00
+ ====== ===== ===== ===== ===== ====== ===== =====
+
+The default location of IO peripherals is above 0xf0000000. This may be changed
+using a "ranges" property in a device tree simple-bus node. See the Devicetree
+Specification, section 4.5 for details on the syntax and semantics of
+simple-bus nodes. The following limitations apply:
+
+1. Only top level simple-bus nodes are considered
+
+2. Only one (first) simple-bus node is considered
+
+3. Empty "ranges" properties are not supported
+
+4. Only the first triplet in the "ranges" property is considered
+
+5. The parent-bus-address value is rounded down to the nearest 256MB boundary
+
+6. The IO area covers the entire 256MB segment of parent-bus-address; the
+ "ranges" triplet length field is ignored
+
+
+MMUv3 address space layouts.
+============================
+
+Default MMUv2-compatible layout::
+
+ Symbol VADDR Size
+ +------------------+
+ | Userspace | 0x00000000 TASK_SIZE
+ +------------------+ 0x40000000
+ +------------------+
+ | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
+ +------------------+
+ | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
+ +------------------+ 0x8e400000
+ +------------------+
+ | VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB
+ +------------------+ VMALLOC_END
+ | Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE
+ | remap area 1 |
+ +------------------+
+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
+ | remap area 2 |
+ +------------------+
+ +------------------+
+ | KMAP area | PKMAP_BASE PTRS_PER_PTE *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ | | (4MB * DCACHE_N_COLORS)
+ +------------------+
+ | Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
+ | | NR_CPUS *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ +------------------+ FIXADDR_TOP 0xcffff000
+ +------------------+
+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xd0000000 128MB
+ +------------------+
+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xd8000000 128MB
+ +------------------+
+ | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
+ +------------------+
+ | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
+ +------------------+
+
+
+256MB cached + 256MB uncached layout::
+
+ Symbol VADDR Size
+ +------------------+
+ | Userspace | 0x00000000 TASK_SIZE
+ +------------------+ 0x40000000
+ +------------------+
+ | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
+ +------------------+
+ | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
+ +------------------+ 0x8e400000
+ +------------------+
+ | VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB
+ +------------------+ VMALLOC_END
+ | Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE
+ | remap area 1 |
+ +------------------+
+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
+ | remap area 2 |
+ +------------------+
+ +------------------+
+ | KMAP area | PKMAP_BASE PTRS_PER_PTE *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ | | (4MB * DCACHE_N_COLORS)
+ +------------------+
+ | Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
+ | | NR_CPUS *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ +------------------+ FIXADDR_TOP 0xaffff000
+ +------------------+
+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xb0000000 256MB
+ +------------------+
+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 256MB
+ +------------------+
+ +------------------+
+ | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
+ +------------------+
+ | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
+ +------------------+
+
+
+512MB cached + 512MB uncached layout::
+
+ Symbol VADDR Size
+ +------------------+
+ | Userspace | 0x00000000 TASK_SIZE
+ +------------------+ 0x40000000
+ +------------------+
+ | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
+ +------------------+
+ | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
+ +------------------+ 0x8e400000
+ +------------------+
+ | VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB
+ +------------------+ VMALLOC_END
+ | Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE
+ | remap area 1 |
+ +------------------+
+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
+ | remap area 2 |
+ +------------------+
+ +------------------+
+ | KMAP area | PKMAP_BASE PTRS_PER_PTE *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ | | (4MB * DCACHE_N_COLORS)
+ +------------------+
+ | Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
+ | | NR_CPUS *
+ | | DCACHE_N_COLORS *
+ | | PAGE_SIZE
+ +------------------+ FIXADDR_TOP 0x9ffff000
+ +------------------+
+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xa0000000 512MB
+ +------------------+
+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 512MB
+ +------------------+
+ | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
+ +------------------+
+ | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
+ +------------------+
diff --git a/Documentation/xtensa/mmu.txt b/Documentation/xtensa/mmu.txt
deleted file mode 100644
index 318114de63f3..000000000000
--- a/Documentation/xtensa/mmu.txt
+++ /dev/null
@@ -1,189 +0,0 @@
-MMUv3 initialization sequence.
-
-The code in the initialize_mmu macro sets up MMUv3 memory mapping
-identically to MMUv2 fixed memory mapping. Depending on
-CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is
-located in addresses it was linked for (symbol undefined), or not
-(symbol defined), so it needs to be position-independent.
-
-The code has the following assumptions:
- This code fragment is run only on an MMU v3.
- TLBs are in their reset state.
- ITLBCFG and DTLBCFG are zero (reset state).
- RASID is 0x04030201 (reset state).
- PS.RING is zero (reset state).
- LITBASE is zero (reset state, PC-relative literals); required to be PIC.
-
-TLB setup proceeds along the following steps.
-
- Legend:
- VA = virtual address (two upper nibbles of it);
- PA = physical address (two upper nibbles of it);
- pc = physical range that contains this code;
-
-After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff
-or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below
-0x40000000 or above. That address corresponds to next instruction to execute
-in this code. After step 4, we jump to intended (linked) address of this code.
-The scheme below assumes that the kernel is loaded below 0x40000000.
-
- Step0 Step1 Step2 Step3 Step4 Step5
- ===== ===== ===== ===== ===== =====
- VA PA PA PA PA VA PA PA
- ------ -- -- -- -- ------ -- --
- E0..FF -> E0 -> E0 -> E0 F0..FF -> F0 -> F0
- C0..DF -> C0 -> C0 -> C0 E0..EF -> F0 -> F0
- A0..BF -> A0 -> A0 -> A0 D8..DF -> 00 -> 00
- 80..9F -> 80 -> 80 -> 80 D0..D7 -> 00 -> 00
- 60..7F -> 60 -> 60 -> 60
- 40..5F -> 40 -> pc -> pc 40..5F -> pc
- 20..3F -> 20 -> 20 -> 20
- 00..1F -> 00 -> 00 -> 00
-
-The default location of IO peripherals is above 0xf0000000. This may be changed
-using a "ranges" property in a device tree simple-bus node. See the Devicetree
-Specification, section 4.5 for details on the syntax and semantics of
-simple-bus nodes. The following limitations apply:
-
-1. Only top level simple-bus nodes are considered
-
-2. Only one (first) simple-bus node is considered
-
-3. Empty "ranges" properties are not supported
-
-4. Only the first triplet in the "ranges" property is considered
-
-5. The parent-bus-address value is rounded down to the nearest 256MB boundary
-
-6. The IO area covers the entire 256MB segment of parent-bus-address; the
- "ranges" triplet length field is ignored
-
-
-MMUv3 address space layouts.
-============================
-
-Default MMUv2-compatible layout.
-
- Symbol VADDR Size
-+------------------+
-| Userspace | 0x00000000 TASK_SIZE
-+------------------+ 0x40000000
-+------------------+
-| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
-+------------------+ 0x8e400000
-+------------------+
-| VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB
-+------------------+ VMALLOC_END
-| Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE
-| remap area 1 |
-+------------------+
-| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
-| remap area 2 |
-+------------------+
-+------------------+
-| KMAP area | PKMAP_BASE PTRS_PER_PTE *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-| | (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
-| | NR_CPUS *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-+------------------+ FIXADDR_TOP 0xcffff000
-+------------------+
-| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xd0000000 128MB
-+------------------+
-| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xd8000000 128MB
-+------------------+
-| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
-+------------------+
-| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
-+------------------+
-
-
-256MB cached + 256MB uncached layout.
-
- Symbol VADDR Size
-+------------------+
-| Userspace | 0x00000000 TASK_SIZE
-+------------------+ 0x40000000
-+------------------+
-| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
-+------------------+ 0x8e400000
-+------------------+
-| VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB
-+------------------+ VMALLOC_END
-| Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE
-| remap area 1 |
-+------------------+
-| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
-| remap area 2 |
-+------------------+
-+------------------+
-| KMAP area | PKMAP_BASE PTRS_PER_PTE *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-| | (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
-| | NR_CPUS *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-+------------------+ FIXADDR_TOP 0xaffff000
-+------------------+
-| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xb0000000 256MB
-+------------------+
-| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 256MB
-+------------------+
-+------------------+
-| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
-+------------------+
-| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
-+------------------+
-
-
-512MB cached + 512MB uncached layout.
-
- Symbol VADDR Size
-+------------------+
-| Userspace | 0x00000000 TASK_SIZE
-+------------------+ 0x40000000
-+------------------+
-| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE
-+------------------+ 0x8e400000
-+------------------+
-| VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB
-+------------------+ VMALLOC_END
-| Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE
-| remap area 1 |
-+------------------+
-| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE
-| remap area 2 |
-+------------------+
-+------------------+
-| KMAP area | PKMAP_BASE PTRS_PER_PTE *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-| | (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area | FIXADDR_START KM_TYPE_NR *
-| | NR_CPUS *
-| | DCACHE_N_COLORS *
-| | PAGE_SIZE
-+------------------+ FIXADDR_TOP 0x9ffff000
-+------------------+
-| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xa0000000 512MB
-+------------------+
-| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 512MB
-+------------------+
-| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB
-+------------------+
-| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB
-+------------------+
diff --git a/arch/xtensa/include/asm/initialize_mmu.h b/arch/xtensa/include/asm/initialize_mmu.h
index 323d05789159..3b054d2bede0 100644
--- a/arch/xtensa/include/asm/initialize_mmu.h
+++ b/arch/xtensa/include/asm/initialize_mmu.h
@@ -42,7 +42,7 @@
#if XCHAL_HAVE_S32C1I && (XCHAL_HW_MIN_VERSION >= XTENSA_HWVERSION_RC_2009_0)
/*
* We Have Atomic Operation Control (ATOMCTL) Register; Initialize it.
- * For details see Documentation/xtensa/atomctl.txt
+ * For details see Documentation/xtensa/atomctl.rst
*/
#if XCHAL_DCACHE_IS_COHERENT
movi a3, 0x25 /* For SMP/MX -- internal for writeback,
--
2.21.0
^ permalink raw reply related
* [PATCH v1 29/31] docs: nvdimm: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Dan Williams, Vishal Verma, Dave Jiang,
Keith Busch, Ira Weiny, linux-nvdimm
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the mtd documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/nvdimm/{btt.txt => btt.rst} | 140 ++---
Documentation/nvdimm/index.rst | 12 +
.../nvdimm/{nvdimm.txt => nvdimm.rst} | 518 ++++++++++--------
.../nvdimm/{security.txt => security.rst} | 4 +-
drivers/nvdimm/Kconfig | 2 +-
5 files changed, 387 insertions(+), 289 deletions(-)
rename Documentation/nvdimm/{btt.txt => btt.rst} (71%)
create mode 100644 Documentation/nvdimm/index.rst
rename Documentation/nvdimm/{nvdimm.txt => nvdimm.rst} (60%)
rename Documentation/nvdimm/{security.txt => security.rst} (99%)
diff --git a/Documentation/nvdimm/btt.txt b/Documentation/nvdimm/btt.rst
similarity index 71%
rename from Documentation/nvdimm/btt.txt
rename to Documentation/nvdimm/btt.rst
index e293fb664924..2d8269f834bd 100644
--- a/Documentation/nvdimm/btt.txt
+++ b/Documentation/nvdimm/btt.rst
@@ -1,9 +1,10 @@
+=============================
BTT - Block Translation Table
=============================
1. Introduction
----------------
+===============
Persistent memory based storage is able to perform IO at byte (or more
accurately, cache line) granularity. However, we often want to expose such
@@ -25,7 +26,7 @@ provides atomic sector updates.
2. Static Layout
-----------------
+================
The underlying storage on which a BTT can be laid out is not limited in any way.
The BTT, however, splits the available space into chunks of up to 512 GiB,
@@ -33,43 +34,43 @@ called "Arenas".
Each arena follows the same layout for its metadata, and all references in an
arena are internal to it (with the exception of one field that points to the
-next arena). The following depicts the "On-disk" metadata layout:
+next arena). The following depicts the "On-disk" metadata layout::
- Backing Store +-------> Arena
-+---------------+ | +------------------+
-| | | | Arena info block |
-| Arena 0 +---+ | 4K |
-| 512G | +------------------+
-| | | |
-+---------------+ | |
-| | | |
-| Arena 1 | | Data Blocks |
-| 512G | | |
-| | | |
-+---------------+ | |
-| . | | |
-| . | | |
-| . | | |
-| | | |
-| | | |
-+---------------+ +------------------+
- | |
- | BTT Map |
- | |
- | |
- +------------------+
- | |
- | BTT Flog |
- | |
- +------------------+
- | Info block copy |
- | 4K |
- +------------------+
+ Backing Store +-------> Arena
+ +---------------+ | +------------------+
+ | | | | Arena info block |
+ | Arena 0 +---+ | 4K |
+ | 512G | +------------------+
+ | | | |
+ +---------------+ | |
+ | | | |
+ | Arena 1 | | Data Blocks |
+ | 512G | | |
+ | | | |
+ +---------------+ | |
+ | . | | |
+ | . | | |
+ | . | | |
+ | | | |
+ | | | |
+ +---------------+ +------------------+
+ | |
+ | BTT Map |
+ | |
+ | |
+ +------------------+
+ | |
+ | BTT Flog |
+ | |
+ +------------------+
+ | Info block copy |
+ | 4K |
+ +------------------+
3. Theory of Operation
-----------------------
+======================
a. The BTT Map
@@ -79,31 +80,37 @@ The map is a simple lookup/indirection table that maps an LBA to an internal
block. Each map entry is 32 bits. The two most significant bits are special
flags, and the remaining form the internal block number.
+======== =============================================================
Bit Description
-31 - 30 : Error and Zero flags - Used in the following way:
- Bit Description
- 31 30
- -----------------------------------------------------------------------
- 00 Initial state. Reads return zeroes; Premap = Postmap
- 01 Zero state: Reads return zeroes
- 10 Error state: Reads fail; Writes clear 'E' bit
- 11 Normal Block – has valid postmap
+======== =============================================================
+31 - 30 Error and Zero flags - Used in the following way:
+ == == ====================================================
+ 31 30 Description
+ == == ====================================================
+ 0 0 Initial state. Reads return zeroes; Premap = Postmap
+ 0 1 Zero state: Reads return zeroes
+ 1 0 Error state: Reads fail; Writes clear 'E' bit
+ 1 1 Normal Block – has valid postmap
+ == == ====================================================
-29 - 0 : Mappings to internal 'postmap' blocks
+29 - 0 Mappings to internal 'postmap' blocks
+======== =============================================================
Some of the terminology that will be subsequently used:
-External LBA : LBA as made visible to upper layers.
-ABA : Arena Block Address - Block offset/number within an arena
-Premap ABA : The block offset into an arena, which was decided upon by range
+============ ================================================================
+External LBA LBA as made visible to upper layers.
+ABA Arena Block Address - Block offset/number within an arena
+Premap ABA The block offset into an arena, which was decided upon by range
checking the External LBA
-Postmap ABA : The block number in the "Data Blocks" area obtained after
+Postmap ABA The block number in the "Data Blocks" area obtained after
indirection from the map
-nfree : The number of free blocks that are maintained at any given time.
+nfree The number of free blocks that are maintained at any given time.
This is the number of concurrent writes that can happen to the
arena.
+============ ================================================================
For example, after adding a BTT, we surface a disk of 1024G. We get a read for
@@ -121,19 +128,21 @@ i.e. Every write goes to a "free" block. A running list of free blocks is
maintained in the form of the BTT flog. 'Flog' is a combination of the words
"free list" and "log". The flog contains 'nfree' entries, and an entry contains:
-lba : The premap ABA that is being written to
-old_map : The old postmap ABA - after 'this' write completes, this will be a
+======== =====================================================================
+lba The premap ABA that is being written to
+old_map The old postmap ABA - after 'this' write completes, this will be a
free block.
-new_map : The new postmap ABA. The map will up updated to reflect this
+new_map The new postmap ABA. The map will up updated to reflect this
lba->postmap_aba mapping, but we log it here in case we have to
recover.
-seq : Sequence number to mark which of the 2 sections of this flog entry is
+seq Sequence number to mark which of the 2 sections of this flog entry is
valid/newest. It cycles between 01->10->11->01 (binary) under normal
operation, with 00 indicating an uninitialized state.
-lba' : alternate lba entry
-old_map': alternate old postmap entry
-new_map': alternate new postmap entry
-seq' : alternate sequence number.
+lba' alternate lba entry
+old_map' alternate old postmap entry
+new_map' alternate new postmap entry
+seq' alternate sequence number.
+======== =====================================================================
Each of the above fields is 32-bit, making one entry 32 bytes. Entries are also
padded to 64 bytes to avoid cache line sharing or aliasing. Flog updates are
@@ -147,8 +156,10 @@ c. The concept of lanes
While 'nfree' describes the number of concurrent IOs an arena can process
concurrently, 'nlanes' is the number of IOs the BTT device as a whole can
-process.
- nlanes = min(nfree, num_cpus)
+process::
+
+ nlanes = min(nfree, num_cpus)
+
A lane number is obtained at the start of any IO, and is used for indexing into
all the on-disk and in-memory data structures for the duration of the IO. If
there are more CPUs than the max number of available lanes, than lanes are
@@ -180,10 +191,10 @@ e. In-memory data structure: map locks
--------------------------------------
Consider a case where two writer threads are writing to the same LBA. There can
-be a race in the following sequence of steps:
+be a race in the following sequence of steps::
-free[lane] = map[premap_aba]
-map[premap_aba] = postmap_aba
+ free[lane] = map[premap_aba]
+ map[premap_aba] = postmap_aba
Both threads can update their respective free[lane] with the same old, freed
postmap_aba. This has made the layout inconsistent by losing a free entry, and
@@ -202,6 +213,7 @@ On startup, we analyze the BTT flog to create our list of free blocks. We walk
through all the entries, and for each lane, of the set of two possible
'sections', we always look at the most recent one only (based on the sequence
number). The reconstruction rules/steps are simple:
+
- Read map[log_entry.lba].
- If log_entry.new matches the map entry, then log_entry.old is free.
- If log_entry.new does not match the map entry, then log_entry.new is free.
@@ -228,7 +240,7 @@ Write:
1. Convert external LBA to Arena number + pre-map ABA
2. Get a lane (and take lane_lock)
3. Use lane to index into in-memory free list and obtain a new block, next flog
- index, next sequence number
+ index, next sequence number
4. Scan the RTT to check if free block is present, and spin/wait if it is.
5. Write data to this free block
6. Read map to get the existing post-map ABA entry for this pre-map ABA
@@ -245,6 +257,7 @@ Write:
An arena would be in an error state if any of the metadata is corrupted
irrecoverably, either due to a bug or a media error. The following conditions
indicate an error:
+
- Info block checksum does not match (and recovering from the copy also fails)
- All internal available blocks are not uniquely and entirely addressed by the
sum of mapped blocks and free blocks (from the BTT flog).
@@ -263,11 +276,10 @@ The BTT can be set up on any disk (namespace) exposed by the libnvdimm subsystem
(pmem, or blk mode). The easiest way to set up such a namespace is using the
'ndctl' utility [1]:
-For example, the ndctl command line to setup a btt with a 4k sector size is:
+For example, the ndctl command line to setup a btt with a 4k sector size is::
ndctl create-namespace -f -e namespace0.0 -m sector -l 4k
See ndctl create-namespace --help for more options.
[1]: https://github.com/pmem/ndctl
-
diff --git a/Documentation/nvdimm/index.rst b/Documentation/nvdimm/index.rst
new file mode 100644
index 000000000000..1a3402d3775e
--- /dev/null
+++ b/Documentation/nvdimm/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+===================================
+Non-Volatile Memory Device (NVDIMM)
+===================================
+
+.. toctree::
+ :maxdepth: 1
+
+ nvdimm
+ btt
+ security
diff --git a/Documentation/nvdimm/nvdimm.txt b/Documentation/nvdimm/nvdimm.rst
similarity index 60%
rename from Documentation/nvdimm/nvdimm.txt
rename to Documentation/nvdimm/nvdimm.rst
index 1669f626b037..08f855cbb4e6 100644
--- a/Documentation/nvdimm/nvdimm.txt
+++ b/Documentation/nvdimm/nvdimm.rst
@@ -1,8 +1,14 @@
- LIBNVDIMM: Non-Volatile Devices
- libnvdimm - kernel / libndctl - userspace helper library
- linux-nvdimm@lists.01.org
- v13
+===============================
+LIBNVDIMM: Non-Volatile Devices
+===============================
+libnvdimm - kernel / libndctl - userspace helper library
+
+linux-nvdimm@lists.01.org
+
+Version 13
+
+.. contents:
Glossary
Overview
@@ -40,49 +46,57 @@
Glossary
---------
-
-PMEM: A system-physical-address range where writes are persistent. A
-block device composed of PMEM is capable of DAX. A PMEM address range
-may span an interleave of several DIMMs.
-
-BLK: A set of one or more programmable memory mapped apertures provided
-by a DIMM to access its media. This indirection precludes the
-performance benefit of interleaving, but enables DIMM-bounded failure
-modes.
-
-DPA: DIMM Physical Address, is a DIMM-relative offset. With one DIMM in
-the system there would be a 1:1 system-physical-address:DPA association.
-Once more DIMMs are added a memory controller interleave must be
-decoded to determine the DPA associated with a given
-system-physical-address. BLK capacity always has a 1:1 relationship
-with a single-DIMM's DPA range.
-
-DAX: File system extensions to bypass the page cache and block layer to
-mmap persistent memory, from a PMEM block device, directly into a
-process address space.
-
-DSM: Device Specific Method: ACPI method to to control specific
-device - in this case the firmware.
-
-DCR: NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
-It defines a vendor-id, device-id, and interface format for a given DIMM.
-
-BTT: Block Translation Table: Persistent memory is byte addressable.
-Existing software may have an expectation that the power-fail-atomicity
-of writes is at least one sector, 512 bytes. The BTT is an indirection
-table with atomic update semantics to front a PMEM/BLK block device
-driver and present arbitrary atomic sector sizes.
-
-LABEL: Metadata stored on a DIMM device that partitions and identifies
-(persistently names) storage between PMEM and BLK. It also partitions
-BLK storage to host BTTs with different parameters per BLK-partition.
-Note that traditional partition tables, GPT/MBR, are layered on top of a
-BLK or PMEM device.
+========
+
+PMEM:
+ A system-physical-address range where writes are persistent. A
+ block device composed of PMEM is capable of DAX. A PMEM address range
+ may span an interleave of several DIMMs.
+
+BLK:
+ A set of one or more programmable memory mapped apertures provided
+ by a DIMM to access its media. This indirection precludes the
+ performance benefit of interleaving, but enables DIMM-bounded failure
+ modes.
+
+DPA:
+ DIMM Physical Address, is a DIMM-relative offset. With one DIMM in
+ the system there would be a 1:1 system-physical-address:DPA association.
+ Once more DIMMs are added a memory controller interleave must be
+ decoded to determine the DPA associated with a given
+ system-physical-address. BLK capacity always has a 1:1 relationship
+ with a single-DIMM's DPA range.
+
+DAX:
+ File system extensions to bypass the page cache and block layer to
+ mmap persistent memory, from a PMEM block device, directly into a
+ process address space.
+
+DSM:
+ Device Specific Method: ACPI method to to control specific
+ device - in this case the firmware.
+
+DCR:
+ NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
+ It defines a vendor-id, device-id, and interface format for a given DIMM.
+
+BTT:
+ Block Translation Table: Persistent memory is byte addressable.
+ Existing software may have an expectation that the power-fail-atomicity
+ of writes is at least one sector, 512 bytes. The BTT is an indirection
+ table with atomic update semantics to front a PMEM/BLK block device
+ driver and present arbitrary atomic sector sizes.
+
+LABEL:
+ Metadata stored on a DIMM device that partitions and identifies
+ (persistently names) storage between PMEM and BLK. It also partitions
+ BLK storage to host BTTs with different parameters per BLK-partition.
+ Note that traditional partition tables, GPT/MBR, are layered on top of a
+ BLK or PMEM device.
Overview
---------
+========
The LIBNVDIMM subsystem provides support for three types of NVDIMMs, namely,
PMEM, BLK, and NVDIMM devices that can simultaneously support both PMEM
@@ -96,19 +110,30 @@ accessible via BLK. When that occurs a LABEL is needed to reserve DPA
for exclusive access via one mode a time.
Supporting Documents
-ACPI 6: http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
-NVDIMM Namespace: http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
-DSM Interface Example: http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
-Driver Writer's Guide: http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
+--------------------
+
+ACPI 6:
+ http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
+NVDIMM Namespace:
+ http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
+DSM Interface Example:
+ http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
+Driver Writer's Guide:
+ http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
Git Trees
-LIBNVDIMM: https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
-LIBNDCTL: https://github.com/pmem/ndctl.git
-PMEM: https://github.com/01org/prd
+---------
+
+LIBNVDIMM:
+ https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
+LIBNDCTL:
+ https://github.com/pmem/ndctl.git
+PMEM:
+ https://github.com/01org/prd
LIBNVDIMM PMEM and BLK
-------------------
+======================
Prior to the arrival of the NFIT, non-volatile memory was described to a
system in various ad-hoc ways. Usually only the bare minimum was
@@ -122,38 +147,39 @@ For each NVDIMM access method (PMEM, BLK), LIBNVDIMM provides a block
device driver:
1. PMEM (nd_pmem.ko): Drives a system-physical-address range. This
- range is contiguous in system memory and may be interleaved (hardware
- memory controller striped) across multiple DIMMs. When interleaved the
- platform may optionally provide details of which DIMMs are participating
- in the interleave.
+ range is contiguous in system memory and may be interleaved (hardware
+ memory controller striped) across multiple DIMMs. When interleaved the
+ platform may optionally provide details of which DIMMs are participating
+ in the interleave.
- Note that while LIBNVDIMM describes system-physical-address ranges that may
- alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
- alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
- distinction. The different device-types are an implementation detail
- that userspace can exploit to implement policies like "only interface
- with address ranges from certain DIMMs". It is worth noting that when
- aliasing is present and a DIMM lacks a label, then no block device can
- be created by default as userspace needs to do at least one allocation
- of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once
- registered, can be immediately attached to nd_pmem.
+ Note that while LIBNVDIMM describes system-physical-address ranges that may
+ alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
+ alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
+ distinction. The different device-types are an implementation detail
+ that userspace can exploit to implement policies like "only interface
+ with address ranges from certain DIMMs". It is worth noting that when
+ aliasing is present and a DIMM lacks a label, then no block device can
+ be created by default as userspace needs to do at least one allocation
+ of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once
+ registered, can be immediately attached to nd_pmem.
2. BLK (nd_blk.ko): This driver performs I/O using a set of platform
- defined apertures. A set of apertures will access just one DIMM.
- Multiple windows (apertures) allow multiple concurrent accesses, much like
- tagged-command-queuing, and would likely be used by different threads or
- different CPUs.
+ defined apertures. A set of apertures will access just one DIMM.
+ Multiple windows (apertures) allow multiple concurrent accesses, much like
+ tagged-command-queuing, and would likely be used by different threads or
+ different CPUs.
- The NFIT specification defines a standard format for a BLK-aperture, but
- the spec also allows for vendor specific layouts, and non-NFIT BLK
- implementations may have other designs for BLK I/O. For this reason
- "nd_blk" calls back into platform-specific code to perform the I/O.
- One such implementation is defined in the "Driver Writer's Guide" and "DSM
- Interface Example".
+ The NFIT specification defines a standard format for a BLK-aperture, but
+ the spec also allows for vendor specific layouts, and non-NFIT BLK
+ implementations may have other designs for BLK I/O. For this reason
+ "nd_blk" calls back into platform-specific code to perform the I/O.
+
+ One such implementation is defined in the "Driver Writer's Guide" and "DSM
+ Interface Example".
Why BLK?
---------
+========
While PMEM provides direct byte-addressable CPU-load/store access to
NVDIMM storage, it does not provide the best system RAS (recovery,
@@ -162,12 +188,15 @@ system-physical-address address causes a CPU exception while an access
to a corrupted address through an BLK-aperture causes that block window
to raise an error status in a register. The latter is more aligned with
the standard error model that host-bus-adapter attached disks present.
+
Also, if an administrator ever wants to replace a memory it is easier to
service a system at DIMM module boundaries. Compare this to PMEM where
data could be interleaved in an opaque hardware specific manner across
several DIMMs.
PMEM vs BLK
+-----------
+
BLK-apertures solve these RAS problems, but their presence is also the
major contributing factor to the complexity of the ND subsystem. They
complicate the implementation because PMEM and BLK alias in DPA space.
@@ -185,13 +214,14 @@ carved into an arbitrary number of BLK devices with discontiguous
extents.
BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX
---------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One of the few
reasons to allow multiple BLK namespaces per REGION is so that each
BLK-namespace can be configured with a BTT with unique atomic sector
sizes. While a PMEM device can host a BTT the LABEL specification does
not provide for a sector size to be specified for a PMEM namespace.
+
This is due to the expectation that the primary usage model for PMEM is
via DAX, and the BTT is incompatible with DAX. However, for the cases
where an application or filesystem still needs atomic sector update
@@ -200,52 +230,52 @@ LIBNVDIMM/NDCTL: Block Translation Table "btt"
Example NVDIMM Platform
------------------------
+=======================
For the remainder of this document the following diagram will be
-referenced for any example sysfs layouts.
+referenced for any example sysfs layouts::
- (a) (b) DIMM BLK-REGION
- +-------------------+--------+--------+--------+
-+------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2
-| imc0 +--+- - - region0- - - +--------+ +--------+
-+--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3
- | +-------------------+--------v v--------+
-+--+---+ | |
-| cpu0 | region1
-+--+---+ | |
- | +----------------------------^ ^--------+
-+--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4
-| imc1 +--+----------------------------| +--------+
-+------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5
- +----------------------------+--------+--------+
+ (a) (b) DIMM BLK-REGION
+ +-------------------+--------+--------+--------+
+ +------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2
+ | imc0 +--+- - - region0- - - +--------+ +--------+
+ +--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3
+ | +-------------------+--------v v--------+
+ +--+---+ | |
+ | cpu0 | region1
+ +--+---+ | |
+ | +----------------------------^ ^--------+
+ +--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4
+ | imc1 +--+----------------------------| +--------+
+ +------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5
+ +----------------------------+--------+--------+
In this platform we have four DIMMs and two memory controllers in one
socket. Each unique interface (BLK or PMEM) to DPA space is identified
by a region device with a dynamically assigned id (REGION0 - REGION5).
1. The first portion of DIMM0 and DIMM1 are interleaved as REGION0. A
- single PMEM namespace is created in the REGION0-SPA-range that spans most
- of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
- interleaved system-physical-address range is reclaimed as BLK-aperture
- accessed space starting at DPA-offset (a) into each DIMM. In that
- reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
- REGION3 where "blk2.0" and "blk3.0" are just human readable names that
- could be set to any user-desired name in the LABEL.
+ single PMEM namespace is created in the REGION0-SPA-range that spans most
+ of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
+ interleaved system-physical-address range is reclaimed as BLK-aperture
+ accessed space starting at DPA-offset (a) into each DIMM. In that
+ reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
+ REGION3 where "blk2.0" and "blk3.0" are just human readable names that
+ could be set to any user-desired name in the LABEL.
2. In the last portion of DIMM0 and DIMM1 we have an interleaved
- system-physical-address range, REGION1, that spans those two DIMMs as
- well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace
- named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
- each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
- "blk5.0".
+ system-physical-address range, REGION1, that spans those two DIMMs as
+ well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace
+ named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
+ each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
+ "blk5.0".
3. The portion of DIMM2 and DIMM3 that do not participate in the REGION1
- interleaved system-physical-address range (i.e. the DPA address past
- offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
- Note, that this example shows that BLK-aperture namespaces don't need to
- be contiguous in DPA-space.
+ interleaved system-physical-address range (i.e. the DPA address past
+ offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
+ Note, that this example shows that BLK-aperture namespaces don't need to
+ be contiguous in DPA-space.
This bus is provided by the kernel under the device
/sys/devices/platform/nfit_test.0 when CONFIG_NFIT_TEST is enabled and
@@ -254,7 +284,7 @@ by a region device with a dynamically assigned id (REGION0 - REGION5).
LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API
-----------------------------------------------------
+========================================================
What follows is a description of the LIBNVDIMM sysfs layout and a
corresponding object hierarchy diagram as viewed through the LIBNDCTL
@@ -263,12 +293,18 @@ NVDIMM Platform which is also the LIBNVDIMM bus used in the LIBNDCTL unit
test.
LIBNDCTL: Context
+-----------------
+
Every API call in the LIBNDCTL library requires a context that holds the
logging parameters and other library instance state. The library is
based on the libabc template:
-https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
+
+ https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
LIBNDCTL: instantiate a new library context example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
struct ndctl_ctx *ctx;
@@ -278,7 +314,7 @@ LIBNDCTL: instantiate a new library context example
return NULL;
LIBNVDIMM/LIBNDCTL: Bus
--------------------
+-----------------------
A bus has a 1:1 relationship with an NFIT. The current expectation for
ACPI based systems is that there is only ever one platform-global NFIT.
@@ -288,9 +324,10 @@ we use this capability to test multiple NFIT configurations in the unit
test.
LIBNVDIMM: control class device in /sys/class
+---------------------------------------------
This character device accepts DSM messages to be passed to DIMM
-identified by its NFIT handle.
+identified by its NFIT handle::
/sys/class/nd/ndctl0
|-- dev
@@ -300,10 +337,15 @@ identified by its NFIT handle.
LIBNVDIMM: bus
+--------------
+
+::
struct nvdimm_bus *nvdimm_bus_register(struct device *parent,
struct nvdimm_bus_descriptor *nfit_desc);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- commands
|-- nd
@@ -324,7 +366,9 @@ LIBNVDIMM: bus
`-- wait_probe
LIBNDCTL: bus enumeration example
-Find the bus handle that describes the bus from Example NVDIMM Platform
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Find the bus handle that describes the bus from Example NVDIMM Platform::
static struct ndctl_bus *get_bus_by_provider(struct ndctl_ctx *ctx,
const char *provider)
@@ -342,7 +386,7 @@ Find the bus handle that describes the bus from Example NVDIMM Platform
LIBNVDIMM/LIBNDCTL: DIMM (NMEM)
----------------------------
+-------------------------------
The DIMM device provides a character device for sending commands to
hardware, and it is a container for LABELs. If the DIMM is defined by
@@ -355,11 +399,16 @@ Range Mapping Structure", and there is no requirement that they actually
be physical DIMMs, so we use a more generic name.
LIBNVDIMM: DIMM (NMEM)
+^^^^^^^^^^^^^^^^^^^^^^
+
+::
struct nvdimm *nvdimm_create(struct nvdimm_bus *nvdimm_bus, void *provider_data,
const struct attribute_group **groups, unsigned long flags,
unsigned long *dsm_mask);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- nmem0
| |-- available_slots
@@ -384,15 +433,20 @@ LIBNVDIMM: DIMM (NMEM)
LIBNDCTL: DIMM enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note, in this example we are assuming NFIT-defined DIMMs which are
identified by an "nfit_handle" a 32-bit value where:
-Bit 3:0 DIMM number within the memory channel
-Bit 7:4 memory channel number
-Bit 11:8 memory controller ID
-Bit 15:12 socket ID (within scope of a Node controller if node controller is present)
-Bit 27:16 Node Controller ID
-Bit 31:28 Reserved
+
+ - Bit 3:0 DIMM number within the memory channel
+ - Bit 7:4 memory channel number
+ - Bit 11:8 memory controller ID
+ - Bit 15:12 socket ID (within scope of a Node controller if node
+ controller is present)
+ - Bit 27:16 Node Controller ID
+ - Bit 31:28 Reserved
+
+::
static struct ndctl_dimm *get_dimm_by_handle(struct ndctl_bus *bus,
unsigned int handle)
@@ -413,7 +467,7 @@ Bit 31:28 Reserved
dimm = get_dimm_by_handle(bus, DIMM_HANDLE(0, 0, 0, 0, 0));
LIBNVDIMM/LIBNDCTL: Region
-----------------------
+--------------------------
A generic REGION device is registered for each PMEM range or BLK-aperture
set. Per the example there are 6 regions: 2 PMEM and 4 BLK-aperture
@@ -435,13 +489,15 @@ emits, "devtype" duplicates the DEVTYPE variable stored by udev at the
at the 'add' event, and finally, the optional "spa_index" is provided in
the case where the region is defined by a SPA.
-LIBNVDIMM: region
+LIBNVDIMM: region::
struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus,
struct nd_region_desc *ndr_desc);
struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus,
struct nd_region_desc *ndr_desc);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- region0
| |-- available_size
@@ -468,10 +524,11 @@ LIBNVDIMM: region
[..]
LIBNDCTL: region enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sample region retrieval routines based on NFIT-unique data like
"spa_index" (interleave set id) for PMEM and "nfit_handle" (dimm id) for
-BLK.
+BLK::
static struct ndctl_region *get_pmem_region_by_spa_index(struct ndctl_bus *bus,
unsigned int spa_index)
@@ -518,33 +575,33 @@ REGION name generic and expects userspace to always consider the
region-attributes for four reasons:
1. There are already more than two REGION and "namespace" types. For
- PMEM there are two subtypes. As mentioned previously we have PMEM where
- the constituent DIMM devices are known and anonymous PMEM. For BLK
- regions the NFIT specification already anticipates vendor specific
- implementations. The exact distinction of what a region contains is in
- the region-attributes not the region-name or the region-devtype.
+ PMEM there are two subtypes. As mentioned previously we have PMEM where
+ the constituent DIMM devices are known and anonymous PMEM. For BLK
+ regions the NFIT specification already anticipates vendor specific
+ implementations. The exact distinction of what a region contains is in
+ the region-attributes not the region-name or the region-devtype.
2. A region with zero child-namespaces is a possible configuration. For
- example, the NFIT allows for a DCR to be published without a
- corresponding BLK-aperture. This equates to a DIMM that can only accept
- control/configuration messages, but no i/o through a descendant block
- device. Again, this "type" is advertised in the attributes ('mappings'
- == 0) and the name does not tell you much.
+ example, the NFIT allows for a DCR to be published without a
+ corresponding BLK-aperture. This equates to a DIMM that can only accept
+ control/configuration messages, but no i/o through a descendant block
+ device. Again, this "type" is advertised in the attributes ('mappings'
+ == 0) and the name does not tell you much.
3. What if a third major interface type arises in the future? Outside
- of vendor specific implementations, it's not difficult to envision a
- third class of interface type beyond BLK and PMEM. With a generic name
- for the REGION level of the device-hierarchy old userspace
- implementations can still make sense of new kernel advertised
- region-types. Userspace can always rely on the generic region
- attributes like "mappings", "size", etc and the expected child devices
- named "namespace". This generic format of the device-model hierarchy
- allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
- future-proof.
+ of vendor specific implementations, it's not difficult to envision a
+ third class of interface type beyond BLK and PMEM. With a generic name
+ for the REGION level of the device-hierarchy old userspace
+ implementations can still make sense of new kernel advertised
+ region-types. Userspace can always rely on the generic region
+ attributes like "mappings", "size", etc and the expected child devices
+ named "namespace". This generic format of the device-model hierarchy
+ allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
+ future-proof.
4. There are more robust mechanisms for determining the major type of a
- region than a device name. See the next section, How Do I Determine the
- Major Type of a Region?
+ region than a device name. See the next section, How Do I Determine the
+ Major Type of a Region?
How Do I Determine the Major Type of a Region?
----------------------------------------------
@@ -553,7 +610,8 @@ Outside of the blanket recommendation of "use libndctl", or simply
looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
"nstype" integer attribute, here are some other options.
- 1. module alias lookup:
+1. module alias lookup
+^^^^^^^^^^^^^^^^^^^^^^
The whole point of region/namespace device type differentiation is to
decide which block-device driver will attach to a given LIBNVDIMM namespace.
@@ -569,28 +627,31 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
the resulting namespaces. The output from module resolution is more
accurate than a region-name or region-devtype.
- 2. udev:
+2. udev
+^^^^^^^
- The kernel "devtype" is registered in the udev database
- # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
- P: /devices/platform/nfit_test.0/ndbus0/region0
- E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
- E: DEVTYPE=nd_pmem
- E: MODALIAS=nd:t2
- E: SUBSYSTEM=nd
+ The kernel "devtype" is registered in the udev database::
- # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
- P: /devices/platform/nfit_test.0/ndbus0/region4
- E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
- E: DEVTYPE=nd_blk
- E: MODALIAS=nd:t3
- E: SUBSYSTEM=nd
+ # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
+ P: /devices/platform/nfit_test.0/ndbus0/region0
+ E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
+ E: DEVTYPE=nd_pmem
+ E: MODALIAS=nd:t2
+ E: SUBSYSTEM=nd
+
+ # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
+ P: /devices/platform/nfit_test.0/ndbus0/region4
+ E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
+ E: DEVTYPE=nd_blk
+ E: MODALIAS=nd:t3
+ E: SUBSYSTEM=nd
...and is available as a region attribute, but keep in mind that the
"devtype" does not indicate sub-type variations and scripts should
really be understanding the other attributes.
- 3. type specific attributes:
+3. type specific attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
As it currently stands a BLK-aperture region will never have a
"nfit/spa_index" attribute, but neither will a non-NFIT PMEM region. A
@@ -600,7 +661,7 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
LIBNVDIMM/LIBNDCTL: Namespace
--------------------------
+-----------------------------
A REGION, after resolving DPA aliasing and LABEL specified boundaries,
surfaces one or more "namespace" devices. The arrival of a "namespace"
@@ -608,12 +669,14 @@ device currently triggers either the nd_blk or nd_pmem driver to load
and register a disk/block device.
LIBNVDIMM: namespace
+^^^^^^^^^^^^^^^^^^^^
+
Here is a sample layout from the three major types of NAMESPACE where
namespace0.0 represents DIMM-info-backed PMEM (note that it has a 'uuid'
attribute), namespace2.0 represents a BLK namespace (note it has a
'sector_size' attribute) that, and namespace6.0 represents an anonymous
PMEM namespace (note that has no 'uuid' attribute due to not support a
-LABEL).
+LABEL)::
/sys/devices/platform/nfit_test.0/ndbus0/region0/namespace0.0
|-- alt_name
@@ -656,76 +719,84 @@ LABEL).
`-- uevent
LIBNDCTL: namespace enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Namespaces are indexed relative to their parent region, example below.
These indexes are mostly static from boot to boot, but subsystem makes
no guarantees in this regard. For a static namespace identifier use its
'uuid' attribute.
-static struct ndctl_namespace *get_namespace_by_id(struct ndctl_region *region,
- unsigned int id)
-{
- struct ndctl_namespace *ndns;
+::
- ndctl_namespace_foreach(region, ndns)
- if (ndctl_namespace_get_id(ndns) == id)
- return ndns;
+ static struct ndctl_namespace
+ *get_namespace_by_id(struct ndctl_region *region, unsigned int id)
+ {
+ struct ndctl_namespace *ndns;
- return NULL;
-}
+ ndctl_namespace_foreach(region, ndns)
+ if (ndctl_namespace_get_id(ndns) == id)
+ return ndns;
+
+ return NULL;
+ }
LIBNDCTL: namespace creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Idle namespaces are automatically created by the kernel if a given
region has enough available capacity to create a new namespace.
Namespace instantiation involves finding an idle namespace and
configuring it. For the most part the setting of namespace attributes
can occur in any order, the only constraint is that 'uuid' must be set
before 'size'. This enables the kernel to track DPA allocations
-internally with a static identifier.
+internally with a static identifier::
-static int configure_namespace(struct ndctl_region *region,
- struct ndctl_namespace *ndns,
- struct namespace_parameters *parameters)
-{
- char devname[50];
+ static int configure_namespace(struct ndctl_region *region,
+ struct ndctl_namespace *ndns,
+ struct namespace_parameters *parameters)
+ {
+ char devname[50];
- snprintf(devname, sizeof(devname), "namespace%d.%d",
- ndctl_region_get_id(region), paramaters->id);
+ snprintf(devname, sizeof(devname), "namespace%d.%d",
+ ndctl_region_get_id(region), paramaters->id);
- ndctl_namespace_set_alt_name(ndns, devname);
- /* 'uuid' must be set prior to setting size! */
- ndctl_namespace_set_uuid(ndns, paramaters->uuid);
- ndctl_namespace_set_size(ndns, paramaters->size);
- /* unlike pmem namespaces, blk namespaces have a sector size */
- if (parameters->lbasize)
- ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
- ndctl_namespace_enable(ndns);
-}
+ ndctl_namespace_set_alt_name(ndns, devname);
+ /* 'uuid' must be set prior to setting size! */
+ ndctl_namespace_set_uuid(ndns, paramaters->uuid);
+ ndctl_namespace_set_size(ndns, paramaters->size);
+ /* unlike pmem namespaces, blk namespaces have a sector size */
+ if (parameters->lbasize)
+ ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
+ ndctl_namespace_enable(ndns);
+ }
Why the Term "namespace"?
+^^^^^^^^^^^^^^^^^^^^^^^^^
1. Why not "volume" for instance? "volume" ran the risk of confusing
- ND (libnvdimm subsystem) to a volume manager like device-mapper.
+ ND (libnvdimm subsystem) to a volume manager like device-mapper.
2. The term originated to describe the sub-devices that can be created
- within a NVME controller (see the nvme specification:
- http://www.nvmexpress.org/specifications/), and NFIT namespaces are
- meant to parallel the capabilities and configurability of
- NVME-namespaces.
+ within a NVME controller (see the nvme specification:
+ http://www.nvmexpress.org/specifications/), and NFIT namespaces are
+ meant to parallel the capabilities and configurability of
+ NVME-namespaces.
LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
----------------------------------------------
+-------------------------------------------------
A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked
block device driver that fronts either the whole block device or a
partition of a block device emitted by either a PMEM or BLK NAMESPACE.
LIBNVDIMM: btt layout
+^^^^^^^^^^^^^^^^^^^^^
+
Every region will start out with at least one BTT device which is the
seed device. To activate it set the "namespace", "uuid", and
"sector_size" attributes and then bind the device to the nd_pmem or
-nd_blk driver depending on the region type.
+nd_blk driver depending on the region type::
/sys/devices/platform/nfit_test.1/ndbus0/region0/btt0/
|-- namespace
@@ -739,10 +810,12 @@ nd_blk driver depending on the region type.
`-- uuid
LIBNDCTL: btt creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Similar to namespaces an idle BTT device is automatically created per
region. Each time this "seed" btt device is configured and enabled a new
seed is created. Creating a BTT configuration involves two steps of
-finding and idle BTT and assigning it to consume a PMEM or BLK namespace.
+finding and idle BTT and assigning it to consume a PMEM or BLK namespace::
static struct ndctl_btt *get_idle_btt(struct ndctl_region *region)
{
@@ -787,29 +860,28 @@ Summary LIBNDCTL Diagram
------------------------
For the given example above, here is the view of the objects as seen by the
-LIBNDCTL API:
- +---+
- |CTX| +---------+ +--------------+ +---------------+
- +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
- | | +---------+ +--------------+ +---------------+
-+-------+ | | +---------+ +--------------+ +---------------+
-| DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
-+-------+ | | | +---------+ +--------------+ +---------------+
-| DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+
-+-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" |
-| DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+
-+-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 |
-| DIMM3 <-+ | +--------------+ +----------------------+
-+-------+ | +---------+ +--------------+ +---------------+
- +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" |
- | +---------+ | +--------------+ +----------------------+
- | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 |
- | +--------------+ +----------------------+
- | +---------+ +--------------+ +---------------+
- +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" |
- | +---------+ +--------------+ +---------------+
- | +---------+ +--------------+ +----------------------+
- +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 |
- +---------+ +--------------+ +---------------+------+
-
+LIBNDCTL API::
+ +---+
+ |CTX| +---------+ +--------------+ +---------------+
+ +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
+ | | +---------+ +--------------+ +---------------+
+ +-------+ | | +---------+ +--------------+ +---------------+
+ | DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
+ +-------+ | | | +---------+ +--------------+ +---------------+
+ | DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+
+ +-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" |
+ | DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+
+ +-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 |
+ | DIMM3 <-+ | +--------------+ +----------------------+
+ +-------+ | +---------+ +--------------+ +---------------+
+ +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" |
+ | +---------+ | +--------------+ +----------------------+
+ | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 |
+ | +--------------+ +----------------------+
+ | +---------+ +--------------+ +---------------+
+ +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" |
+ | +---------+ +--------------+ +---------------+
+ | +---------+ +--------------+ +----------------------+
+ +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 |
+ +---------+ +--------------+ +---------------+------+
diff --git a/Documentation/nvdimm/security.txt b/Documentation/nvdimm/security.rst
similarity index 99%
rename from Documentation/nvdimm/security.txt
rename to Documentation/nvdimm/security.rst
index 4c36c05ca98e..ad9dea099b34 100644
--- a/Documentation/nvdimm/security.txt
+++ b/Documentation/nvdimm/security.rst
@@ -1,4 +1,5 @@
-NVDIMM SECURITY
+===============
+NVDIMM Security
===============
1. Introduction
@@ -138,4 +139,5 @@ This command is only available when the master security is enabled, indicated
by the extended security status.
[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
+
[2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
diff --git a/drivers/nvdimm/Kconfig b/drivers/nvdimm/Kconfig
index 54500798f23a..e89c1c332407 100644
--- a/drivers/nvdimm/Kconfig
+++ b/drivers/nvdimm/Kconfig
@@ -33,7 +33,7 @@ config BLK_DEV_PMEM
Documentation/admin-guide/kernel-parameters.rst). This driver converts
these persistent memory ranges into block devices that are
capable of DAX (direct-access) file system mappings. See
- Documentation/nvdimm/nvdimm.txt for more details.
+ Documentation/nvdimm/nvdimm.rst for more details.
Say Y if you want to use an NVDIMM
--
2.21.0
^ permalink raw reply related
* [PATCH v1 20/31] docs: hid: convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jiri Kosina, Jonathan Cameron,
Srinivas Pandruvada, Benjamin Tissoires, Dmitry Torokhov,
linux-input, linux-iio, linux-usb
In-Reply-To: <cover.1560364493.git.mchehab+samsung@kernel.org>
Rename the HID documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
While here, fix the sysfs example from hid-sensor.txt, that
has a lot of "?" instead of the proper UTF-8 characters that
are produced by the tree command.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../hid/{hid-alps.txt => hid-alps.rst} | 85 ++-
.../hid/{hid-sensor.txt => hid-sensor.rst} | 192 +++----
.../{hid-transport.txt => hid-transport.rst} | 82 ++-
Documentation/hid/{hiddev.txt => hiddev.rst} | 154 ++++--
Documentation/hid/{hidraw.txt => hidraw.rst} | 53 +-
Documentation/hid/index.rst | 18 +
Documentation/hid/intel-ish-hid.rst | 485 ++++++++++++++++++
Documentation/hid/intel-ish-hid.txt | 454 ----------------
Documentation/hid/{uhid.txt => uhid.rst} | 46 +-
Documentation/input/input.rst | 2 +-
MAINTAINERS | 2 +-
11 files changed, 897 insertions(+), 676 deletions(-)
rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
create mode 100644 Documentation/hid/index.rst
create mode 100644 Documentation/hid/intel-ish-hid.rst
delete mode 100644 Documentation/hid/intel-ish-hid.txt
rename Documentation/hid/{uhid.txt => uhid.rst} (94%)
diff --git a/Documentation/hid/hid-alps.txt b/Documentation/hid/hid-alps.rst
similarity index 64%
rename from Documentation/hid/hid-alps.txt
rename to Documentation/hid/hid-alps.rst
index 6b02a2447c77..e2f4c4c11e3f 100644
--- a/Documentation/hid/hid-alps.txt
+++ b/Documentation/hid/hid-alps.rst
@@ -1,19 +1,26 @@
+==========================
ALPS HID Touchpad Protocol
-----------------------
+==========================
Introduction
------------
Currently ALPS HID driver supports U1 Touchpad device.
-U1 devuce basic information.
+U1 device basic information.
+
+========== ======
Vender ID 0x044E
Product ID 0x120B
Version ID 0x0121
+========== ======
HID Descriptor
-------------
+--------------
+
+======= ==================== ===== =======================================
Byte Field Value Notes
+======= ==================== ===== =======================================
0 wHIDDescLength 001E Length of HID Descriptor : 30 bytes
2 bcdVersion 0100 Compliant with Version 1.00
4 wReportDescLength 00B2 Report Descriptor is 178 Bytes (0x00B2)
@@ -28,32 +35,42 @@ Byte Field Value Notes
22 wProductID 120B Product ID 0x120B
24 wVersionID 0121 Version 01.21
26 RESERVED 0000 RESERVED
+======= ==================== ===== =======================================
Report ID
-------------
-ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP
-ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP
-ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP
-ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP
-ReportID-5 (Feature Reports) Feature Reports
-ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP
-ReportID-7 (Feature Reports) Flash update (Bootloader)
+---------
+
+========== ================= =========================================
+ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP
+ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP
+ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP
+ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP
+ReportID-5 (Feature Reports) Feature Reports
+ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP
+ReportID-7 (Feature Reports) Flash update (Bootloader)
+========== ================= =========================================
Data pattern
------------
+
+===== ========== ===== =================
Case1 ReportID_1 TP/SP Relative/Relative
Case2 ReportID_3 TP Absolute
ReportID_6 SP Absolute
+===== ========== ===== =================
Command Read/Write
------------------
To read/write to RAM, need to send a commands to the device.
+
The command format is as below.
DataByte(SET_REPORT)
+
+===== ======================
Byte1 Command Byte
Byte2 Address - Byte 0 (LSB)
Byte3 Address - Byte 1
@@ -61,13 +78,19 @@ Byte4 Address - Byte 2
Byte5 Address - Byte 3 (MSB)
Byte6 Value Byte
Byte7 Checksum
+===== ======================
Command Byte is read=0xD1/write=0xD2 .
+
Address is read/write RAM address.
+
Value Byte is writing data when you send the write commands.
+
When you read RAM, there is no meaning.
DataByte(GET_REPORT)
+
+===== ======================
Byte1 Response Byte
Byte2 Address - Byte 0 (LSB)
Byte3 Address - Byte 1
@@ -75,6 +98,7 @@ Byte4 Address - Byte 2
Byte5 Address - Byte 3 (MSB)
Byte6 Value Byte
Byte7 Checksum
+===== ======================
Read value is stored in Value Byte.
@@ -82,7 +106,11 @@ Read value is stored in Value Byte.
Packet Format
Touchpad data byte
------------------
- b7 b6 b5 b4 b3 b2 b1 b0
+
+
+======= ======= ======= ======= ======= ======= ======= ======= =====
+- b7 b6 b5 b4 b3 b2 b1 b0
+======= ======= ======= ======= ======= ======= ======= ======= =====
1 0 0 SW6 SW5 SW4 SW3 SW2 SW1
2 0 0 0 Fcv Fn3 Fn2 Fn1 Fn0
3 Xa0_7 Xa0_6 Xa0_5 Xa0_4 Xa0_3 Xa0_2 Xa0_1 Xa0_0
@@ -114,17 +142,25 @@ Touchpad data byte
25 Ya4_7 Ya4_6 Ya4_5 Ya4_4 Ya4_3 Ya4_2 Ya4_1 Ya4_0
26 Ya4_15 Ya4_14 Ya4_13 Ya4_12 Ya4_11 Ya4_10 Ya4_9 Ya4_8
27 LFB4 Zs4_6 Zs4_5 Zs4_4 Zs4_3 Zs4_2 Zs4_1 Zs4_0
+======= ======= ======= ======= ======= ======= ======= ======= =====
-SW1-SW6: SW ON/OFF status
-Xan_15-0(16bit):X Absolute data of the "n"th finger
-Yan_15-0(16bit):Y Absolute data of the "n"th finger
-Zsn_6-0(7bit): Operation area of the "n"th finger
+SW1-SW6:
+ SW ON/OFF status
+Xan_15-0(16bit):
+ X Absolute data of the "n"th finger
+Yan_15-0(16bit):
+ Y Absolute data of the "n"th finger
+Zsn_6-0(7bit):
+ Operation area of the "n"th finger
StickPointer data byte
-------------------
- b7 b6 b5 b4 b3 b2 b1 b0
+----------------------
+
+======= ======= ======= ======= ======= ======= ======= ======= =====
+- b7 b6 b5 b4 b3 b2 b1 b0
+======= ======= ======= ======= ======= ======= ======= ======= =====
Byte1 1 1 1 0 1 SW3 SW2 SW1
Byte2 X7 X6 X5 X4 X3 X2 X1 X0
Byte3 X15 X14 X13 X12 X11 X10 X9 X8
@@ -132,8 +168,13 @@ Byte4 Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
Byte5 Y15 Y14 Y13 Y12 Y11 Y10 Y9 Y8
Byte6 Z7 Z6 Z5 Z4 Z3 Z2 Z1 Z0
Byte7 T&P Z14 Z13 Z12 Z11 Z10 Z9 Z8
+======= ======= ======= ======= ======= ======= ======= ======= =====
-SW1-SW3: SW ON/OFF status
-Xn_15-0(16bit):X Absolute data
-Yn_15-0(16bit):Y Absolute data
-Zn_14-0(15bit):Z
+SW1-SW3:
+ SW ON/OFF status
+Xn_15-0(16bit):
+ X Absolute data
+Yn_15-0(16bit):
+ Y Absolute data
+Zn_14-0(15bit):
+ Z
diff --git a/Documentation/hid/hid-sensor.txt b/Documentation/hid/hid-sensor.rst
similarity index 61%
rename from Documentation/hid/hid-sensor.txt
rename to Documentation/hid/hid-sensor.rst
index b287752a31cd..758972e34971 100644
--- a/Documentation/hid/hid-sensor.txt
+++ b/Documentation/hid/hid-sensor.rst
@@ -1,6 +1,6 @@
-
+=====================
HID Sensors Framework
-======================
+=====================
HID sensor framework provides necessary interfaces to implement sensor drivers,
which are connected to a sensor hub. The sensor hub is a HID device and it provides
a report descriptor conforming to HID 1.12 sensor usage tables.
@@ -15,22 +15,22 @@ the drivers themselves."
This specification describes many usage IDs, which describe the type of sensor
and also the individual data fields. Each sensor can have variable number of
data fields. The length and order is specified in the report descriptor. For
-example a part of report descriptor can look like:
+example a part of report descriptor can look like::
- INPUT(1)[INPUT]
- ..
- Field(2)
- Physical(0020.0073)
- Usage(1)
- 0020.045f
- Logical Minimum(-32767)
- Logical Maximum(32767)
- Report Size(8)
- Report Count(1)
- Report Offset(16)
- Flags(Variable Absolute)
-..
-..
+ INPUT(1)[INPUT]
+ ..
+ Field(2)
+ Physical(0020.0073)
+ Usage(1)
+ 0020.045f
+ Logical Minimum(-32767)
+ Logical Maximum(32767)
+ Report Size(8)
+ Report Count(1)
+ Report Offset(16)
+ Flags(Variable Absolute)
+ ..
+ ..
The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
This accelerometer-3D has some fields. Here for example field 2 is motion intensity
@@ -40,13 +40,14 @@ data will use this format.
Implementation
-=================
+==============
This specification defines many different types of sensors with different sets of
data fields. It is difficult to have a common input event to user space applications,
for different sensors. For example an accelerometer can send X,Y and Z data, whereas
an ambient light sensor can send illumination data.
So the implementation has two parts:
+
- Core hid driver
- Individual sensor processing part (sensor drivers)
@@ -55,8 +56,11 @@ Core driver
The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
report descriptors and identifies all the sensors present. It adds an MFD device
with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
-For example
+
+For example:
+
HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
+
So if any driver with this name is inserted, then the probe routine for that
function will be called. So an accelerometer processing driver can register
with this name and will be probed if there is an accelerometer-3D detected.
@@ -66,7 +70,8 @@ drivers to register and get events for that usage id. Also it provides parsing
functions, which get and set each input/feature/output report.
Individual sensor processing part (sensor drivers)
------------
+--------------------------------------------------
+
The processing driver will use an interface provided by the core driver to parse
the report and get the indexes of the fields and also can get events. This driver
can use IIO interface to use the standard ABI defined for a type of sensor.
@@ -75,31 +80,34 @@ can use IIO interface to use the standard ABI defined for a type of sensor.
Core driver Interface
=====================
-Callback structure:
-Each processing driver can use this structure to set some callbacks.
+Callback structure::
+
+ Each processing driver can use this structure to set some callbacks.
int (*suspend)(..): Callback when HID suspend is received
int (*resume)(..): Callback when HID resume is received
int (*capture_sample)(..): Capture a sample for one of its data fields
int (*send_event)(..): One complete event is received which can have
multiple data fields.
-Registration functions:
-int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
+Registration functions::
+
+ int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
u32 usage_id,
struct hid_sensor_hub_callbacks *usage_callback):
Registers callbacks for an usage id. The callback functions are not allowed
-to sleep.
+to sleep::
-int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
+ int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
u32 usage_id):
Removes callbacks for an usage id.
-Parsing function:
-int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
+Parsing function::
+
+ int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
u8 type,
u32 usage_id, u32 attr_usage_id,
struct hid_sensor_hub_attribute_info *info);
@@ -110,26 +118,27 @@ so that fields can be set or get individually.
These indexes avoid searching every time and getting field index to get or set.
-Set Feature report
-int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
+Set Feature report::
+
+ int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
u32 field_index, s32 value);
This interface is used to set a value for a field in feature report. For example
if there is a field report_interval, which is parsed by a call to
-sensor_hub_input_get_attribute_info before, then it can directly set that individual
-field.
+sensor_hub_input_get_attribute_info before, then it can directly set that
+individual field::
-int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
+ int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
u32 field_index, s32 *value);
This interface is used to get a value for a field in input report. For example
if there is a field report_interval, which is parsed by a call to
-sensor_hub_input_get_attribute_info before, then it can directly get that individual
-field value.
+sensor_hub_input_get_attribute_info before, then it can directly get that
+individual field value::
-int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
+ int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
u32 usage_id,
u32 attr_usage_id, u32 report_id);
@@ -143,6 +152,8 @@ registered callback function to process the sample.
----------
HID Custom and generic Sensors
+------------------------------
+
HID Sensor specification defines two special sensor usage types. Since they
don't represent a standard sensor, it is not possible to define using Linux IIO
@@ -158,66 +169,73 @@ keyboard attached/detached or lid open/close.
To allow application to utilize these sensors, here they are exported uses sysfs
attribute groups, attributes and misc device interface.
-An example of this representation on sysfs:
-/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
-.
-????????? enable_sensor
-????????? feature-0-200316
-??????? ????????? feature-0-200316-maximum
-??????? ????????? feature-0-200316-minimum
-??????? ????????? feature-0-200316-name
-??????? ????????? feature-0-200316-size
-??????? ????????? feature-0-200316-unit-expo
-??????? ????????? feature-0-200316-units
-??????? ????????? feature-0-200316-value
-????????? feature-1-200201
-??????? ????????? feature-1-200201-maximum
-??????? ????????? feature-1-200201-minimum
-??????? ????????? feature-1-200201-name
-??????? ????????? feature-1-200201-size
-??????? ????????? feature-1-200201-unit-expo
-??????? ????????? feature-1-200201-units
-??????? ????????? feature-1-200201-value
-????????? input-0-200201
-??????? ????????? input-0-200201-maximum
-??????? ????????? input-0-200201-minimum
-??????? ????????? input-0-200201-name
-??????? ????????? input-0-200201-size
-??????? ????????? input-0-200201-unit-expo
-??????? ????????? input-0-200201-units
-??????? ????????? input-0-200201-value
-????????? input-1-200202
-??????? ????????? input-1-200202-maximum
-??????? ????????? input-1-200202-minimum
-??????? ????????? input-1-200202-name
-??????? ????????? input-1-200202-size
-??????? ????????? input-1-200202-unit-expo
-??????? ????????? input-1-200202-units
-??????? ????????? input-1-200202-value
+An example of this representation on sysfs::
+
+ /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
+ .
+ │ ├── enable_sensor
+ │ │ ├── feature-0-200316
+ │ │ │ ├── feature-0-200316-maximum
+ │ │ │ ├── feature-0-200316-minimum
+ │ │ │ ├── feature-0-200316-name
+ │ │ │ ├── feature-0-200316-size
+ │ │ │ ├── feature-0-200316-unit-expo
+ │ │ │ ├── feature-0-200316-units
+ │ │ │ ├── feature-0-200316-value
+ │ │ ├── feature-1-200201
+ │ │ │ ├── feature-1-200201-maximum
+ │ │ │ ├── feature-1-200201-minimum
+ │ │ │ ├── feature-1-200201-name
+ │ │ │ ├── feature-1-200201-size
+ │ │ │ ├── feature-1-200201-unit-expo
+ │ │ │ ├── feature-1-200201-units
+ │ │ │ ├── feature-1-200201-value
+ │ │ ├── input-0-200201
+ │ │ │ ├── input-0-200201-maximum
+ │ │ │ ├── input-0-200201-minimum
+ │ │ │ ├── input-0-200201-name
+ │ │ │ ├── input-0-200201-size
+ │ │ │ ├── input-0-200201-unit-expo
+ │ │ │ ├── input-0-200201-units
+ │ │ │ ├── input-0-200201-value
+ │ │ ├── input-1-200202
+ │ │ │ ├── input-1-200202-maximum
+ │ │ │ ├── input-1-200202-minimum
+ │ │ │ ├── input-1-200202-name
+ │ │ │ ├── input-1-200202-size
+ │ │ │ ├── input-1-200202-unit-expo
+ │ │ │ ├── input-1-200202-units
+ │ │ │ ├── input-1-200202-value
Here there is a custom sensors with four fields, two feature and two inputs.
Each field is represented by a set of attributes. All fields except the "value"
are read only. The value field is a RW field.
-Example
-/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
-feature-0-200316-maximum:6
-feature-0-200316-minimum:0
-feature-0-200316-name:property-reporting-state
-feature-0-200316-size:1
-feature-0-200316-unit-expo:0
-feature-0-200316-units:25
-feature-0-200316-value:1
+
+Example::
+
+ /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
+ feature-0-200316-maximum:6
+ feature-0-200316-minimum:0
+ feature-0-200316-name:property-reporting-state
+ feature-0-200316-size:1
+ feature-0-200316-unit-expo:0
+ feature-0-200316-units:25
+ feature-0-200316-value:1
How to enable such sensor?
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
By default sensor can be power gated. To enable sysfs attribute "enable" can be
-used.
-$ echo 1 > enable_sensor
+used::
+
+ $ echo 1 > enable_sensor
Once enabled and powered on, sensor can report value using HID reports.
-These reports are pushed using misc device interface in a FIFO order.
-/dev$ tree | grep HID-SENSOR-2000e1.6.auto
-??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
-????????? HID-SENSOR-2000e1.6.auto
+These reports are pushed using misc device interface in a FIFO order::
+
+ /dev$ tree | grep HID-SENSOR-2000e1.6.auto
+ │ │ │ ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
+ │ ├── HID-SENSOR-2000e1.6.auto
Each reports can be of variable length preceded by a header. This header
consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
diff --git a/Documentation/hid/hid-transport.txt b/Documentation/hid/hid-transport.rst
similarity index 93%
rename from Documentation/hid/hid-transport.txt
rename to Documentation/hid/hid-transport.rst
index 3dcba9fd4a3a..6f3aaa86ce7b 100644
--- a/Documentation/hid/hid-transport.txt
+++ b/Documentation/hid/hid-transport.rst
@@ -1,5 +1,6 @@
- HID I/O Transport Drivers
- ===========================
+=========================
+HID I/O Transport Drivers
+=========================
The HID subsystem is independent of the underlying transport driver. Initially,
only USB was supported, but other specifications adopted the HID design and
@@ -16,6 +17,8 @@ transport and device setup/management. HID core is responsible of
report-parsing, report interpretation and the user-space API. Device specifics
and quirks are handled by all layers depending on the quirk.
+::
+
+-----------+ +-----------+ +-----------+ +-----------+
| Device #1 | | Device #i | | Device #j | | Device #k |
+-----------+ +-----------+ +-----------+ +-----------+
@@ -42,8 +45,9 @@ and quirks are handled by all layers depending on the quirk.
+----------------+ +-----------+ +------------------+ +------------------+
Example Drivers:
- I/O: USB, I2C, Bluetooth-l2cap
- Transport: USB-HID, I2C-HID, BT-HIDP
+
+ - I/O: USB, I2C, Bluetooth-l2cap
+ - Transport: USB-HID, I2C-HID, BT-HIDP
Everything below "HID Core" is simplified in this graph as it is only of
interest to HID device drivers. Transport drivers do not need to know the
@@ -183,7 +187,7 @@ Other ctrl-channel requests are supported by USB-HID but are not available
-------------------
Transport drivers normally use the following procedure to register a new device
-with HID core:
+with HID core::
struct hid_device *hid;
int ret;
@@ -215,7 +219,7 @@ Once hid_add_device() is entered, HID core might use the callbacks provided in
"custom_ll_driver". Note that fields like "country" can be ignored by underlying
transport-drivers if not supported.
-To unregister a device, use:
+To unregister a device, use::
hid_destroy_device(hid);
@@ -226,73 +230,110 @@ driver callbacks.
-----------------------------
The available HID callbacks are:
- - int (*start) (struct hid_device *hdev)
+
+ ::
+
+ int (*start) (struct hid_device *hdev)
+
Called from HID device drivers once they want to use the device. Transport
drivers can choose to setup their device in this callback. However, normally
devices are already set up before transport drivers register them to HID core
so this is mostly only used by USB-HID.
- - void (*stop) (struct hid_device *hdev)
+ ::
+
+ void (*stop) (struct hid_device *hdev)
+
Called from HID device drivers once they are done with a device. Transport
drivers can free any buffers and deinitialize the device. But note that
->start() might be called again if another HID device driver is loaded on the
device.
+
Transport drivers are free to ignore it and deinitialize devices after they
destroyed them via hid_destroy_device().
- - int (*open) (struct hid_device *hdev)
+ ::
+
+ int (*open) (struct hid_device *hdev)
+
Called from HID device drivers once they are interested in data reports.
Usually, while user-space didn't open any input API/etc., device drivers are
not interested in device data and transport drivers can put devices asleep.
However, once ->open() is called, transport drivers must be ready for I/O.
->open() calls are nested for each client that opens the HID device.
- - void (*close) (struct hid_device *hdev)
+ ::
+
+ void (*close) (struct hid_device *hdev)
+
Called from HID device drivers after ->open() was called but they are no
longer interested in device reports. (Usually if user-space closed any input
devices of the driver).
+
Transport drivers can put devices asleep and terminate any I/O of all
->open() calls have been followed by a ->close() call. However, ->start() may
be called again if the device driver is interested in input reports again.
- - int (*parse) (struct hid_device *hdev)
+ ::
+
+ int (*parse) (struct hid_device *hdev)
+
Called once during device setup after ->start() has been called. Transport
drivers must read the HID report-descriptor from the device and tell HID core
about it via hid_parse_report().
- - int (*power) (struct hid_device *hdev, int level)
+ ::
+
+ int (*power) (struct hid_device *hdev, int level)
+
Called by HID core to give PM hints to transport drivers. Usually this is
analogical to the ->open() and ->close() hints and redundant.
- - void (*request) (struct hid_device *hdev, struct hid_report *report,
- int reqtype)
+ ::
+
+ void (*request) (struct hid_device *hdev, struct hid_report *report,
+ int reqtype)
+
Send an HID request on the ctrl channel. "report" contains the report that
should be sent and "reqtype" the request type. Request-type can be
HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
+
This callback is optional. If not provided, HID core will assemble a raw
report following the HID specs and send it via the ->raw_request() callback.
The transport driver is free to implement this asynchronously.
- - int (*wait) (struct hid_device *hdev)
+ ::
+
+ int (*wait) (struct hid_device *hdev)
+
Used by HID core before calling ->request() again. A transport driver can use
it to wait for any pending requests to complete if only one request is
allowed at a time.
- - int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
- __u8 *buf, size_t count, unsigned char rtype,
- int reqtype)
+ ::
+
+ int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
+ __u8 *buf, size_t count, unsigned char rtype,
+ int reqtype)
+
Same as ->request() but provides the report as raw buffer. This request shall
be synchronous. A transport driver must not use ->wait() to complete such
requests. This request is mandatory and hid core will reject the device if
it is missing.
- - int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
+ ::
+
+ int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
+
Send raw output report via intr channel. Used by some HID device drivers
which require high throughput for outgoing requests on the intr channel. This
must not cause SET_REPORT calls! This must be implemented as asynchronous
output report on the intr channel!
- - int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
+ ::
+
+ int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
+
Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
2.3) Data Path
@@ -314,4 +355,5 @@ transport driver and not passed to hid_input_report().
Acknowledgements to SET_REPORT requests are not of interest to HID core.
----------------------------------------------------
+
Written 2013, David Herrmann <dh.herrmann@gmail.com>
diff --git a/Documentation/hid/hiddev.txt b/Documentation/hid/hiddev.rst
similarity index 77%
rename from Documentation/hid/hiddev.txt
rename to Documentation/hid/hiddev.rst
index 638448707aa2..209e6ba4e019 100644
--- a/Documentation/hid/hiddev.txt
+++ b/Documentation/hid/hiddev.rst
@@ -1,6 +1,9 @@
+================================================
Care and feeding of your Human Interface Devices
+================================================
-INTRODUCTION
+Introduction
+============
In addition to the normal input type HID devices, USB also uses the
human interface device protocols for things that are not really human
@@ -16,38 +19,40 @@ normalised event interface - see Documentation/input/input.rst
* the hiddev interface, which provides fairly raw HID events
The data flow for a HID event produced by a device is something like
-the following :
+the following::
usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event]
|
|
- --> hiddev.c ----> POWER / MONITOR CONTROL
+ --> hiddev.c ----> POWER / MONITOR CONTROL
In addition, other subsystems (apart from USB) can potentially feed
events into the input subsystem, but these have no effect on the hid
device interface.
-USING THE HID DEVICE INTERFACE
+Using the HID Device Interface
+==============================
The hiddev interface is a char interface using the normal USB major,
with the minor numbers starting at 96 and finishing at 111. Therefore,
-you need the following commands:
-mknod /dev/usb/hiddev0 c 180 96
-mknod /dev/usb/hiddev1 c 180 97
-mknod /dev/usb/hiddev2 c 180 98
-mknod /dev/usb/hiddev3 c 180 99
-mknod /dev/usb/hiddev4 c 180 100
-mknod /dev/usb/hiddev5 c 180 101
-mknod /dev/usb/hiddev6 c 180 102
-mknod /dev/usb/hiddev7 c 180 103
-mknod /dev/usb/hiddev8 c 180 104
-mknod /dev/usb/hiddev9 c 180 105
-mknod /dev/usb/hiddev10 c 180 106
-mknod /dev/usb/hiddev11 c 180 107
-mknod /dev/usb/hiddev12 c 180 108
-mknod /dev/usb/hiddev13 c 180 109
-mknod /dev/usb/hiddev14 c 180 110
-mknod /dev/usb/hiddev15 c 180 111
+you need the following commands::
+
+ mknod /dev/usb/hiddev0 c 180 96
+ mknod /dev/usb/hiddev1 c 180 97
+ mknod /dev/usb/hiddev2 c 180 98
+ mknod /dev/usb/hiddev3 c 180 99
+ mknod /dev/usb/hiddev4 c 180 100
+ mknod /dev/usb/hiddev5 c 180 101
+ mknod /dev/usb/hiddev6 c 180 102
+ mknod /dev/usb/hiddev7 c 180 103
+ mknod /dev/usb/hiddev8 c 180 104
+ mknod /dev/usb/hiddev9 c 180 105
+ mknod /dev/usb/hiddev10 c 180 106
+ mknod /dev/usb/hiddev11 c 180 107
+ mknod /dev/usb/hiddev12 c 180 108
+ mknod /dev/usb/hiddev13 c 180 109
+ mknod /dev/usb/hiddev14 c 180 110
+ mknod /dev/usb/hiddev15 c 180 111
So you point your hiddev compliant user-space program at the correct
interface for your device, and it all just works.
@@ -56,7 +61,9 @@ Assuming that you have a hiddev compliant user-space program, of
course. If you need to write one, read on.
-THE HIDDEV API
+The HIDDEV API
+==============
+
This description should be read in conjunction with the HID
specification, freely available from http://www.usb.org, and
conveniently linked of http://www.linux-usb.org.
@@ -69,12 +76,14 @@ each of which can have one or more "usages". In the hid-core,
each one of these usages has a single signed 32 bit value.
read():
+-------
+
This is the event interface. When the HID device's state changes,
it performs an interrupt transfer containing a report which contains
the changed value. The hid-core.c module parses the report, and
returns to hiddev.c the individual usages that have changed within
the report. In its basic mode, the hiddev will make these individual
-usage changes available to the reader using a struct hiddev_event:
+usage changes available to the reader using a struct hiddev_event::
struct hiddev_event {
unsigned hid;
@@ -90,13 +99,19 @@ behavior of the read() function can be modified using the HIDIOCSFLAG
ioctl() described below.
-ioctl():
-This is the control interface. There are a number of controls:
+ioctl():
+--------
-HIDIOCGVERSION - int (read)
-Gets the version code out of the hiddev driver.
+This is the control interface. There are a number of controls:
+
+HIDIOCGVERSION
+ - int (read)
+
+ Gets the version code out of the hiddev driver.
+
+HIDIOCAPPLICATION
+ - (none)
-HIDIOCAPPLICATION - (none)
This ioctl call returns the HID application usage associated with the
hid device. The third argument to ioctl() specifies which application
index to get. This is useful when the device has more than one
@@ -104,25 +119,33 @@ application collection. If the index is invalid (greater or equal to
the number of application collections this device has) the ioctl
returns -1. You can find out beforehand how many application
collections the device has from the num_applications field from the
-hiddev_devinfo structure.
+hiddev_devinfo structure.
+
+HIDIOCGCOLLECTIONINFO
+ - struct hiddev_collection_info (read/write)
-HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
This returns a superset of the information above, providing not only
application collections, but all the collections the device has. It
also returns the level the collection lives in the hierarchy.
-The user passes in a hiddev_collection_info struct with the index
-field set to the index that should be returned. The ioctl fills in
-the other fields. If the index is larger than the last collection
+The user passes in a hiddev_collection_info struct with the index
+field set to the index that should be returned. The ioctl fills in
+the other fields. If the index is larger than the last collection
index, the ioctl returns -1 and sets errno to -EINVAL.
-HIDIOCGDEVINFO - struct hiddev_devinfo (read)
+HIDIOCGDEVINFO
+ - struct hiddev_devinfo (read)
+
Gets a hiddev_devinfo structure which describes the device.
-HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
+HIDIOCGSTRING
+ - struct hiddev_string_descriptor (read/write)
+
Gets a string descriptor from the device. The caller must fill in the
"index" field to indicate which descriptor should be returned.
-HIDIOCINITREPORT - (none)
+HIDIOCINITREPORT
+ - (none)
+
Instructs the kernel to retrieve all input and feature report values
from the device. At this point, all the usage structures will contain
current values for the device, and will maintain it as the device
@@ -130,21 +153,29 @@ changes. Note that the use of this ioctl is unnecessary in general,
since later kernels automatically initialize the reports from the
device at attach time.
-HIDIOCGNAME - string (variable length)
+HIDIOCGNAME
+ - string (variable length)
+
Gets the device name
-HIDIOCGREPORT - struct hiddev_report_info (write)
+HIDIOCGREPORT
+ - struct hiddev_report_info (write)
+
Instructs the kernel to get a feature or input report from the device,
in order to selectively update the usage structures (in contrast to
INITREPORT).
-HIDIOCSREPORT - struct hiddev_report_info (write)
+HIDIOCSREPORT
+ - struct hiddev_report_info (write)
+
Instructs the kernel to send a report to the device. This report can
be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
individual usage values in the report before sending the report in full
-to the device.
+to the device.
+
+HIDIOCGREPORTINFO
+ - struct hiddev_report_info (read/write)
-HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
Fills in a hiddev_report_info structure for the user. The report is
looked up by type (input, output or feature) and id, so these fields
must be filled in by the user. The ID can be absolute -- the actual
@@ -154,52 +185,67 @@ report_id) for the next report after report_id. Without a-priori
information about report ids, the right way to use this ioctl is to
use the relative IDs above to enumerate the valid IDs. The ioctl
returns non-zero when there is no more next ID. The real report ID is
-filled into the returned hiddev_report_info structure.
+filled into the returned hiddev_report_info structure.
+
+HIDIOCGFIELDINFO
+ - struct hiddev_field_info (read/write)
-HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
Returns the field information associated with a report in a
hiddev_field_info structure. The user must fill in report_id and
report_type in this structure, as above. The field_index should also
be filled in, which should be a number from 0 and maxfield-1, as
-returned from a previous HIDIOCGREPORTINFO call.
+returned from a previous HIDIOCGREPORTINFO call.
+
+HIDIOCGUCODE
+ - struct hiddev_usage_ref (read/write)
-HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
Returns the usage_code in a hiddev_usage_ref structure, given that
given its report type, report id, field index, and index within the
field have already been filled into the structure.
-HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
+HIDIOCGUSAGE
+ - struct hiddev_usage_ref (read/write)
+
Returns the value of a usage in a hiddev_usage_ref structure. The
usage to be retrieved can be specified as above, or the user can
choose to fill in the report_type field and specify the report_id as
HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
filled in with the report and field information associated with this
-usage if it is found.
+usage if it is found.
+
+HIDIOCSUSAGE
+ - struct hiddev_usage_ref (write)
-HIDIOCSUSAGE - struct hiddev_usage_ref (write)
Sets the value of a usage in an output report. The user fills in
the hiddev_usage_ref structure as above, but additionally fills in
the value field.
-HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
+HIDIOGCOLLECTIONINDEX
+ - struct hiddev_usage_ref (write)
+
Returns the collection index associated with this usage. This
indicates where in the collection hierarchy this usage sits.
-HIDIOCGFLAG - int (read)
-HIDIOCSFLAG - int (write)
+HIDIOCGFLAG
+ - int (read)
+HIDIOCSFLAG
+ - int (write)
+
These operations respectively inspect and replace the mode flags
that influence the read() call above. The flags are as follows:
- HIDDEV_FLAG_UREF - read() calls will now return
+ HIDDEV_FLAG_UREF
+ - read() calls will now return
struct hiddev_usage_ref instead of struct hiddev_event.
This is a larger structure, but in situations where the
device has more than one usage in its reports with the
same usage code, this mode serves to resolve such
ambiguity.
- HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
+ HIDDEV_FLAG_REPORT
+ - This flag can only be used in conjunction
with HIDDEV_FLAG_UREF. With this flag set, when the device
sends a report, a struct hiddev_usage_ref will be returned
- to read() filled in with the report_type and report_id, but
+ to read() filled in with the report_type and report_id, but
with field_index set to FIELD_INDEX_NONE. This serves as
additional notification when the device has sent a report.
diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.rst
similarity index 89%
rename from Documentation/hid/hidraw.txt
rename to Documentation/hid/hidraw.rst
index c8436e354f44..4a4a0ba1f362 100644
--- a/Documentation/hid/hidraw.txt
+++ b/Documentation/hid/hidraw.rst
@@ -1,5 +1,6 @@
- HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
- ==================================================================
+================================================================
+HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
+================================================================
The hidraw driver provides a raw interface to USB and Bluetooth Human
Interface Devices (HIDs). It differs from hiddev in that reports sent and
@@ -31,6 +32,7 @@ directly under /dev (eg: /dev/hidraw0). As this location is distribution-
and udev rule-dependent, applications should use libudev to locate hidraw
devices attached to the system. There is a tutorial on libudev with a
working example at:
+
http://www.signal11.us/oss/udev/
The HIDRAW API
@@ -51,7 +53,7 @@ byte. For devices which do not use numbered reports, the report data
will begin at the first byte.
write()
---------
+-------
The write() function will write a report to the device. For USB devices, if
the device has an INTERRUPT OUT endpoint, the report will be sent on that
endpoint. If it does not, the report will be sent over the control endpoint,
@@ -62,38 +64,52 @@ number. If the device does not use numbered reports, the first byte should
be set to 0. The report data itself should begin at the second byte.
ioctl()
---------
+-------
Hidraw supports the following ioctls:
-HIDIOCGRDESCSIZE: Get Report Descriptor Size
+HIDIOCGRDESCSIZE:
+ Get Report Descriptor Size
+
This ioctl will get the size of the device's report descriptor.
-HIDIOCGRDESC: Get Report Descriptor
+HIDIOCGRDESC:
+ Get Report Descriptor
+
This ioctl returns the device's report descriptor using a
hidraw_report_descriptor struct. Make sure to set the size field of the
hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.
-HIDIOCGRAWINFO: Get Raw Info
+HIDIOCGRAWINFO:
+ Get Raw Info
+
This ioctl will return a hidraw_devinfo struct containing the bus type, the
vendor ID (VID), and product ID (PID) of the device. The bus type can be one
-of:
- BUS_USB
- BUS_HIL
- BUS_BLUETOOTH
- BUS_VIRTUAL
+of::
+
+ - BUS_USB
+ - BUS_HIL
+ - BUS_BLUETOOTH
+ - BUS_VIRTUAL
+
which are defined in uapi/linux/input.h.
-HIDIOCGRAWNAME(len): Get Raw Name
+HIDIOCGRAWNAME(len):
+ Get Raw Name
+
This ioctl returns a string containing the vendor and product strings of
the device. The returned string is Unicode, UTF-8 encoded.
-HIDIOCGRAWPHYS(len): Get Physical Address
+HIDIOCGRAWPHYS(len):
+ Get Physical Address
+
This ioctl returns a string representing the physical address of the device.
For USB devices, the string contains the physical path to the device (the
USB controller, hubs, ports, etc). For Bluetooth devices, the string
contains the hardware (MAC) address of the device.
-HIDIOCSFEATURE(len): Send a Feature Report
+HIDIOCSFEATURE(len):
+ Send a Feature Report
+
This ioctl will send a feature report to the device. Per the HID
specification, feature reports are always sent using the control endpoint.
Set the first byte of the supplied buffer to the report number. For devices
@@ -101,7 +117,9 @@ which do not use numbered reports, set the first byte to 0. The report data
begins in the second byte. Make sure to set len accordingly, to one more
than the length of the report (to account for the report number).
-HIDIOCGFEATURE(len): Get a Feature Report
+HIDIOCGFEATURE(len):
+ Get a Feature Report
+
This ioctl will request a feature report from the device using the control
endpoint. The first byte of the supplied buffer should be set to the report
number of the requested report. For devices which do not use numbered
@@ -109,11 +127,12 @@ reports, set the first byte to 0. The report will be returned starting at
the first byte of the buffer (ie: the report number is not returned).
Example
----------
+-------
In samples/, find hid-example.c, which shows examples of read(), write(),
and all the ioctls for hidraw. The code may be used by anyone for any
purpose, and can serve as a starting point for developing applications using
hidraw.
Document by:
+
Alan Ott <alan@signal11.us>, Signal 11 Software
diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst
new file mode 100644
index 000000000000..af4324902622
--- /dev/null
+++ b/Documentation/hid/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=============================
+Human Interface Devices (HID)
+=============================
+
+.. toctree::
+ :maxdepth: 1
+
+ hiddev
+ hidraw
+ hid-sensor
+ hid-transport
+
+ uhid
+
+ hid-alps
+ intel-ish-hid
diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst
new file mode 100644
index 000000000000..cccbf4be17d7
--- /dev/null
+++ b/Documentation/hid/intel-ish-hid.rst
@@ -0,0 +1,485 @@
+=================================
+Intel Integrated Sensor Hub (ISH)
+=================================
+
+A sensor hub enables the ability to offload sensor polling and algorithm
+processing to a dedicated low power co-processor. This allows the core
+processor to go into low power modes more often, resulting in the increased
+battery life.
+
+There are many vendors providing external sensor hubs confirming to HID
+Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
+and embedded products. Linux had this support since Linux 3.9.
+
+Intel® introduced integrated sensor hubs as a part of the SoC starting from
+Cherry Trail and now supported on multiple generations of CPU packages. There
+are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
+These ISH also comply to HID sensor specification, but the difference is the
+transport protocol used for communication. The current external sensor hubs
+mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
+
+1. Overview
+===========
+
+Using a analogy with a usbhid implementation, the ISH follows a similar model
+for a very high speed communication::
+
+ ----------------- ----------------------
+ | USB HID | --> | ISH HID |
+ ----------------- ----------------------
+ ----------------- ----------------------
+ | USB protocol | --> | ISH Transport |
+ ----------------- ----------------------
+ ----------------- ----------------------
+ | EHCI/XHCI | --> | ISH IPC |
+ ----------------- ----------------------
+ PCI PCI
+ ----------------- ----------------------
+ |Host controller| --> | ISH processor |
+ ----------------- ----------------------
+ USB Link
+ ----------------- ----------------------
+ | USB End points| --> | ISH Clients |
+ ----------------- ----------------------
+
+Like USB protocol provides a method for device enumeration, link management
+and user data encapsulation, the ISH also provides similar services. But it is
+very light weight tailored to manage and communicate with ISH client
+applications implemented in the firmware.
+
+The ISH allows multiple sensor management applications executing in the
+firmware. Like USB endpoints the messaging can be to/from a client. As part of
+enumeration process, these clients are identified. These clients can be simple
+HID sensor applications, sensor calibration application or senor firmware
+update application.
+
+The implementation model is similar, like USB bus, ISH transport is also
+implemented as a bus. Each client application executing in the ISH processor
+is registered as a device on this bus. The driver, which binds each device
+(ISH HID driver) identifies the device type and registers with the hid core.
+
+2. ISH Implementation: Block Diagram
+====================================
+
+::
+
+ ---------------------------
+ | User Space Applications |
+ ---------------------------
+
+ ----------------IIO ABI----------------
+ --------------------------
+ | IIO Sensor Drivers |
+ --------------------------
+ --------------------------
+ | IIO core |
+ --------------------------
+ --------------------------
+ | HID Sensor Hub MFD |
+ --------------------------
+ --------------------------
+ | HID Core |
+ --------------------------
+ --------------------------
+ | HID over ISH Client |
+ --------------------------
+ --------------------------
+ | ISH Transport (ISHTP) |
+ --------------------------
+ --------------------------
+ | IPC Drivers |
+ --------------------------
+ OS
+ ---------------- PCI -----------------
+ Hardware + Firmware
+ ----------------------------
+ | ISH Hardware/Firmware(FW) |
+ ----------------------------
+
+3. High level processing in above blocks
+========================================
+
+3.1 Hardware Interface
+----------------------
+
+The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
+product and vendor IDs are changed from different generations of processors. So
+the source code which enumerate drivers needs to update from generation to
+generation.
+
+3.2 Inter Processor Communication (IPC) driver
+----------------------------------------------
+
+Location: drivers/hid/intel-ish-hid/ipc
+
+The IPC message used memory mapped I/O. The registers are defined in
+hw-ish-regs.h.
+
+3.2.1 IPC/FW message types
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two types of messages, one for management of link and other messages
+are to and from transport layers.
+
+TX and RX of Transport messages
+...............................
+
+A set of memory mapped register offers support of multi byte messages TX and
+RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
+internal queues to sequence messages and send them in order to the FW.
+Optionally the caller can register handler to get notification of completion.
+A door bell mechanism is used in messaging to trigger processing in host and
+client firmware side. When ISH interrupt handler is called, the ISH2HOST
+doorbell register is used by host drivers to determine that the interrupt
+is for ISH.
+
+Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
+register has the following format:
+Bits 0..6: fragment length (7 bits are used)
+Bits 10..13: encapsulated protocol
+Bits 16..19: management command (for IPC management protocol)
+Bit 31: doorbell trigger (signal H/W interrupt to the other side)
+Other bits are reserved, should be 0.
+
+3.2.2 Transport layer interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To abstract HW level IPC communication, a set of callbacks are registered.
+The transport layer uses them to send and receive messages.
+Refer to struct ishtp_hw_ops for callbacks.
+
+3.3 ISH Transport layer
+-----------------------
+
+Location: drivers/hid/intel-ish-hid/ishtp/
+
+3.3.1 A Generic Transport Layer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The transport layer is a bi-directional protocol, which defines:
+- Set of commands to start, stop, connect, disconnect and flow control
+(ishtp/hbm.h) for details
+- A flow control mechanism to avoid buffer overflows
+
+This protocol resembles bus messages described in the following document:
+http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
+specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
+
+3.3.2 Connection and Flow Control Mechanism
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each FW client and a protocol is identified by an UUID. In order to communicate
+to a FW client, a connection must be established using connect request and
+response bus messages. If successful, a pair (host_client_id and fw_client_id)
+will identify the connection.
+
+Once connection is established, peers send each other flow control bus messages
+independently. Every peer may send a message only if it has received a
+flow-control credit before. Once it sent a message, it may not send another one
+before receiving the next flow control credit.
+Either side can send disconnect request bus message to end communication. Also
+the link will be dropped if major FW reset occurs.
+
+3.3.3 Peer to Peer data transfer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Peer to Peer data transfer can happen with or without using DMA. Depending on
+the sensor bandwidth requirement DMA can be enabled by using module parameter
+ishtp_use_dma under intel_ishtp.
+
+Each side (host and FW) manages its DMA transfer memory independently. When an
+ISHTP client from either host or FW side wants to send something, it decides
+whether to send over IPC or over DMA; for each transfer the decision is
+independent. The sending side sends DMA_XFER message when the message is in
+the respective host buffer (TX when host client sends, RX when FW client
+sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
+the sender that the memory region for that message may be reused.
+
+DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
+(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
+Additionally to DMA address communication, this sequence checks capabilities:
+if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
+send DMA; if FW doesn't support DMA then it won't respond with
+DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
+Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
+it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
+that it already did DMA and the message resides at host. Thus, DMA_XFER
+and DMA_XFER_ACK act as ownership indicators.
+
+At initial state all outgoing memory belongs to the sender (TX to host, RX to
+FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
+the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
+needs not wait for previous DMA_XFER to be ack'ed, and may send another message
+as long as remaining continuous memory in its ownership is enough.
+In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
+(up to IPC MTU), thus allowing for interrupt throttling.
+Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
+fragments and via IPC otherwise.
+
+3.3.4 Ring Buffers
+^^^^^^^^^^^^^^^^^^
+
+When a client initiate a connection, a ring or RX and TX buffers are allocated.
+The size of ring can be specified by the client. HID client set 16 and 32 for
+TX and RX buffers respectively. On send request from client, the data to be
+sent is copied to one of the send ring buffer and scheduled to be sent using
+bus message protocol. These buffers are required because the FW may have not
+have processed the last message and may not have enough flow control credits
+to send. Same thing holds true on receive side and flow control is required.
+
+3.3.5 Host Enumeration
+^^^^^^^^^^^^^^^^^^^^^^
+
+The host enumeration bus command allow discovery of clients present in the FW.
+There can be multiple sensor clients and clients for calibration function.
+
+To ease in implantation and allow independent driver handle each client
+this transport layer takes advantage of Linux Bus driver model. Each
+client is registered as device on the the transport bus (ishtp bus).
+
+Enumeration sequence of messages:
+
+- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
+- FW responds with HOST_START_RES_CMD
+- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
+- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
+ client IDs
+- For each FW ID found in that bitmap host sends
+ HOST_CLIENT_PROPERTIES_REQ_CMD
+- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
+ max ISHTP message size, etc.
+- Once host received properties for that last discovered client, it considers
+ ISHTP device fully functional (and allocates DMA buffers)
+
+3.4 HID over ISH Client
+-----------------------
+
+Location: drivers/hid/intel-ish-hid
+
+The ISHTP client driver is responsible for:
+
+- enumerate HID devices under FW ISH client
+- Get Report descriptor
+- Register with HID core as a LL driver
+- Process Get/Set feature request
+- Get input reports
+
+3.5 HID Sensor Hub MFD and IIO sensor drivers
+---------------------------------------------
+
+The functionality in these drivers is the same as an external sensor hub.
+Refer to
+Documentation/hid/hid-sensor.rst for HID sensor
+Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
+
+3.6 End to End HID transport Sequence Diagram
+---------------------------------------------
+
+::
+
+ HID-ISH-CLN ISHTP IPC HW
+ | | | |
+ | | |-----WAKE UP------------------>|
+ | | | |
+ | | |-----HOST READY--------------->|
+ | | | |
+ | | |<----MNG_RESET_NOTIFY_ACK----- |
+ | | | |
+ | |<----ISHTP_START------ | |
+ | | | |
+ | |<-----------------HOST_START_RES_CMD-------------------|
+ | | | |
+ | |------------------QUERY_SUBSCRIBER-------------------->|
+ | | | |
+ | |------------------HOST_ENUM_REQ_CMD------------------->|
+ | | | |
+ | |<-----------------HOST_ENUM_RES_CMD--------------------|
+ | | | |
+ | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
+ | | | |
+ | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
+ | Create new device on in ishtp bus | |
+ | | | |
+ | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
+ | | | |
+ | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
+ | Create new device on in ishtp bus | |
+ | | | |
+ | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
+ | | | |
+ probed()
+ |----ishtp_cl_connect--->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
+ | | | |
+ | |<----------------CLIENT_CONNECT_RES_CMD----------------|
+ | | | |
+ |register event callback | | |
+ | | | |
+ |ishtp_cl_send(
+ HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >|
+ | | | |
+ | | |<-----IRQ(IPC_PROTOCOL_ISHTP---|
+ | | | |
+ |<--ENUM_DEVICE RSP------| | |
+ | | | |
+ for each enumerated device
+ |ishtp_cl_send(
+ HOSTIF_GET_HID_DESCRIPTOR|----------fill ishtp_msg_hdr struct write to HW----- >|
+ | | | |
+ ...Response
+ | | | |
+ for each enumerated device
+ |ishtp_cl_send(
+ HOSTIF_GET_REPORT_DESCRIPTOR|--------------fill ishtp_msg_hdr struct write to HW-- >|
+ | | | |
+ | | | |
+ hid_allocate_device
+ | | | |
+ hid_add_device | | |
+ | | | |
+
+
+3.7 ISH Debugging
+-----------------
+
+To debug ISH, event tracing mechanism is used. To enable debug logs
+echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
+cat sys/kernel/debug/tracing/trace
+
+3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
+-----------------------------------------------------
+
+::
+
+ root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
+ /sys/bus/iio/devices/
+ ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
+ │ ├── buffer
+ │ │ ├── enable
+ │ │ ├── length
+ │ │ └── watermark
+ ...
+ │ ├── in_accel_hysteresis
+ │ ├── in_accel_offset
+ │ ├── in_accel_sampling_frequency
+ │ ├── in_accel_scale
+ │ ├── in_accel_x_raw
+ │ ├── in_accel_y_raw
+ │ ├── in_accel_z_raw
+ │ ├── name
+ │ ├── scan_elements
+ │ │ ├── in_accel_x_en
+ │ │ ├── in_accel_x_index
+ │ │ ├── in_accel_x_type
+ │ │ ├── in_accel_y_en
+ │ │ ├── in_accel_y_index
+ │ │ ├── in_accel_y_type
+ │ │ ├── in_accel_z_en
+ │ │ ├── in_accel_z_index
+ │ │ └── in_accel_z_type
+ ...
+ │ │ ├── devices
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_intensity_both_raw
+ │ │ │ │ ├── in_intensity_hysteresis
+ │ │ │ │ ├── in_intensity_offset
+ │ │ │ │ ├── in_intensity_sampling_frequency
+ │ │ │ │ ├── in_intensity_scale
+ │ │ │ │ ├── name
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_intensity_both_en
+ │ │ │ │ │ ├── in_intensity_both_index
+ │ │ │ │ │ └── in_intensity_both_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_magn_hysteresis
+ │ │ │ │ ├── in_magn_offset
+ │ │ │ │ ├── in_magn_sampling_frequency
+ │ │ │ │ ├── in_magn_scale
+ │ │ │ │ ├── in_magn_x_raw
+ │ │ │ │ ├── in_magn_y_raw
+ │ │ │ │ ├── in_magn_z_raw
+ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw
+ │ │ │ │ ├── in_rot_hysteresis
+ │ │ │ │ ├── in_rot_offset
+ │ │ │ │ ├── in_rot_sampling_frequency
+ │ │ │ │ ├── in_rot_scale
+ │ │ │ │ ├── name
+ ...
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_magn_x_en
+ │ │ │ │ │ ├── in_magn_x_index
+ │ │ │ │ │ ├── in_magn_x_type
+ │ │ │ │ │ ├── in_magn_y_en
+ │ │ │ │ │ ├── in_magn_y_index
+ │ │ │ │ │ ├── in_magn_y_type
+ │ │ │ │ │ ├── in_magn_z_en
+ │ │ │ │ │ ├── in_magn_z_index
+ │ │ │ │ │ ├── in_magn_z_type
+ │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en
+ │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index
+ │ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_anglvel_hysteresis
+ │ │ │ │ ├── in_anglvel_offset
+ │ │ │ │ ├── in_anglvel_sampling_frequency
+ │ │ │ │ ├── in_anglvel_scale
+ │ │ │ │ ├── in_anglvel_x_raw
+ │ │ │ │ ├── in_anglvel_y_raw
+ │ │ │ │ ├── in_anglvel_z_raw
+ │ │ │ │ ├── name
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_anglvel_x_en
+ │ │ │ │ │ ├── in_anglvel_x_index
+ │ │ │ │ │ ├── in_anglvel_x_type
+ │ │ │ │ │ ├── in_anglvel_y_en
+ │ │ │ │ │ ├── in_anglvel_y_index
+ │ │ │ │ │ ├── in_anglvel_y_type
+ │ │ │ │ │ ├── in_anglvel_z_en
+ │ │ │ │ │ ├── in_anglvel_z_index
+ │ │ │ │ │ └── in_anglvel_z_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
+ │ │ │ │ ├── buffer
+ │ │ │ │ │ ├── enable
+ │ │ │ │ │ ├── length
+ │ │ │ │ │ └── watermark
+ │ │ │ │ ├── dev
+ │ │ │ │ ├── in_anglvel_hysteresis
+ │ │ │ │ ├── in_anglvel_offset
+ │ │ │ │ ├── in_anglvel_sampling_frequency
+ │ │ │ │ ├── in_anglvel_scale
+ │ │ │ │ ├── in_anglvel_x_raw
+ │ │ │ │ ├── in_anglvel_y_raw
+ │ │ │ │ ├── in_anglvel_z_raw
+ │ │ │ │ ├── name
+ │ │ │ │ ├── scan_elements
+ │ │ │ │ │ ├── in_anglvel_x_en
+ │ │ │ │ │ ├── in_anglvel_x_index
+ │ │ │ │ │ ├── in_anglvel_x_type
+ │ │ │ │ │ ├── in_anglvel_y_en
+ │ │ │ │ │ ├── in_anglvel_y_index
+ │ │ │ │ │ ├── in_anglvel_y_type
+ │ │ │ │ │ ├── in_anglvel_z_en
+ │ │ │ │ │ ├── in_anglvel_z_index
+ │ │ │ │ │ └── in_anglvel_z_type
+ │ │ │ │ ├── trigger
+ │ │ │ │ │ └── current_trigger
+ ...
diff --git a/Documentation/hid/intel-ish-hid.txt b/Documentation/hid/intel-ish-hid.txt
deleted file mode 100644
index d48b21c71ddd..000000000000
--- a/Documentation/hid/intel-ish-hid.txt
+++ /dev/null
@@ -1,454 +0,0 @@
-Intel Integrated Sensor Hub (ISH)
-===============================
-
-A sensor hub enables the ability to offload sensor polling and algorithm
-processing to a dedicated low power co-processor. This allows the core
-processor to go into low power modes more often, resulting in the increased
-battery life.
-
-There are many vendors providing external sensor hubs confirming to HID
-Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
-and embedded products. Linux had this support since Linux 3.9.
-
-Intel® introduced integrated sensor hubs as a part of the SoC starting from
-Cherry Trail and now supported on multiple generations of CPU packages. There
-are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
-These ISH also comply to HID sensor specification, but the difference is the
-transport protocol used for communication. The current external sensor hubs
-mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
-
-1. Overview
-
-Using a analogy with a usbhid implementation, the ISH follows a similar model
-for a very high speed communication:
-
- ----------------- ----------------------
- | USB HID | --> | ISH HID |
- ----------------- ----------------------
- ----------------- ----------------------
- | USB protocol | --> | ISH Transport |
- ----------------- ----------------------
- ----------------- ----------------------
- | EHCI/XHCI | --> | ISH IPC |
- ----------------- ----------------------
- PCI PCI
- ----------------- ----------------------
- |Host controller| --> | ISH processor |
- ----------------- ----------------------
- USB Link
- ----------------- ----------------------
- | USB End points| --> | ISH Clients |
- ----------------- ----------------------
-
-Like USB protocol provides a method for device enumeration, link management
-and user data encapsulation, the ISH also provides similar services. But it is
-very light weight tailored to manage and communicate with ISH client
-applications implemented in the firmware.
-
-The ISH allows multiple sensor management applications executing in the
-firmware. Like USB endpoints the messaging can be to/from a client. As part of
-enumeration process, these clients are identified. These clients can be simple
-HID sensor applications, sensor calibration application or senor firmware
-update application.
-
-The implementation model is similar, like USB bus, ISH transport is also
-implemented as a bus. Each client application executing in the ISH processor
-is registered as a device on this bus. The driver, which binds each device
-(ISH HID driver) identifies the device type and registers with the hid core.
-
-2. ISH Implementation: Block Diagram
-
- ---------------------------
- | User Space Applications |
- ---------------------------
-
-----------------IIO ABI----------------
- --------------------------
- | IIO Sensor Drivers |
- --------------------------
- --------------------------
- | IIO core |
- --------------------------
- --------------------------
- | HID Sensor Hub MFD |
- --------------------------
- --------------------------
- | HID Core |
- --------------------------
- --------------------------
- | HID over ISH Client |
- --------------------------
- --------------------------
- | ISH Transport (ISHTP) |
- --------------------------
- --------------------------
- | IPC Drivers |
- --------------------------
-OS
----------------- PCI -----------------
-Hardware + Firmware
- ----------------------------
- | ISH Hardware/Firmware(FW) |
- ----------------------------
-
-3. High level processing in above blocks
-
-3.1 Hardware Interface
-
-The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
-product and vendor IDs are changed from different generations of processors. So
-the source code which enumerate drivers needs to update from generation to
-generation.
-
-3.2 Inter Processor Communication (IPC) driver
-Location: drivers/hid/intel-ish-hid/ipc
-
-The IPC message used memory mapped I/O. The registers are defined in
-hw-ish-regs.h.
-
-3.2.1 IPC/FW message types
-
-There are two types of messages, one for management of link and other messages
-are to and from transport layers.
-
-TX and RX of Transport messages
-
-A set of memory mapped register offers support of multi byte messages TX and
-RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
-internal queues to sequence messages and send them in order to the FW.
-Optionally the caller can register handler to get notification of completion.
-A door bell mechanism is used in messaging to trigger processing in host and
-client firmware side. When ISH interrupt handler is called, the ISH2HOST
-doorbell register is used by host drivers to determine that the interrupt
-is for ISH.
-
-Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
-register has the following format:
-Bits 0..6: fragment length (7 bits are used)
-Bits 10..13: encapsulated protocol
-Bits 16..19: management command (for IPC management protocol)
-Bit 31: doorbell trigger (signal H/W interrupt to the other side)
-Other bits are reserved, should be 0.
-
-3.2.2 Transport layer interface
-
-To abstract HW level IPC communication, a set of callbacks are registered.
-The transport layer uses them to send and receive messages.
-Refer to struct ishtp_hw_ops for callbacks.
-
-3.3 ISH Transport layer
-Location: drivers/hid/intel-ish-hid/ishtp/
-
-3.3.1 A Generic Transport Layer
-
-The transport layer is a bi-directional protocol, which defines:
-- Set of commands to start, stop, connect, disconnect and flow control
-(ishtp/hbm.h) for details
-- A flow control mechanism to avoid buffer overflows
-
-This protocol resembles bus messages described in the following document:
-http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
-specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
-
-3.3.2 Connection and Flow Control Mechanism
-
-Each FW client and a protocol is identified by an UUID. In order to communicate
-to a FW client, a connection must be established using connect request and
-response bus messages. If successful, a pair (host_client_id and fw_client_id)
-will identify the connection.
-
-Once connection is established, peers send each other flow control bus messages
-independently. Every peer may send a message only if it has received a
-flow-control credit before. Once it sent a message, it may not send another one
-before receiving the next flow control credit.
-Either side can send disconnect request bus message to end communication. Also
-the link will be dropped if major FW reset occurs.
-
-3.3.3 Peer to Peer data transfer
-
-Peer to Peer data transfer can happen with or without using DMA. Depending on
-the sensor bandwidth requirement DMA can be enabled by using module parameter
-ishtp_use_dma under intel_ishtp.
-
-Each side (host and FW) manages its DMA transfer memory independently. When an
-ISHTP client from either host or FW side wants to send something, it decides
-whether to send over IPC or over DMA; for each transfer the decision is
-independent. The sending side sends DMA_XFER message when the message is in
-the respective host buffer (TX when host client sends, RX when FW client
-sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
-the sender that the memory region for that message may be reused.
-
-DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
-(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
-Additionally to DMA address communication, this sequence checks capabilities:
-if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
-send DMA; if FW doesn't support DMA then it won't respond with
-DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
-Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
-it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
-that it already did DMA and the message resides at host. Thus, DMA_XFER
-and DMA_XFER_ACK act as ownership indicators.
-
-At initial state all outgoing memory belongs to the sender (TX to host, RX to
-FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
-the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
-needs not wait for previous DMA_XFER to be ack'ed, and may send another message
-as long as remaining continuous memory in its ownership is enough.
-In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
-(up to IPC MTU), thus allowing for interrupt throttling.
-Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
-fragments and via IPC otherwise.
-
-3.3.4 Ring Buffers
-
-When a client initiate a connection, a ring or RX and TX buffers are allocated.
-The size of ring can be specified by the client. HID client set 16 and 32 for
-TX and RX buffers respectively. On send request from client, the data to be
-sent is copied to one of the send ring buffer and scheduled to be sent using
-bus message protocol. These buffers are required because the FW may have not
-have processed the last message and may not have enough flow control credits
-to send. Same thing holds true on receive side and flow control is required.
-
-3.3.5 Host Enumeration
-
-The host enumeration bus command allow discovery of clients present in the FW.
-There can be multiple sensor clients and clients for calibration function.
-
-To ease in implantation and allow independent driver handle each client
-this transport layer takes advantage of Linux Bus driver model. Each
-client is registered as device on the the transport bus (ishtp bus).
-
-Enumeration sequence of messages:
-- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
-- FW responds with HOST_START_RES_CMD
-- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
-- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
-client IDs
-- For each FW ID found in that bitmap host sends
-HOST_CLIENT_PROPERTIES_REQ_CMD
-- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
-max ISHTP message size, etc.
-- Once host received properties for that last discovered client, it considers
-ISHTP device fully functional (and allocates DMA buffers)
-
-3.4 HID over ISH Client
-Location: drivers/hid/intel-ish-hid
-
-The ISHTP client driver is responsible for:
-- enumerate HID devices under FW ISH client
-- Get Report descriptor
-- Register with HID core as a LL driver
-- Process Get/Set feature request
-- Get input reports
-
-3.5 HID Sensor Hub MFD and IIO sensor drivers
-
-The functionality in these drivers is the same as an external sensor hub.
-Refer to
-Documentation/hid/hid-sensor.txt for HID sensor
-Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
-
-3.6 End to End HID transport Sequence Diagram
-
-HID-ISH-CLN ISHTP IPC HW
- | | | |
- | | |-----WAKE UP------------------>|
- | | | |
- | | |-----HOST READY--------------->|
- | | | |
- | | |<----MNG_RESET_NOTIFY_ACK----- |
- | | | |
- | |<----ISHTP_START------ | |
- | | | |
- | |<-----------------HOST_START_RES_CMD-------------------|
- | | | |
- | |------------------QUERY_SUBSCRIBER-------------------->|
- | | | |
- | |------------------HOST_ENUM_REQ_CMD------------------->|
- | | | |
- | |<-----------------HOST_ENUM_RES_CMD--------------------|
- | | | |
- | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
- | | | |
- | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
- | Create new device on in ishtp bus | |
- | | | |
- | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
- | | | |
- | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
- | Create new device on in ishtp bus | |
- | | | |
- | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
- | | | |
- probed()
- |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
- | | | |
- | |<----------------CLIENT_CONNECT_RES_CMD----------------|
- | | | |
- |register event callback| | |
- | | | |
- |ishtp_cl_send(
- HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >|
- | | | |
- | | |<-----IRQ(IPC_PROTOCOL_ISHTP---|
- | | | |
- |<--ENUM_DEVICE RSP-----| | |
- | | | |
-for each enumerated device
- |ishtp_cl_send(
- HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW--- >|
- | | | |
- ...Response
- | | | |
-for each enumerated device
- |ishtp_cl_send(
- HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >|
- | | | |
- | | | |
- hid_allocate_device
- | | | |
- hid_add_device | | |
- | | | |
-
-
-3.7 ISH Debugging
-
-To debug ISH, event tracing mechanism is used. To enable debug logs
-echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
-cat sys/kernel/debug/tracing/trace
-
-3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
-
-root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
-/sys/bus/iio/devices/
-├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
-│ ├── buffer
-│ │ ├── enable
-│ │ ├── length
-│ │ └── watermark
-...
-│ ├── in_accel_hysteresis
-│ ├── in_accel_offset
-│ ├── in_accel_sampling_frequency
-│ ├── in_accel_scale
-│ ├── in_accel_x_raw
-│ ├── in_accel_y_raw
-│ ├── in_accel_z_raw
-│ ├── name
-│ ├── scan_elements
-│ │ ├── in_accel_x_en
-│ │ ├── in_accel_x_index
-│ │ ├── in_accel_x_type
-│ │ ├── in_accel_y_en
-│ │ ├── in_accel_y_index
-│ │ ├── in_accel_y_type
-│ │ ├── in_accel_z_en
-│ │ ├── in_accel_z_index
-│ │ └── in_accel_z_type
-...
-│ │ ├── devices
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_intensity_both_raw
-│ │ │ │ ├── in_intensity_hysteresis
-│ │ │ │ ├── in_intensity_offset
-│ │ │ │ ├── in_intensity_sampling_frequency
-│ │ │ │ ├── in_intensity_scale
-│ │ │ │ ├── name
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_intensity_both_en
-│ │ │ │ │ ├── in_intensity_both_index
-│ │ │ │ │ └── in_intensity_both_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_magn_hysteresis
-│ │ │ │ ├── in_magn_offset
-│ │ │ │ ├── in_magn_sampling_frequency
-│ │ │ │ ├── in_magn_scale
-│ │ │ │ ├── in_magn_x_raw
-│ │ │ │ ├── in_magn_y_raw
-│ │ │ │ ├── in_magn_z_raw
-│ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw
-│ │ │ │ ├── in_rot_hysteresis
-│ │ │ │ ├── in_rot_offset
-│ │ │ │ ├── in_rot_sampling_frequency
-│ │ │ │ ├── in_rot_scale
-│ │ │ │ ├── name
-...
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_magn_x_en
-│ │ │ │ │ ├── in_magn_x_index
-│ │ │ │ │ ├── in_magn_x_type
-│ │ │ │ │ ├── in_magn_y_en
-│ │ │ │ │ ├── in_magn_y_index
-│ │ │ │ │ ├── in_magn_y_type
-│ │ │ │ │ ├── in_magn_z_en
-│ │ │ │ │ ├── in_magn_z_index
-│ │ │ │ │ ├── in_magn_z_type
-│ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en
-│ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index
-│ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_anglvel_hysteresis
-│ │ │ │ ├── in_anglvel_offset
-│ │ │ │ ├── in_anglvel_sampling_frequency
-│ │ │ │ ├── in_anglvel_scale
-│ │ │ │ ├── in_anglvel_x_raw
-│ │ │ │ ├── in_anglvel_y_raw
-│ │ │ │ ├── in_anglvel_z_raw
-│ │ │ │ ├── name
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_anglvel_x_en
-│ │ │ │ │ ├── in_anglvel_x_index
-│ │ │ │ │ ├── in_anglvel_x_type
-│ │ │ │ │ ├── in_anglvel_y_en
-│ │ │ │ │ ├── in_anglvel_y_index
-│ │ │ │ │ ├── in_anglvel_y_type
-│ │ │ │ │ ├── in_anglvel_z_en
-│ │ │ │ │ ├── in_anglvel_z_index
-│ │ │ │ │ └── in_anglvel_z_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
-│ │ │ │ ├── buffer
-│ │ │ │ │ ├── enable
-│ │ │ │ │ ├── length
-│ │ │ │ │ └── watermark
-│ │ │ │ ├── dev
-│ │ │ │ ├── in_anglvel_hysteresis
-│ │ │ │ ├── in_anglvel_offset
-│ │ │ │ ├── in_anglvel_sampling_frequency
-│ │ │ │ ├── in_anglvel_scale
-│ │ │ │ ├── in_anglvel_x_raw
-│ │ │ │ ├── in_anglvel_y_raw
-│ │ │ │ ├── in_anglvel_z_raw
-│ │ │ │ ├── name
-│ │ │ │ ├── scan_elements
-│ │ │ │ │ ├── in_anglvel_x_en
-│ │ │ │ │ ├── in_anglvel_x_index
-│ │ │ │ │ ├── in_anglvel_x_type
-│ │ │ │ │ ├── in_anglvel_y_en
-│ │ │ │ │ ├── in_anglvel_y_index
-│ │ │ │ │ ├── in_anglvel_y_type
-│ │ │ │ │ ├── in_anglvel_z_en
-│ │ │ │ │ ├── in_anglvel_z_index
-│ │ │ │ │ └── in_anglvel_z_type
-│ │ │ │ ├── trigger
-│ │ │ │ │ └── current_trigger
-...
diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.rst
similarity index 94%
rename from Documentation/hid/uhid.txt
rename to Documentation/hid/uhid.rst
index 958fff945304..b18cb96c885f 100644
--- a/Documentation/hid/uhid.txt
+++ b/Documentation/hid/uhid.rst
@@ -1,5 +1,6 @@
- UHID - User-space I/O driver support for HID subsystem
- ========================================================
+======================================================
+UHID - User-space I/O driver support for HID subsystem
+======================================================
UHID allows user-space to implement HID transport drivers. Please see
hid-transport.txt for an introduction into HID transport drivers. This document
@@ -22,9 +23,9 @@ If a new device is detected by your HID I/O Driver and you want to register this
device with the HID subsystem, then you need to open /dev/uhid once for each
device you want to register. All further communication is done by read()'ing or
write()'ing "struct uhid_event" objects. Non-blocking operations are supported
-by setting O_NONBLOCK.
+by setting O_NONBLOCK::
-struct uhid_event {
+ struct uhid_event {
__u32 type;
union {
struct uhid_create2_req create2;
@@ -32,7 +33,7 @@ struct uhid_event {
struct uhid_input2_req input2;
...
} u;
-};
+ };
The "type" field contains the ID of the event. Depending on the ID different
payloads are sent. You must not split a single event across multiple read()'s or
@@ -86,31 +87,31 @@ the request was handled successfully. O_NONBLOCK does not affect write() as
writes are always handled immediately in a non-blocking fashion. Future requests
might make use of O_NONBLOCK, though.
- UHID_CREATE2:
+UHID_CREATE2:
This creates the internal HID device. No I/O is possible until you send this
event to the kernel. The payload is of type struct uhid_create2_req and
contains information about your device. You can start I/O now.
- UHID_DESTROY:
+UHID_DESTROY:
This destroys the internal HID device. No further I/O will be accepted. There
may still be pending messages that you can receive with read() but no further
UHID_INPUT events can be sent to the kernel.
You can create a new device by sending UHID_CREATE2 again. There is no need to
reopen the character device.
- UHID_INPUT2:
+UHID_INPUT2:
You must send UHID_CREATE2 before sending input to the kernel! This event
contains a data-payload. This is the raw data that you read from your device
on the interrupt channel. The kernel will parse the HID reports.
- UHID_GET_REPORT_REPLY:
+UHID_GET_REPORT_REPLY:
If you receive a UHID_GET_REPORT request you must answer with this request.
You must copy the "id" field from the request into the answer. Set the "err"
field to 0 if no error occurred or to EIO if an I/O error occurred.
If "err" is 0 then you should fill the buffer of the answer with the results
of the GET_REPORT request and set "size" correspondingly.
- UHID_SET_REPORT_REPLY:
+UHID_SET_REPORT_REPLY:
This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
"id" and "err" fields correctly.
@@ -120,16 +121,18 @@ read()
read() will return a queued output report. No reaction is required to any of
them but you should handle them according to your needs.
- UHID_START:
+UHID_START:
This is sent when the HID device is started. Consider this as an answer to
UHID_CREATE2. This is always the first event that is sent. Note that this
event might not be available immediately after write(UHID_CREATE2) returns.
Device drivers might required delayed setups.
This event contains a payload of type uhid_start_req. The "dev_flags" field
describes special behaviors of a device. The following flags are defined:
- UHID_DEV_NUMBERED_FEATURE_REPORTS:
- UHID_DEV_NUMBERED_OUTPUT_REPORTS:
- UHID_DEV_NUMBERED_INPUT_REPORTS:
+
+ - UHID_DEV_NUMBERED_FEATURE_REPORTS
+ - UHID_DEV_NUMBERED_OUTPUT_REPORTS
+ - UHID_DEV_NUMBERED_INPUT_REPORTS
+
Each of these flags defines whether a given report-type uses numbered
reports. If numbered reports are used for a type, all messages from
the kernel already have the report-number as prefix. Otherwise, no
@@ -137,33 +140,35 @@ them but you should handle them according to your needs.
For messages sent by user-space to the kernel, you must adjust the
prefixes according to these flags.
- UHID_STOP:
+UHID_STOP:
This is sent when the HID device is stopped. Consider this as an answer to
UHID_DESTROY.
+
If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
UHID_STOP event, this should usually be ignored. It means that the kernel
reloaded/changed the device driver loaded on your HID device (or some other
maintenance actions happened).
+
You can usually ignored any UHID_STOP events safely.
- UHID_OPEN:
+UHID_OPEN:
This is sent when the HID device is opened. That is, the data that the HID
device provides is read by some other process. You may ignore this event but
it is useful for power-management. As long as you haven't received this event
there is actually no other process that reads your data so there is no need to
send UHID_INPUT2 events to the kernel.
- UHID_CLOSE:
+UHID_CLOSE:
This is sent when there are no more processes which read the HID data. It is
the counterpart of UHID_OPEN and you may as well ignore this event.
- UHID_OUTPUT:
+UHID_OUTPUT:
This is sent if the HID device driver wants to send raw data to the I/O
device on the interrupt channel. You should read the payload and forward it to
the device. The payload is of type "struct uhid_output_req".
This may be received even though you haven't received UHID_OPEN, yet.
- UHID_GET_REPORT:
+UHID_GET_REPORT:
This event is sent if the kernel driver wants to perform a GET_REPORT request
on the control channeld as described in the HID specs. The report-type and
report-number are available in the payload.
@@ -177,11 +182,12 @@ them but you should handle them according to your needs.
timed out, the kernel will ignore the response silently. The "id" field is
never re-used, so conflicts cannot happen.
- UHID_SET_REPORT:
+UHID_SET_REPORT:
This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
send a SET_REPORT request to your hid device. Once it replies, you must tell
the kernel about it via UHID_SET_REPORT_REPLY.
The same restrictions as for UHID_GET_REPORT apply.
----------------------------------------------------
+
Written 2012, David Herrmann <dh.herrmann@gmail.com>
diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst
index 47f86a4bf16c..0eb61e67a7b7 100644
--- a/Documentation/input/input.rst
+++ b/Documentation/input/input.rst
@@ -188,7 +188,7 @@ LCDs and many other purposes.
The monitor and speaker controls should be easy to add to the hid/input
interface, but for the UPSs and LCDs it doesn't make much sense. For this,
-the hiddev interface was designed. See Documentation/hid/hiddev.txt
+the hiddev interface was designed. See Documentation/hid/hiddev.rst
for more information about it.
The usage of the usbhid module is very simple, it takes no parameters,
diff --git a/MAINTAINERS b/MAINTAINERS
index 8d39979e4091..969225e6bfce 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16383,7 +16383,7 @@ M: Benjamin Tissoires <benjamin.tissoires@redhat.com>
L: linux-usb@vger.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git
S: Maintained
-F: Documentation/hid/hiddev.txt
+F: Documentation/hid/hiddev.rst
F: drivers/hid/usbhid/
USB INTEL XHCI ROLE MUX DRIVER
--
2.21.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox