* [PATCH 00/43] Convert doc files to ReST
@ 2019-06-28 12:19 Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (42 more replies)
0 siblings, 43 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:19 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This patchset contains the patches that weren't merged yet from
part 2 and 3 of the previous ReST conversion patchset.
This is based aganst linux-next (next-20190627), so they may not
apply cleanly at docs-next.
It does contain file renames, but, except for a few exceptions, the files
are kept where they are.
The first patches on this series were agreed to be merged via subsystem's
tree, but, as they didn't appear at -next, I'm recending as a gentile
ping.
Mauro Carvalho Chehab (43):
docs: infiniband: convert docs to ReST and rename to *.rst
docs: iio: convert to ReST
docs: hid: convert to ReST
docs: locking: convert docs to ReST and rename to *.rst
docs: powerpc: convert docs to ReST and rename to *.rst
docs: connector: convert to ReST and rename to connector.rst
docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
docs: lp855x-driver.txt: convert to ReST and move to kernel-api
docs: m68k: convert docs to ReST and rename to *.rst
docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst
docs: console.txt: convert docs to ReST and rename to *.rst
docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst
docs: early-userspace: convert docs to ReST and rename to *.rst
docs: arm: convert docs to ReST and rename to *.rst
docs: memory-devices: convert ti-emif.txt to ReST
docs: xen-tpmfront.txt: convert it to .rst
docs: bus-devices: ti-gpmc.rst: convert it to ReST
docs: nvmem: convert docs to ReST and rename to *.rst
docs: phy: convert samsung-usb2.txt to ReST format
docs: rbtree.txt: fix Sphinx build warnings
docs: DMA-API-HOWTO.txt: fix an unmarked code block
docs: accounting: convert to ReST
docs: ia64: convert to ReST
docs: leds: convert to ReST
docs: laptops: convert to ReST
docs: namespaces: convert to ReST
docs: nfc: convert to ReST
docs: md: convert to ReST
docs: mtd: convert to ReST
docs: nvdimm: convert to ReST
docs: xtensa: convert to ReST
docs: mmc: convert to ReST
docs: ioctl-number.txt: convert it to ReST format
docs: ioctl: convert to ReST
docs: thermal: convert to ReST
docs: rapidio: convert to ReST
docs: blockdev: convert to ReST
docs: perf: convert to ReST
docs: sysctl: convert to ReST
docs: block: convert to ReST
docs: extcon: convert it to ReST and move to acpi dir
docs: move gcc_plugins.txt to core-api and rename to .rst
docs: logo.txt: rename it to COPYING-logo
Documentation/ABI/testing/sysfs-block-device | 2 +-
.../ABI/testing/sysfs-platform-asus-laptop | 2 +-
Documentation/{logo.txt => COPYING-logo} | 0
Documentation/DMA-API-HOWTO.txt | 2 +-
Documentation/PCI/pci-error-recovery.rst | 23 +-
.../{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 +-
.../admin-guide/kernel-parameters.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 30 +-
Documentation/admin-guide/mm/index.rst | 2 +-
Documentation/admin-guide/mm/ksm.rst | 2 +-
Documentation/arm/Marvell/README | 395 ------
Documentation/arm/Netwinder | 78 --
Documentation/arm/SA1100/FreeBird | 21 -
Documentation/arm/SA1100/empeg | 2 -
Documentation/arm/SA1100/serial_UART | 47 -
Documentation/arm/{README => arm.rst} | 50 +-
Documentation/arm/{Booting => booting.rst} | 71 +-
...ance.txt => cluster-pm-race-avoidance.rst} | 177 ++-
.../arm/{firmware.txt => firmware.rst} | 14 +-
Documentation/arm/index.rst | 80 ++
.../arm/{Interrupts => interrupts.rst} | 86 +-
Documentation/arm/{IXP4xx => ixp4xx.rst} | 61 +-
...nel_mode_neon.txt => kernel_mode_neon.rst} | 3 +
...er_helpers.txt => kernel_user_helpers.rst} | 79 +-
.../keystone/{knav-qmss.txt => knav-qmss.rst} | 6 +-
.../keystone/{Overview.txt => overview.rst} | 47 +-
Documentation/arm/marvel.rst | 488 +++++++
.../arm/{mem_alignment => mem_alignment.rst} | 11 +-
Documentation/arm/{memory.txt => memory.rst} | 9 +-
.../arm/{Microchip/README => microchip.rst} | 63 +-
Documentation/arm/netwinder.rst | 85 ++
Documentation/arm/nwfpe/index.rst | 11 +
.../nwfpe/{README.FPE => netwinder-fpe.rst} | 24 +-
Documentation/arm/nwfpe/{NOTES => notes.rst} | 3 +
Documentation/arm/nwfpe/{README => nwfpe.rst} | 10 +-
Documentation/arm/nwfpe/{TODO => todo.rst} | 47 +-
Documentation/arm/{OMAP/DSS => omap/dss.rst} | 112 +-
Documentation/arm/omap/index.rst | 10 +
.../arm/{OMAP/README => omap/omap.rst} | 7 +
.../arm/{OMAP/omap_pm => omap/omap_pm.rst} | 55 +-
Documentation/arm/{Porting => porting.rst} | 14 +-
Documentation/arm/pxa/{mfp.txt => mfp.rst} | 106 +-
.../{SA1100/ADSBitsy => sa1100/adsbitsy.rst} | 14 +-
.../{SA1100/Assabet => sa1100/assabet.rst} | 185 +--
.../arm/{SA1100/Brutus => sa1100/brutus.rst} | 45 +-
.../arm/{SA1100/CERF => sa1100/cerf.rst} | 10 +-
Documentation/arm/sa1100/freebird.rst | 25 +
.../graphicsclient.rst} | 46 +-
.../graphicsmaster.rst} | 13 +-
.../HUW_WEBPANEL => sa1100/huw_webpanel.rst} | 8 +-
Documentation/arm/sa1100/index.rst | 23 +
.../arm/{SA1100/Itsy => sa1100/itsy.rst} | 14 +-
.../arm/{SA1100/LART => sa1100/lart.rst} | 3 +-
.../nanoEngine => sa1100/nanoengine.rst} | 6 +-
.../{SA1100/Pangolin => sa1100/pangolin.rst} | 10 +-
.../arm/{SA1100/PLEB => sa1100/pleb.rst} | 6 +-
Documentation/arm/sa1100/serial_uart.rst | 51 +
.../arm/{SA1100/Tifon => sa1100/tifon.rst} | 4 +-
.../arm/{SA1100/Yopy => sa1100/yopy.rst} | 5 +-
.../cpufreq.rst} | 5 +-
.../eb2410itx.rst} | 5 +-
.../GPIO.txt => samsung-s3c24xx/gpio.rst} | 23 +-
.../H1940.txt => samsung-s3c24xx/h1940.rst} | 5 +-
Documentation/arm/samsung-s3c24xx/index.rst | 18 +
.../NAND.txt => samsung-s3c24xx/nand.rst} | 6 +-
.../overview.rst} | 21 +-
.../s3c2412.rst} | 5 +-
.../s3c2413.rst} | 7 +-
.../smdk2440.rst} | 5 +-
.../suspend.rst} | 20 +-
.../usb-host.rst} | 16 +-
.../bootloader-interface.rst} | 27 +-
.../clksrc-change-registers.awk | 0
.../{Samsung/GPIO.txt => samsung/gpio.rst} | 7 +-
Documentation/arm/samsung/index.rst | 10 +
.../Overview.txt => samsung/overview.rst} | 15 +-
Documentation/arm/{Setup => setup.rst} | 49 +-
.../arm/{SH-Mobile => sh-mobile}/.gitignore | 0
.../overview.txt => spear/overview.rst} | 20 +-
.../arm/sti/{overview.txt => overview.rst} | 21 +-
...h407-overview.txt => stih407-overview.rst} | 9 +-
...h415-overview.txt => stih415-overview.rst} | 8 +-
...h416-overview.txt => stih416-overview.rst} | 5 +-
...h418-overview.txt => stih418-overview.rst} | 9 +-
Documentation/arm/stm32/overview.rst | 2 -
.../arm/stm32/stm32f429-overview.rst | 7 +-
.../arm/stm32/stm32f746-overview.rst | 7 +-
.../arm/stm32/stm32f769-overview.rst | 7 +-
.../arm/stm32/stm32h743-overview.rst | 7 +-
.../arm/stm32/stm32mp157-overview.rst | 3 +-
Documentation/arm/{sunxi/README => sunxi.rst} | 98 +-
.../arm/sunxi/{clocks.txt => clocks.rst} | 7 +-
.../arm/{swp_emulation => swp_emulation.rst} | 24 +-
Documentation/arm/{tcm.txt => tcm.rst} | 54 +-
Documentation/arm/{uefi.txt => uefi.rst} | 39 +-
.../release-notes.rst} | 4 +-
Documentation/arm/{vlocks.txt => vlocks.rst} | 9 +-
...cd-panel-cgram.txt => lcd-panel-cgram.rst} | 9 +-
Documentation/backlight/lp855x-driver.rst | 83 ++
Documentation/backlight/lp855x-driver.txt | 66 -
.../{bfq-iosched.txt => bfq-iosched.rst} | 66 +-
.../block/{biodoc.txt => biodoc.rst} | 328 +++--
.../block/{biovecs.txt => biovecs.rst} | 20 +-
Documentation/block/capability.rst | 18 +
Documentation/block/capability.txt | 15 -
...ne-partition.txt => cmdline-partition.rst} | 13 +-
...{data-integrity.txt => data-integrity.rst} | 60 +-
...dline-iosched.txt => deadline-iosched.rst} | 21 +-
Documentation/block/index.rst | 25 +
.../block/{ioprio.txt => ioprio.rst} | 95 +-
.../{kyber-iosched.txt => kyber-iosched.rst} | 3 +-
.../block/{null_blk.txt => null_blk.rst} | 65 +-
Documentation/block/{pr.txt => pr.rst} | 18 +-
.../{queue-sysfs.txt => queue-sysfs.rst} | 7 +-
.../block/{request.txt => request.rst} | 47 +-
Documentation/block/{stat.txt => stat.rst} | 13 +-
...witching-sched.txt => switching-sched.rst} | 28 +-
...ontrol.txt => writeback_cache_control.rst} | 12 +-
...structure-v9.txt => data-structure-v9.rst} | 6 +-
Documentation/blockdev/drbd/figures.rst | 28 +
.../blockdev/drbd/{README.txt => index.rst} | 15 +-
.../blockdev/{floppy.txt => floppy.rst} | 88 +-
Documentation/blockdev/index.rst | 16 +
Documentation/blockdev/{nbd.txt => nbd.rst} | 2 +-
.../blockdev/{paride.txt => paride.rst} | 194 +--
.../blockdev/{ramdisk.txt => ramdisk.rst} | 55 +-
Documentation/blockdev/{zram.txt => zram.rst} | 197 ++-
.../bus-devices/{ti-gpmc.txt => ti-gpmc.rst} | 159 ++-
.../cma/{debugfs.txt => debugfs.rst} | 8 +-
.../{connector.txt => connector.rst} | 130 +-
.../console/{console.txt => console.rst} | 63 +-
.../gcc-plugins.rst} | 0
Documentation/core-api/index.rst | 2 +-
Documentation/core-api/printk-formats.rst | 2 +-
Documentation/devicetree/bindings/arm/xen.txt | 2 +-
.../devicetree/booting-without-of.txt | 4 +-
.../{buffer-format.txt => buffer-format.rst} | 19 +-
.../{README => early_userspace_support.rst} | 3 +
Documentation/early-userspace/index.rst | 18 +
Documentation/fb/fbcon.rst | 4 +-
Documentation/filesystems/nfs/nfsroot.txt | 2 +-
.../filesystems/ramfs-rootfs-initramfs.txt | 4 +-
.../acpi/extcon-intel-int3496.rst} | 14 +-
Documentation/firmware-guide/acpi/index.rst | 1 +
.../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 +-
.../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 ---
.../iio/{ep93xx_adc.txt => ep93xx_adc.rst} | 15 +-
.../{iio_configfs.txt => iio_configfs.rst} | 52 +-
Documentation/iio/index.rst | 12 +
Documentation/index.rst | 1 +
.../{core_locking.txt => core_locking.rst} | 64 +-
Documentation/infiniband/index.rst | 23 +
.../infiniband/{ipoib.txt => ipoib.rst} | 24 +-
.../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +-
.../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
.../{tag_matching.txt => tag_matching.rst} | 5 +
.../infiniband/{user_mad.txt => user_mad.rst} | 33 +-
.../{user_verbs.txt => user_verbs.rst} | 12 +-
Documentation/input/input.rst | 2 +-
...g-up-ioctls.txt => botching-up-ioctls.rst} | 1 +
Documentation/ioctl/cdrom.rst | 1233 +++++++++++++++++
Documentation/ioctl/cdrom.txt | 967 -------------
Documentation/ioctl/{hdio.txt => hdio.rst} | 835 +++++++----
Documentation/ioctl/index.rst | 16 +
...{ioctl-decoding.txt => ioctl-decoding.rst} | 13 +-
Documentation/ioctl/ioctl-number.rst | 362 +++++
Documentation/ioctl/ioctl-number.txt | 350 -----
Documentation/kernel-hacking/locking.rst | 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} | 367 +++--
.../{toshiba_haps.txt => toshiba_haps.rst} | 47 +-
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 +-
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/m68k/index.rst | 17 +
...{kernel-options.txt => kernel-options.rst} | 319 +++--
Documentation/md/index.rst | 12 +
.../md/{md-cluster.txt => md-cluster.rst} | 188 ++-
.../md/{raid5-cache.txt => raid5-cache.rst} | 28 +-
.../md/{raid5-ppl.txt => raid5-ppl.rst} | 2 +
.../{ti-emif.txt => ti-emif.rst} | 27 +-
Documentation/mmc/index.rst | 13 +
.../{mmc-async-req.txt => mmc-async-req.rst} | 53 +-
.../{mmc-dev-attrs.txt => mmc-dev-attrs.rst} | 32 +-
.../{mmc-dev-parts.txt => mmc-dev-parts.rst} | 13 +-
.../mmc/{mmc-tools.txt => mmc-tools.rst} | 5 +-
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 +-
...bility-list.txt => compatibility-list.rst} | 10 +-
Documentation/namespaces/index.rst | 11 +
...ource-control.txt => resource-control.rst} | 4 +
Documentation/networking/ip-sysctl.txt | 2 +-
Documentation/nfc/index.rst | 11 +
.../nfc/{nfc-hci.txt => nfc-hci.rst} | 163 ++-
.../nfc/{nfc-pn544.txt => nfc-pn544.rst} | 6 +-
Documentation/nvdimm/{btt.txt => btt.rst} | 140 +-
Documentation/nvdimm/index.rst | 12 +
.../nvdimm/{nvdimm.txt => nvdimm.rst} | 518 ++++---
.../nvdimm/{security.txt => security.rst} | 4 +-
Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 +-
.../perf/{arm-ccn.txt => arm-ccn.rst} | 18 +-
.../perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} | 5 +-
.../perf/{hisi-pmu.txt => hisi-pmu.rst} | 35 +-
Documentation/perf/index.rst | 16 +
.../perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} | 3 +-
.../perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} | 3 +-
.../{thunderx2-pmu.txt => thunderx2-pmu.rst} | 25 +-
.../perf/{xgene-pmu.txt => xgene-pmu.rst} | 3 +-
.../{samsung-usb2.txt => samsung-usb2.rst} | 62 +-
Documentation/pi-futex.txt | 2 +-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
Documentation/powerpc/ptrace.rst | 156 +++
Documentation/powerpc/ptrace.txt | 151 --
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/process/submit-checklist.rst | 2 +-
Documentation/pti/pti_intel_mid.rst | 106 ++
Documentation/pti/pti_intel_mid.txt | 99 --
Documentation/rapidio/index.rst | 15 +
.../{mport_cdev.txt => mport_cdev.rst} | 47 +-
.../rapidio/{rapidio.txt => rapidio.rst} | 39 +-
.../rapidio/{rio_cm.txt => rio_cm.rst} | 66 +-
.../rapidio/{sysfs.txt => sysfs.rst} | 4 +
.../rapidio/{tsi721.txt => tsi721.rst} | 45 +-
Documentation/rbtree.txt | 6 +-
.../{xen-tpmfront.txt => xen-tpmfront.rst} | 103 +-
Documentation/sysctl/abi.rst | 67 +
Documentation/sysctl/abi.txt | 54 -
Documentation/sysctl/{fs.txt => fs.rst} | 142 +-
Documentation/sysctl/{README => index.rst} | 36 +-
.../sysctl/{kernel.txt => kernel.rst} | 372 ++---
Documentation/sysctl/{net.txt => net.rst} | 141 +-
.../sysctl/{sunrpc.txt => sunrpc.rst} | 13 +-
Documentation/sysctl/{user.txt => user.rst} | 32 +-
Documentation/sysctl/{vm.txt => vm.rst} | 262 ++--
...pu-cooling-api.txt => cpu-cooling-api.rst} | 39 +-
.../{exynos_thermal => exynos_thermal.rst} | 47 +-
.../thermal/exynos_thermal_emulation | 53 -
.../thermal/exynos_thermal_emulation.rst | 61 +
Documentation/thermal/index.rst | 18 +
...el_powerclamp.txt => intel_powerclamp.rst} | 177 +--
.../{nouveau_thermal => nouveau_thermal.rst} | 54 +-
...ower_allocator.txt => power_allocator.rst} | 140 +-
.../thermal/{sysfs-api.txt => sysfs-api.rst} | 490 ++++---
...hermal => x86_pkg_temperature_thermal.rst} | 28 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
Documentation/translations/zh_CN/arm/Booting | 4 +-
.../zh_CN/arm/kernel_user_helpers.txt | 4 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
Documentation/vm/unevictable-lru.rst | 2 +-
.../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 ---
MAINTAINERS | 48 +-
arch/arm/Kconfig | 2 +-
arch/arm/common/mcpm_entry.c | 2 +-
arch/arm/common/mcpm_head.S | 2 +-
arch/arm/common/vlock.S | 2 +-
arch/arm/include/asm/setup.h | 2 +-
arch/arm/include/uapi/asm/setup.h | 2 +-
arch/arm/kernel/entry-armv.S | 2 +-
arch/arm/mach-exynos/common.h | 2 +-
arch/arm/mach-ixp4xx/Kconfig | 14 +-
arch/arm/mach-s3c24xx/pm.c | 2 +-
arch/arm/mm/Kconfig | 4 +-
arch/arm/plat-samsung/Kconfig | 6 +-
arch/arm/tools/mach-types | 2 +-
arch/arm64/Kconfig | 2 +-
arch/arm64/kernel/kuser32.S | 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 +-
arch/mips/bmips/setup.c | 2 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
arch/xtensa/include/asm/initialize_mmu.h | 2 +-
block/Kconfig | 2 +-
block/Kconfig.iosched | 2 +-
block/bfq-iosched.c | 2 +-
block/blk-integrity.c | 2 +-
block/ioprio.c | 2 +-
block/mq-deadline.c | 2 +-
block/partitions/cmdline.c | 2 +-
drivers/block/Kconfig | 8 +-
drivers/block/floppy.c | 2 +-
drivers/block/zram/Kconfig | 6 +-
drivers/char/Kconfig | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-cipher.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-core.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-hash.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss.h | 2 +-
drivers/gpu/drm/drm_ioctl.c | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
drivers/iio/Kconfig | 2 +-
drivers/infiniband/core/user_mad.c | 2 +-
drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
drivers/input/touchscreen/sun4i-ts.c | 2 +-
drivers/leds/trigger/Kconfig | 2 +-
drivers/leds/trigger/ledtrig-transient.c | 2 +-
drivers/mtd/nand/raw/nand_ecc.c | 2 +-
drivers/nvdimm/Kconfig | 2 +-
drivers/perf/qcom_l3_pmu.c | 2 +-
drivers/platform/x86/Kconfig | 4 +-
drivers/rapidio/Kconfig | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
drivers/tty/serial/Kconfig | 2 +-
drivers/w1/Kconfig | 2 +-
include/linux/connector.h | 63 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/rwsem.h | 2 +-
include/linux/thermal.h | 4 +-
include/soc/fsl/qe/qe.h | 2 +-
include/uapi/rdma/rdma_user_ioctl_cmds.h | 2 +-
init/Kconfig | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
kernel/panic.c | 2 +-
lib/Kconfig.debug | 4 +-
mm/swap.c | 2 +-
net/netfilter/Kconfig | 2 +-
samples/Kconfig | 2 +-
scripts/gcc-plugins/Kconfig | 2 +-
tools/testing/selftests/zram/README | 2 +-
usr/Kconfig | 2 +-
403 files changed, 13486 insertions(+), 9719 deletions(-)
rename Documentation/{logo.txt => COPYING-logo} (100%)
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%)
delete mode 100644 Documentation/arm/Marvell/README
delete mode 100644 Documentation/arm/Netwinder
delete mode 100644 Documentation/arm/SA1100/FreeBird
delete mode 100644 Documentation/arm/SA1100/empeg
delete mode 100644 Documentation/arm/SA1100/serial_UART
rename Documentation/arm/{README => arm.rst} (88%)
rename Documentation/arm/{Booting => booting.rst} (89%)
rename Documentation/arm/{cluster-pm-race-avoidance.txt => cluster-pm-race-avoidance.rst} (84%)
rename Documentation/arm/{firmware.txt => firmware.rst} (86%)
create mode 100644 Documentation/arm/index.rst
rename Documentation/arm/{Interrupts => interrupts.rst} (81%)
rename Documentation/arm/{IXP4xx => ixp4xx.rst} (84%)
rename Documentation/arm/{kernel_mode_neon.txt => kernel_mode_neon.rst} (99%)
rename Documentation/arm/{kernel_user_helpers.txt => kernel_user_helpers.rst} (78%)
rename Documentation/arm/keystone/{knav-qmss.txt => knav-qmss.rst} (92%)
rename Documentation/arm/keystone/{Overview.txt => overview.rst} (59%)
create mode 100644 Documentation/arm/marvel.rst
rename Documentation/arm/{mem_alignment => mem_alignment.rst} (89%)
rename Documentation/arm/{memory.txt => memory.rst} (90%)
rename Documentation/arm/{Microchip/README => microchip.rst} (92%)
create mode 100644 Documentation/arm/netwinder.rst
create mode 100644 Documentation/arm/nwfpe/index.rst
rename Documentation/arm/nwfpe/{README.FPE => netwinder-fpe.rst} (94%)
rename Documentation/arm/nwfpe/{NOTES => notes.rst} (99%)
rename Documentation/arm/nwfpe/{README => nwfpe.rst} (98%)
rename Documentation/arm/nwfpe/{TODO => todo.rst} (75%)
rename Documentation/arm/{OMAP/DSS => omap/dss.rst} (86%)
create mode 100644 Documentation/arm/omap/index.rst
rename Documentation/arm/{OMAP/README => omap/omap.rst} (62%)
rename Documentation/arm/{OMAP/omap_pm => omap/omap_pm.rst} (83%)
rename Documentation/arm/{Porting => porting.rst} (94%)
rename Documentation/arm/pxa/{mfp.txt => mfp.rst} (83%)
rename Documentation/arm/{SA1100/ADSBitsy => sa1100/adsbitsy.rst} (90%)
rename Documentation/arm/{SA1100/Assabet => sa1100/assabet.rst} (62%)
rename Documentation/arm/{SA1100/Brutus => sa1100/brutus.rst} (75%)
rename Documentation/arm/{SA1100/CERF => sa1100/cerf.rst} (91%)
create mode 100644 Documentation/arm/sa1100/freebird.rst
rename Documentation/arm/{SA1100/GraphicsClient => sa1100/graphicsclient.rst} (87%)
rename Documentation/arm/{SA1100/GraphicsMaster => sa1100/graphicsmaster.rst} (92%)
rename Documentation/arm/{SA1100/HUW_WEBPANEL => sa1100/huw_webpanel.rst} (78%)
create mode 100644 Documentation/arm/sa1100/index.rst
rename Documentation/arm/{SA1100/Itsy => sa1100/itsy.rst} (88%)
rename Documentation/arm/{SA1100/LART => sa1100/lart.rst} (90%)
rename Documentation/arm/{SA1100/nanoEngine => sa1100/nanoengine.rst} (74%)
rename Documentation/arm/{SA1100/Pangolin => sa1100/pangolin.rst} (81%)
rename Documentation/arm/{SA1100/PLEB => sa1100/pleb.rst} (95%)
create mode 100644 Documentation/arm/sa1100/serial_uart.rst
rename Documentation/arm/{SA1100/Tifon => sa1100/tifon.rst} (88%)
rename Documentation/arm/{SA1100/Yopy => sa1100/yopy.rst} (74%)
rename Documentation/arm/{Samsung-S3C24XX/CPUfreq.txt => samsung-s3c24xx/cpufreq.rst} (96%)
rename Documentation/arm/{Samsung-S3C24XX/EB2410ITX.txt => samsung-s3c24xx/eb2410itx.rst} (92%)
rename Documentation/arm/{Samsung-S3C24XX/GPIO.txt => samsung-s3c24xx/gpio.rst} (89%)
rename Documentation/arm/{Samsung-S3C24XX/H1940.txt => samsung-s3c24xx/h1940.rst} (94%)
create mode 100644 Documentation/arm/samsung-s3c24xx/index.rst
rename Documentation/arm/{Samsung-S3C24XX/NAND.txt => samsung-s3c24xx/nand.rst} (92%)
rename Documentation/arm/{Samsung-S3C24XX/Overview.txt => samsung-s3c24xx/overview.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/S3C2412.txt => samsung-s3c24xx/s3c2412.rst} (96%)
rename Documentation/arm/{Samsung-S3C24XX/S3C2413.txt => samsung-s3c24xx/s3c2413.rst} (77%)
rename Documentation/arm/{Samsung-S3C24XX/SMDK2440.txt => samsung-s3c24xx/smdk2440.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/Suspend.txt => samsung-s3c24xx/suspend.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/USB-Host.txt => samsung-s3c24xx/usb-host.rst} (94%)
rename Documentation/arm/{Samsung/Bootloader-interface.txt => samsung/bootloader-interface.rst} (72%)
rename Documentation/arm/{Samsung => samsung}/clksrc-change-registers.awk (100%)
rename Documentation/arm/{Samsung/GPIO.txt => samsung/gpio.rst} (87%)
create mode 100644 Documentation/arm/samsung/index.rst
rename Documentation/arm/{Samsung/Overview.txt => samsung/overview.rst} (86%)
rename Documentation/arm/{Setup => setup.rst} (87%)
rename Documentation/arm/{SH-Mobile => sh-mobile}/.gitignore (100%)
rename Documentation/arm/{SPEAr/overview.txt => spear/overview.rst} (91%)
rename Documentation/arm/sti/{overview.txt => overview.rst} (82%)
rename Documentation/arm/sti/{stih407-overview.txt => stih407-overview.rst} (82%)
rename Documentation/arm/sti/{stih415-overview.txt => stih415-overview.rst} (79%)
rename Documentation/arm/sti/{stih416-overview.txt => stih416-overview.rst} (83%)
rename Documentation/arm/sti/{stih418-overview.txt => stih418-overview.rst} (83%)
rename Documentation/arm/{sunxi/README => sunxi.rst} (83%)
rename Documentation/arm/sunxi/{clocks.txt => clocks.rst} (92%)
rename Documentation/arm/{swp_emulation => swp_emulation.rst} (63%)
rename Documentation/arm/{tcm.txt => tcm.rst} (86%)
rename Documentation/arm/{uefi.txt => uefi.rst} (63%)
rename Documentation/arm/{VFP/release-notes.txt => vfp/release-notes.rst} (92%)
rename Documentation/arm/{vlocks.txt => vlocks.rst} (98%)
rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%)
create mode 100644 Documentation/backlight/lp855x-driver.rst
delete mode 100644 Documentation/backlight/lp855x-driver.txt
rename Documentation/block/{bfq-iosched.txt => bfq-iosched.rst} (95%)
rename Documentation/block/{biodoc.txt => biodoc.rst} (85%)
rename Documentation/block/{biovecs.txt => biovecs.rst} (92%)
create mode 100644 Documentation/block/capability.rst
delete mode 100644 Documentation/block/capability.txt
rename Documentation/block/{cmdline-partition.txt => cmdline-partition.rst} (92%)
rename Documentation/block/{data-integrity.txt => data-integrity.rst} (91%)
rename Documentation/block/{deadline-iosched.txt => deadline-iosched.rst} (89%)
create mode 100644 Documentation/block/index.rst
rename Documentation/block/{ioprio.txt => ioprio.rst} (75%)
rename Documentation/block/{kyber-iosched.txt => kyber-iosched.rst} (86%)
rename Documentation/block/{null_blk.txt => null_blk.rst} (60%)
rename Documentation/block/{pr.txt => pr.rst} (93%)
rename Documentation/block/{queue-sysfs.txt => queue-sysfs.rst} (99%)
rename Documentation/block/{request.txt => request.rst} (59%)
rename Documentation/block/{stat.txt => stat.rst} (89%)
rename Documentation/block/{switching-sched.txt => switching-sched.rst} (67%)
rename Documentation/block/{writeback_cache_control.txt => writeback_cache_control.rst} (94%)
rename Documentation/blockdev/drbd/{data-structure-v9.txt => data-structure-v9.rst} (94%)
create mode 100644 Documentation/blockdev/drbd/figures.rst
rename Documentation/blockdev/drbd/{README.txt => index.rst} (55%)
rename Documentation/blockdev/{floppy.txt => floppy.rst} (81%)
create mode 100644 Documentation/blockdev/index.rst
rename Documentation/blockdev/{nbd.txt => nbd.rst} (96%)
rename Documentation/blockdev/{paride.txt => paride.rst} (81%)
rename Documentation/blockdev/{ramdisk.txt => ramdisk.rst} (84%)
rename Documentation/blockdev/{zram.txt => zram.rst} (76%)
rename Documentation/bus-devices/{ti-gpmc.txt => ti-gpmc.rst} (58%)
rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%)
rename Documentation/connector/{connector.txt => connector.rst} (57%)
rename Documentation/console/{console.txt => console.rst} (80%)
rename Documentation/{gcc-plugins.txt => core-api/gcc-plugins.rst} (100%)
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
rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
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%)
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
rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
create mode 100644 Documentation/iio/index.rst
rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
create mode 100644 Documentation/infiniband/index.rst
rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
rename Documentation/ioctl/{botching-up-ioctls.txt => botching-up-ioctls.rst} (99%)
create mode 100644 Documentation/ioctl/cdrom.rst
delete mode 100644 Documentation/ioctl/cdrom.txt
rename Documentation/ioctl/{hdio.txt => hdio.rst} (54%)
create mode 100644 Documentation/ioctl/index.rst
rename Documentation/ioctl/{ioctl-decoding.txt => ioctl-decoding.rst} (54%)
create mode 100644 Documentation/ioctl/ioctl-number.rst
delete mode 100644 Documentation/ioctl/ioctl-number.txt
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%)
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%)
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/m68k/index.rst
rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%)
create mode 100644 Documentation/md/index.rst
rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)
rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%)
create mode 100644 Documentation/mmc/index.rst
rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%)
rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%)
rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%)
rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%)
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%)
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%)
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%)
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%)
rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)
rename Documentation/perf/{arm-ccn.txt => arm-ccn.rst} (86%)
rename Documentation/perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} (92%)
rename Documentation/perf/{hisi-pmu.txt => hisi-pmu.rst} (73%)
create mode 100644 Documentation/perf/index.rst
rename Documentation/perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} (94%)
rename Documentation/perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} (93%)
rename Documentation/perf/{thunderx2-pmu.txt => thunderx2-pmu.rst} (73%)
rename Documentation/perf/{xgene-pmu.txt => xgene-pmu.rst} (96%)
rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%)
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/pti/pti_intel_mid.rst
delete mode 100644 Documentation/pti/pti_intel_mid.txt
create mode 100644 Documentation/rapidio/index.rst
rename Documentation/rapidio/{mport_cdev.txt => mport_cdev.rst} (84%)
rename Documentation/rapidio/{rapidio.txt => rapidio.rst} (97%)
rename Documentation/rapidio/{rio_cm.txt => rio_cm.rst} (76%)
rename Documentation/rapidio/{sysfs.txt => sysfs.rst} (75%)
rename Documentation/rapidio/{tsi721.txt => tsi721.rst} (79%)
rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)
create mode 100644 Documentation/sysctl/abi.rst
delete mode 100644 Documentation/sysctl/abi.txt
rename Documentation/sysctl/{fs.txt => fs.rst} (77%)
rename Documentation/sysctl/{README => index.rst} (78%)
rename Documentation/sysctl/{kernel.txt => kernel.rst} (79%)
rename Documentation/sysctl/{net.txt => net.rst} (85%)
rename Documentation/sysctl/{sunrpc.txt => sunrpc.rst} (62%)
rename Documentation/sysctl/{user.txt => user.rst} (77%)
rename Documentation/sysctl/{vm.txt => vm.rst} (85%)
rename Documentation/thermal/{cpu-cooling-api.txt => cpu-cooling-api.rst} (82%)
rename Documentation/thermal/{exynos_thermal => exynos_thermal.rst} (67%)
delete mode 100644 Documentation/thermal/exynos_thermal_emulation
create mode 100644 Documentation/thermal/exynos_thermal_emulation.rst
create mode 100644 Documentation/thermal/index.rst
rename Documentation/thermal/{intel_powerclamp.txt => intel_powerclamp.rst} (76%)
rename Documentation/thermal/{nouveau_thermal => nouveau_thermal.rst} (64%)
rename Documentation/thermal/{power_allocator.txt => power_allocator.rst} (74%)
rename Documentation/thermal/{sysfs-api.txt => sysfs-api.rst} (66%)
rename Documentation/thermal/{x86_pkg_temperature_thermal => x86_pkg_temperature_thermal.rst} (80%)
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
--
2.21.0
^ permalink raw reply [flat|nested] 54+ messages in thread
* [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
@ 2019-06-28 12:19 ` Mauro Carvalho Chehab
2019-07-03 18:06 ` Jason Gunthorpe
2019-06-28 12:19 ` [PATCH 02/43] docs: iio: convert to ReST Mauro Carvalho Chehab
` (41 subsequent siblings)
42 siblings, 1 reply; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:19 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Doug Ledford, Jason Gunthorpe, linux-rdma
The InfiniBand docs are plain text with no markups.
So, all we needed to do were to add the title markups and
some markup sequences in order to properly parse tables,
lists and literal blocks.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{core_locking.txt => core_locking.rst} | 64 ++++++-----
Documentation/infiniband/index.rst | 23 ++++
.../infiniband/{ipoib.txt => ipoib.rst} | 24 ++--
.../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +++++++++---------
.../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
.../{tag_matching.txt => tag_matching.rst} | 5 +
.../infiniband/{user_mad.txt => user_mad.rst} | 33 ++++--
.../{user_verbs.txt => user_verbs.rst} | 12 +-
drivers/infiniband/core/user_mad.c | 2 +-
drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
10 files changed, 174 insertions(+), 103 deletions(-)
rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
create mode 100644 Documentation/infiniband/index.rst
rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
diff --git a/Documentation/infiniband/core_locking.txt b/Documentation/infiniband/core_locking.rst
similarity index 78%
rename from Documentation/infiniband/core_locking.txt
rename to Documentation/infiniband/core_locking.rst
index 4b1f36b6ada0..f34669beb4fe 100644
--- a/Documentation/infiniband/core_locking.txt
+++ b/Documentation/infiniband/core_locking.rst
@@ -1,4 +1,6 @@
-INFINIBAND MIDLAYER LOCKING
+===========================
+InfiniBand Midlayer Locking
+===========================
This guide is an attempt to make explicit the locking assumptions
made by the InfiniBand midlayer. It describes the requirements on
@@ -6,45 +8,47 @@ INFINIBAND MIDLAYER LOCKING
protocols that use the midlayer.
Sleeping and interrupt context
+==============================
With the following exceptions, a low-level driver implementation of
all of the methods in struct ib_device may sleep. The exceptions
are any methods from the list:
- create_ah
- modify_ah
- query_ah
- destroy_ah
- post_send
- post_recv
- poll_cq
- req_notify_cq
- map_phys_fmr
+ - create_ah
+ - modify_ah
+ - query_ah
+ - destroy_ah
+ - post_send
+ - post_recv
+ - poll_cq
+ - req_notify_cq
+ - map_phys_fmr
which may not sleep and must be callable from any context.
The corresponding functions exported to upper level protocol
consumers:
- ib_create_ah
- ib_modify_ah
- ib_query_ah
- ib_destroy_ah
- ib_post_send
- ib_post_recv
- ib_req_notify_cq
- ib_map_phys_fmr
+ - ib_create_ah
+ - ib_modify_ah
+ - ib_query_ah
+ - ib_destroy_ah
+ - ib_post_send
+ - ib_post_recv
+ - ib_req_notify_cq
+ - ib_map_phys_fmr
are therefore safe to call from any context.
In addition, the function
- ib_dispatch_event
+ - ib_dispatch_event
used by low-level drivers to dispatch asynchronous events through
the midlayer is also safe to call from any context.
Reentrancy
+----------
All of the methods in struct ib_device exported by a low-level
driver must be fully reentrant. The low-level driver is required to
@@ -62,6 +66,7 @@ Reentrancy
information between different calls of ib_poll_cq() is not defined.
Callbacks
+---------
A low-level driver must not perform a callback directly from the
same callchain as an ib_device method call. For example, it is not
@@ -74,18 +79,18 @@ Callbacks
completion event handlers for the same CQ are not called
simultaneously. The driver must guarantee that only one CQ event
handler for a given CQ is running at a time. In other words, the
- following situation is not allowed:
+ following situation is not allowed::
- CPU1 CPU2
+ CPU1 CPU2
- low-level driver ->
- consumer CQ event callback:
- /* ... */
- ib_req_notify_cq(cq, ...);
- low-level driver ->
- /* ... */ consumer CQ event callback:
- /* ... */
- return from CQ event handler
+ low-level driver ->
+ consumer CQ event callback:
+ /* ... */
+ ib_req_notify_cq(cq, ...);
+ low-level driver ->
+ /* ... */ consumer CQ event callback:
+ /* ... */
+ return from CQ event handler
The context in which completion event and asynchronous event
callbacks run is not defined. Depending on the low-level driver, it
@@ -93,6 +98,7 @@ Callbacks
Upper level protocol consumers may not sleep in a callback.
Hot-plug
+--------
A low-level driver announces that a device is ready for use by
consumers when it calls ib_register_device(), all initialization
diff --git a/Documentation/infiniband/index.rst b/Documentation/infiniband/index.rst
new file mode 100644
index 000000000000..22eea64de722
--- /dev/null
+++ b/Documentation/infiniband/index.rst
@@ -0,0 +1,23 @@
+:orphan:
+
+==========
+InfiniBand
+==========
+
+.. toctree::
+ :maxdepth: 1
+
+ core_locking
+ ipoib
+ opa_vnic
+ sysfs
+ tag_matching
+ user_mad
+ user_verbs
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/infiniband/ipoib.txt b/Documentation/infiniband/ipoib.rst
similarity index 90%
rename from Documentation/infiniband/ipoib.txt
rename to Documentation/infiniband/ipoib.rst
index 47c1dd9818f2..0dd36154c0c9 100644
--- a/Documentation/infiniband/ipoib.txt
+++ b/Documentation/infiniband/ipoib.rst
@@ -1,4 +1,6 @@
-IP OVER INFINIBAND
+==================
+IP over InfiniBand
+==================
The ib_ipoib driver is an implementation of the IP over InfiniBand
protocol as specified by RFC 4391 and 4392, issued by the IETF ipoib
@@ -8,16 +10,17 @@ IP OVER INFINIBAND
masqueraded to the kernel as ethernet interfaces).
Partitions and P_Keys
+=====================
When the IPoIB driver is loaded, it creates one interface for each
port using the P_Key at index 0. To create an interface with a
different P_Key, write the desired P_Key into the main interface's
- /sys/class/net/<intf name>/create_child file. For example:
+ /sys/class/net/<intf name>/create_child file. For example::
echo 0x8001 > /sys/class/net/ib0/create_child
This will create an interface named ib0.8001 with P_Key 0x8001. To
- remove a subinterface, use the "delete_child" file:
+ remove a subinterface, use the "delete_child" file::
echo 0x8001 > /sys/class/net/ib0/delete_child
@@ -28,6 +31,7 @@ Partitions and P_Keys
rtnl_link_ops, where children created using either way behave the same.
Datagram vs Connected modes
+===========================
The IPoIB driver supports two modes of operation: datagram and
connected. The mode is set and read through an interface's
@@ -51,6 +55,7 @@ Datagram vs Connected modes
networking stack to use the smaller UD MTU for these neighbours.
Stateless offloads
+==================
If the IB HW supports IPoIB stateless offloads, IPoIB advertises
TCP/IP checksum and/or Large Send (LSO) offloading capability to the
@@ -60,9 +65,10 @@ Stateless offloads
on/off using ethtool calls. Currently LRO is supported only for
checksum offload capable devices.
- Stateless offloads are supported only in datagram mode.
+ Stateless offloads are supported only in datagram mode.
Interrupt moderation
+====================
If the underlying IB device supports CQ event moderation, one can
use ethtool to set interrupt mitigation parameters and thus reduce
@@ -71,6 +77,7 @@ Interrupt moderation
moderation is supported.
Debugging Information
+=====================
By compiling the IPoIB driver with CONFIG_INFINIBAND_IPOIB_DEBUG set
to 'y', tracing messages are compiled into the driver. They are
@@ -79,7 +86,7 @@ Debugging Information
runtime through files in /sys/module/ib_ipoib/.
CONFIG_INFINIBAND_IPOIB_DEBUG also enables files in the debugfs
- virtual filesystem. By mounting this filesystem, for example with
+ virtual filesystem. By mounting this filesystem, for example with::
mount -t debugfs none /sys/kernel/debug
@@ -96,10 +103,13 @@ Debugging Information
performance, because it adds tests to the fast path.
References
+==========
Transmission of IP over InfiniBand (IPoIB) (RFC 4391)
- http://ietf.org/rfc/rfc4391.txt
+ http://ietf.org/rfc/rfc4391.txt
+
IP over InfiniBand (IPoIB) Architecture (RFC 4392)
- http://ietf.org/rfc/rfc4392.txt
+ http://ietf.org/rfc/rfc4392.txt
+
IP over InfiniBand: Connected Mode (RFC 4755)
http://ietf.org/rfc/rfc4755.txt
diff --git a/Documentation/infiniband/opa_vnic.txt b/Documentation/infiniband/opa_vnic.rst
similarity index 63%
rename from Documentation/infiniband/opa_vnic.txt
rename to Documentation/infiniband/opa_vnic.rst
index 282e17be798a..2f888d9ffec0 100644
--- a/Documentation/infiniband/opa_vnic.txt
+++ b/Documentation/infiniband/opa_vnic.rst
@@ -1,3 +1,7 @@
+=================================================================
+Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC)
+=================================================================
+
Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC) feature
supports Ethernet functionality over Omni-Path fabric by encapsulating
the Ethernet packets between HFI nodes.
@@ -17,70 +21,72 @@ an independent Ethernet network. The configuration is performed by an
Ethernet Manager (EM) which is part of the trusted Fabric Manager (FM)
application. HFI nodes can have multiple VNICs each connected to a
different virtual Ethernet switch. The below diagram presents a case
-of two virtual Ethernet switches with two HFI nodes.
+of two virtual Ethernet switches with two HFI nodes::
- +-------------------+
- | Subnet/ |
- | Ethernet |
- | Manager |
- +-------------------+
- / /
- / /
- / /
- / /
-+-----------------------------+ +------------------------------+
-| Virtual Ethernet Switch | | Virtual Ethernet Switch |
-| +---------+ +---------+ | | +---------+ +---------+ |
-| | VPORT | | VPORT | | | | VPORT | | VPORT | |
-+--+---------+----+---------+-+ +-+---------+----+---------+---+
- | \ / |
- | \ / |
- | \/ |
- | / \ |
- | / \ |
- +-----------+------------+ +-----------+------------+
- | VNIC | VNIC | | VNIC | VNIC |
- +-----------+------------+ +-----------+------------+
- | HFI | | HFI |
- +------------------------+ +------------------------+
+ +-------------------+
+ | Subnet/ |
+ | Ethernet |
+ | Manager |
+ +-------------------+
+ / /
+ / /
+ / /
+ / /
+ +-----------------------------+ +------------------------------+
+ | Virtual Ethernet Switch | | Virtual Ethernet Switch |
+ | +---------+ +---------+ | | +---------+ +---------+ |
+ | | VPORT | | VPORT | | | | VPORT | | VPORT | |
+ +--+---------+----+---------+-+ +-+---------+----+---------+---+
+ | \ / |
+ | \ / |
+ | \/ |
+ | / \ |
+ | / \ |
+ +-----------+------------+ +-----------+------------+
+ | VNIC | VNIC | | VNIC | VNIC |
+ +-----------+------------+ +-----------+------------+
+ | HFI | | HFI |
+ +------------------------+ +------------------------+
The Omni-Path encapsulated Ethernet packet format is as described below.
-Bits Field
-------------------------------------
+==================== ================================
+Bits Field
+==================== ================================
Quad Word 0:
-0-19 SLID (lower 20 bits)
-20-30 Length (in Quad Words)
-31 BECN bit
-32-51 DLID (lower 20 bits)
-52-56 SC (Service Class)
-57-59 RC (Routing Control)
-60 FECN bit
-61-62 L2 (=10, 16B format)
-63 LT (=1, Link Transfer Head Flit)
+0-19 SLID (lower 20 bits)
+20-30 Length (in Quad Words)
+31 BECN bit
+32-51 DLID (lower 20 bits)
+52-56 SC (Service Class)
+57-59 RC (Routing Control)
+60 FECN bit
+61-62 L2 (=10, 16B format)
+63 LT (=1, Link Transfer Head Flit)
Quad Word 1:
-0-7 L4 type (=0x78 ETHERNET)
-8-11 SLID[23:20]
-12-15 DLID[23:20]
-16-31 PKEY
-32-47 Entropy
-48-63 Reserved
+0-7 L4 type (=0x78 ETHERNET)
+8-11 SLID[23:20]
+12-15 DLID[23:20]
+16-31 PKEY
+32-47 Entropy
+48-63 Reserved
Quad Word 2:
-0-15 Reserved
-16-31 L4 header
-32-63 Ethernet Packet
+0-15 Reserved
+16-31 L4 header
+32-63 Ethernet Packet
Quad Words 3 to N-1:
-0-63 Ethernet packet (pad extended)
+0-63 Ethernet packet (pad extended)
Quad Word N (last):
-0-23 Ethernet packet (pad extended)
-24-55 ICRC
-56-61 Tail
-62-63 LT (=01, Link Transfer Tail Flit)
+0-23 Ethernet packet (pad extended)
+24-55 ICRC
+56-61 Tail
+62-63 LT (=01, Link Transfer Tail Flit)
+==================== ================================
Ethernet packet is padded on the transmit side to ensure that the VNIC OPA
packet is quad word aligned. The 'Tail' field contains the number of bytes
@@ -123,7 +129,7 @@ operation. It also handles the encapsulation of Ethernet packets with an
Omni-Path header in the transmit path. For each VNIC interface, the
information required for encapsulation is configured by the EM via VEMA MAD
interface. It also passes any control information to the HW dependent driver
-by invoking the RDMA netdev control operations.
+by invoking the RDMA netdev control operations::
+-------------------+ +----------------------+
| | | Linux |
diff --git a/Documentation/infiniband/sysfs.txt b/Documentation/infiniband/sysfs.rst
similarity index 69%
rename from Documentation/infiniband/sysfs.txt
rename to Documentation/infiniband/sysfs.rst
index 9fab5062f84b..f0abd6fa48f4 100644
--- a/Documentation/infiniband/sysfs.txt
+++ b/Documentation/infiniband/sysfs.rst
@@ -1,4 +1,6 @@
-SYSFS FILES
+===========
+Sysfs files
+===========
The sysfs interface has moved to
Documentation/ABI/stable/sysfs-class-infiniband.
diff --git a/Documentation/infiniband/tag_matching.txt b/Documentation/infiniband/tag_matching.rst
similarity index 98%
rename from Documentation/infiniband/tag_matching.txt
rename to Documentation/infiniband/tag_matching.rst
index d2a3bf819226..ef56ea585f92 100644
--- a/Documentation/infiniband/tag_matching.txt
+++ b/Documentation/infiniband/tag_matching.rst
@@ -1,12 +1,16 @@
+==================
Tag matching logic
+==================
The MPI standard defines a set of rules, known as tag-matching, for matching
source send operations to destination receives. The following parameters must
match the following source and destination parameters:
+
* Communicator
* User tag - wild card may be specified by the receiver
* Source rank – wild car may be specified by the receiver
* Destination rank – wild
+
The ordering rules require that when more than one pair of send and receive
message envelopes may match, the pair that includes the earliest posted-send
and the earliest posted-receive is the pair that must be used to satisfy the
@@ -35,6 +39,7 @@ the header to initiate an RDMA READ operation directly to the matching buffer.
A fin message needs to be received in order for the buffer to be reused.
Tag matching implementation
+===========================
There are two types of matching objects used, the posted receive list and the
unexpected message list. The application posts receive buffers through calls
diff --git a/Documentation/infiniband/user_mad.txt b/Documentation/infiniband/user_mad.rst
similarity index 90%
rename from Documentation/infiniband/user_mad.txt
rename to Documentation/infiniband/user_mad.rst
index 7aca13a54a3a..d88abfc0e370 100644
--- a/Documentation/infiniband/user_mad.txt
+++ b/Documentation/infiniband/user_mad.rst
@@ -1,6 +1,9 @@
-USERSPACE MAD ACCESS
+====================
+Userspace MAD access
+====================
Device files
+============
Each port of each InfiniBand device has a "umad" device and an
"issm" device attached. For example, a two-port HCA will have two
@@ -8,12 +11,13 @@ Device files
device of each type (for switch port 0).
Creating MAD agents
+===================
A MAD agent can be created by filling in a struct ib_user_mad_reg_req
and then calling the IB_USER_MAD_REGISTER_AGENT ioctl on a file
descriptor for the appropriate device file. If the registration
request succeeds, a 32-bit id will be returned in the structure.
- For example:
+ For example::
struct ib_user_mad_reg_req req = { /* ... */ };
ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req);
@@ -26,12 +30,14 @@ Creating MAD agents
ioctl. Also, all agents registered through a file descriptor will
be unregistered when the descriptor is closed.
- 2014 -- a new registration ioctl is now provided which allows additional
+ 2014
+ a new registration ioctl is now provided which allows additional
fields to be provided during registration.
Users of this registration call are implicitly setting the use of
pkey_index (see below).
Receiving MADs
+==============
MADs are received using read(). The receive side now supports
RMPP. The buffer passed to read() must be at least one
@@ -41,7 +47,8 @@ Receiving MADs
MAD (RMPP), the errno is set to ENOSPC and the length of the
buffer needed is set in mad.length.
- Example for normal MAD (non RMPP) reads:
+ Example for normal MAD (non RMPP) reads::
+
struct ib_user_mad *mad;
mad = malloc(sizeof *mad + 256);
ret = read(fd, mad, sizeof *mad + 256);
@@ -50,7 +57,8 @@ Receiving MADs
free(mad);
}
- Example for RMPP reads:
+ Example for RMPP reads::
+
struct ib_user_mad *mad;
mad = malloc(sizeof *mad + 256);
ret = read(fd, mad, sizeof *mad + 256);
@@ -76,11 +84,12 @@ Receiving MADs
poll()/select() may be used to wait until a MAD can be read.
Sending MADs
+============
MADs are sent using write(). The agent ID for sending should be
filled into the id field of the MAD, the destination LID should be
filled into the lid field, and so on. The send side does support
- RMPP so arbitrary length MAD can be sent. For example:
+ RMPP so arbitrary length MAD can be sent. For example::
struct ib_user_mad *mad;
@@ -97,6 +106,7 @@ Sending MADs
perror("write");
Transaction IDs
+===============
Users of the umad devices can use the lower 32 bits of the
transaction ID field (that is, the least significant half of the
@@ -105,6 +115,7 @@ Transaction IDs
the kernel and will be overwritten before a MAD is sent.
P_Key Index Handling
+====================
The old ib_umad interface did not allow setting the P_Key index for
MADs that are sent and did not provide a way for obtaining the P_Key
@@ -119,6 +130,7 @@ P_Key Index Handling
default, and the IB_USER_MAD_ENABLE_PKEY ioctl will be removed.
Setting IsSM Capability Bit
+===========================
To set the IsSM capability bit for a port, simply open the
corresponding issm device file. If the IsSM bit is already set,
@@ -129,25 +141,26 @@ Setting IsSM Capability Bit
the issm file.
/dev files
+==========
To create the appropriate character device files automatically with
- udev, a rule like
+ udev, a rule like::
KERNEL=="umad*", NAME="infiniband/%k"
KERNEL=="issm*", NAME="infiniband/%k"
- can be used. This will create device nodes named
+ can be used. This will create device nodes named::
/dev/infiniband/umad0
/dev/infiniband/issm0
for the first port, and so on. The InfiniBand device and port
- associated with these devices can be determined from the files
+ associated with these devices can be determined from the files::
/sys/class/infiniband_mad/umad0/ibdev
/sys/class/infiniband_mad/umad0/port
- and
+ and::
/sys/class/infiniband_mad/issm0/ibdev
/sys/class/infiniband_mad/issm0/port
diff --git a/Documentation/infiniband/user_verbs.txt b/Documentation/infiniband/user_verbs.rst
similarity index 93%
rename from Documentation/infiniband/user_verbs.txt
rename to Documentation/infiniband/user_verbs.rst
index 47ebf2f80b2b..8ddc4b1cfef2 100644
--- a/Documentation/infiniband/user_verbs.txt
+++ b/Documentation/infiniband/user_verbs.rst
@@ -1,4 +1,6 @@
-USERSPACE VERBS ACCESS
+======================
+Userspace verbs access
+======================
The ib_uverbs module, built by enabling CONFIG_INFINIBAND_USER_VERBS,
enables direct userspace access to IB hardware via "verbs," as
@@ -13,6 +15,7 @@ USERSPACE VERBS ACCESS
libmthca userspace driver be installed.
User-kernel communication
+=========================
Userspace communicates with the kernel for slow path, resource
management operations via the /dev/infiniband/uverbsN character
@@ -28,6 +31,7 @@ User-kernel communication
system call.
Resource management
+===================
Since creation and destruction of all IB resources is done by
commands passed through a file descriptor, the kernel can keep track
@@ -41,6 +45,7 @@ Resource management
prevent one process from touching another process's resources.
Memory pinning
+==============
Direct userspace I/O requires that memory regions that are potential
I/O targets be kept resident at the same physical address. The
@@ -54,13 +59,14 @@ Memory pinning
number of pages pinned by a process.
/dev files
+==========
To create the appropriate character device files automatically with
- udev, a rule like
+ udev, a rule like::
KERNEL=="uverbs*", NAME="infiniband/%k"
- can be used. This will create device nodes named
+ can be used. This will create device nodes named::
/dev/infiniband/uverbs0
diff --git a/drivers/infiniband/core/user_mad.c b/drivers/infiniband/core/user_mad.c
index 547090b41cfb..9f8a48016b41 100644
--- a/drivers/infiniband/core/user_mad.c
+++ b/drivers/infiniband/core/user_mad.c
@@ -745,7 +745,7 @@ static int ib_umad_reg_agent(struct ib_umad_file *file, void __user *arg,
"process %s did not enable P_Key index support.\n",
current->comm);
dev_warn(&file->port->dev,
- " Documentation/infiniband/user_mad.txt has info on the new ABI.\n");
+ " Documentation/infiniband/user_mad.rst has info on the new ABI.\n");
}
}
diff --git a/drivers/infiniband/ulp/ipoib/Kconfig b/drivers/infiniband/ulp/ipoib/Kconfig
index 4760ce465d89..7af68604af77 100644
--- a/drivers/infiniband/ulp/ipoib/Kconfig
+++ b/drivers/infiniband/ulp/ipoib/Kconfig
@@ -7,7 +7,7 @@ config INFINIBAND_IPOIB
transports IP packets over InfiniBand so you can use your IB
device as a fancy NIC.
- See Documentation/infiniband/ipoib.txt for more information
+ See Documentation/infiniband/ipoib.rst for more information
config INFINIBAND_IPOIB_CM
bool "IP-over-InfiniBand Connected Mode support"
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 02/43] docs: iio: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-28 12:19 ` Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 03/43] docs: hid: " Mauro Carvalho Chehab
` (40 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:19 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-iio,
Jonathan Cameron
Rename the iio 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>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
.../iio/{ep93xx_adc.txt => ep93xx_adc.rst} | 15 +++++-
.../{iio_configfs.txt => iio_configfs.rst} | 52 +++++++++++--------
Documentation/iio/index.rst | 12 +++++
drivers/iio/Kconfig | 2 +-
4 files changed, 56 insertions(+), 25 deletions(-)
rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
create mode 100644 Documentation/iio/index.rst
diff --git a/Documentation/iio/ep93xx_adc.txt b/Documentation/iio/ep93xx_adc.rst
similarity index 71%
rename from Documentation/iio/ep93xx_adc.txt
rename to Documentation/iio/ep93xx_adc.rst
index 23053e7817bd..4fd8dea3f6b8 100644
--- a/Documentation/iio/ep93xx_adc.txt
+++ b/Documentation/iio/ep93xx_adc.rst
@@ -1,12 +1,16 @@
-Cirrus Logic EP93xx ADC driver.
+==============================
+Cirrus Logic EP93xx ADC driver
+==============================
1. Overview
+===========
The driver is intended to work on both low-end (EP9301, EP9302) devices with
5-channel ADC and high-end (EP9307, EP9312, EP9315) devices with 10-channel
touchscreen/ADC module.
2. Channel numbering
+====================
Numbering scheme for channels 0..4 is defined in EP9301 and EP9302 datasheets.
EP9307, EP9312 and EP9312 have 3 channels more (total 8), but the numbering is
@@ -17,13 +21,20 @@ Assuming ep93xx_adc is IIO device0, you'd find the following entries under
+-----------------+---------------+
| sysfs entry | ball/pin name |
- +-----------------+---------------+
+ +=================+===============+
| in_voltage0_raw | YM |
+ +-----------------+---------------+
| in_voltage1_raw | SXP |
+ +-----------------+---------------+
| in_voltage2_raw | SXM |
+ +-----------------+---------------+
| in_voltage3_raw | SYP |
+ +-----------------+---------------+
| in_voltage4_raw | SYM |
+ +-----------------+---------------+
| in_voltage5_raw | XP |
+ +-----------------+---------------+
| in_voltage6_raw | XM |
+ +-----------------+---------------+
| in_voltage7_raw | YP |
+-----------------+---------------+
diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.rst
similarity index 73%
rename from Documentation/iio/iio_configfs.txt
rename to Documentation/iio/iio_configfs.rst
index 4e5f101837a8..ecbfdb3afef7 100644
--- a/Documentation/iio/iio_configfs.txt
+++ b/Documentation/iio/iio_configfs.rst
@@ -1,6 +1,9 @@
+===============================
Industrial IIO configfs support
+===============================
1. Overview
+===========
Configfs is a filesystem-based manager of kernel objects. IIO uses some
objects that could be easily configured using configfs (e.g.: devices,
@@ -10,20 +13,22 @@ See Documentation/filesystems/configfs/configfs.txt for more information
about how configfs works.
2. Usage
+========
In order to use configfs support in IIO we need to select it at compile
time via CONFIG_IIO_CONFIGFS config option.
-Then, mount the configfs filesystem (usually under /config directory):
+Then, mount the configfs filesystem (usually under /config directory)::
-$ mkdir /config
-$ mount -t configfs none /config
+ $ mkdir /config
+ $ mount -t configfs none /config
At this point, all default IIO groups will be created and can be accessed
under /config/iio. Next chapters will describe available IIO configuration
objects.
3. Software triggers
+====================
One of the IIO default configfs groups is the "triggers" group. It is
automagically accessible when the configfs is mounted and can be found
@@ -31,40 +36,40 @@ under /config/iio/triggers.
IIO software triggers implementation offers support for creating multiple
trigger types. A new trigger type is usually implemented as a separate
-kernel module following the interface in include/linux/iio/sw_trigger.h:
+kernel module following the interface in include/linux/iio/sw_trigger.h::
-/*
- * drivers/iio/trigger/iio-trig-sample.c
- * sample kernel module implementing a new trigger type
- */
-#include <linux/iio/sw_trigger.h>
+ /*
+ * drivers/iio/trigger/iio-trig-sample.c
+ * sample kernel module implementing a new trigger type
+ */
+ #include <linux/iio/sw_trigger.h>
-static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
-{
+ static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
+ {
/*
* This allocates and registers an IIO trigger plus other
* trigger type specific initialization.
*/
-}
+ }
-static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
-{
+ static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
+ {
/*
* This undoes the actions in iio_trig_sample_probe
*/
-}
+ }
-static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
+ static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
.probe = iio_trig_sample_probe,
.remove = iio_trig_sample_remove,
-};
+ };
-static struct iio_sw_trigger_type iio_trig_sample = {
+ static struct iio_sw_trigger_type iio_trig_sample = {
.name = "trig-sample",
.owner = THIS_MODULE,
.ops = &iio_trig_sample_ops,
-};
+ };
module_iio_sw_trigger_driver(iio_trig_sample);
@@ -73,21 +78,24 @@ iio-trig-sample module will create 'trig-sample' trigger type directory
/config/iio/triggers/trig-sample.
We support the following interrupt sources (trigger types):
+
* hrtimer, uses high resolution timers as interrupt source
3.1 Hrtimer triggers creation and destruction
+---------------------------------------------
Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
users to create hrtimer triggers under /config/iio/triggers/hrtimer.
-e.g:
+e.g::
-$ mkdir /config/iio/triggers/hrtimer/instance1
-$ rmdir /config/iio/triggers/hrtimer/instance1
+ $ mkdir /config/iio/triggers/hrtimer/instance1
+ $ rmdir /config/iio/triggers/hrtimer/instance1
Each trigger can have one or more attributes specific to the trigger type.
3.2 "hrtimer" trigger types attributes
+--------------------------------------
"hrtimer" trigger type doesn't have any configurable attribute from /config dir.
It does introduce the sampling_frequency attribute to trigger directory.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
new file mode 100644
index 000000000000..0593dca89a94
--- /dev/null
+++ b/Documentation/iio/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+==============
+Industrial I/O
+==============
+
+.. toctree::
+ :maxdepth: 1
+
+ iio_configfs
+
+ ep93xx_adc
diff --git a/drivers/iio/Kconfig b/drivers/iio/Kconfig
index 1d736a4952ab..5bd51853b15e 100644
--- a/drivers/iio/Kconfig
+++ b/drivers/iio/Kconfig
@@ -28,7 +28,7 @@ config IIO_CONFIGFS
help
This allows configuring various IIO bits through configfs
(e.g. software triggers). For more info see
- Documentation/iio/iio_configfs.txt.
+ Documentation/iio/iio_configfs.rst.
config IIO_TRIGGER
bool "Enable triggered sampling support"
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 03/43] docs: hid: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 02/43] docs: iio: convert to ReST Mauro Carvalho Chehab
@ 2019-06-28 12:19 ` Mauro Carvalho Chehab
2019-07-02 9:58 ` Benjamin Tissoires
2019-06-28 12:20 ` [PATCH 04/43] docs: locking: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (39 subsequent siblings)
42 siblings, 1 reply; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:19 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
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>
Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
---
.../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 4f41d67f1b4b..0fe526f36db6 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 3e3b9738f2e6..9458cdaa5b4b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16461,7 +16461,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 [flat|nested] 54+ messages in thread
* [PATCH 04/43] docs: locking: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (2 preceding siblings ...)
2019-06-28 12:19 ` [PATCH 03/43] docs: hid: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 05/43] docs: powerpc: " Mauro Carvalho Chehab
` (38 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Zijlstra, Ingo Molnar, Will Deacon,
Thomas Gleixner, Darren Hart, Federico Vaga, Maarten Lankhorst,
Maxime Ripard, Sean Paul, David Airlie, Daniel Vetter, dri-devel
Convert the locking documents to ReST and add them to the
kernel development book where it belongs.
Most of the stuff here is just to make Sphinx to properly
parse the text file, as they're already in good shape,
not requiring massive changes in order to be parsed.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/locking/index.rst | 24 +++
...{lockdep-design.txt => lockdep-design.rst} | 51 +++--
Documentation/locking/lockstat.rst | 204 ++++++++++++++++++
Documentation/locking/lockstat.txt | 183 ----------------
.../{locktorture.txt => locktorture.rst} | 105 +++++----
.../{mutex-design.txt => mutex-design.rst} | 26 ++-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++++++------
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +--
.../locking/{spinlocks.txt => spinlocks.rst} | 32 ++-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +++----
Documentation/pi-futex.txt | 2 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/rwsem.h | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
lib/Kconfig.debug | 4 +-
20 files changed, 511 insertions(+), 387 deletions(-)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
create mode 100644 Documentation/locking/lockstat.rst
delete mode 100644 Documentation/locking/lockstat.txt
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index dc698ea456e0..a8518ac0d31d 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -1364,7 +1364,7 @@ Futex API reference
Further reading
===============
-- ``Documentation/locking/spinlocks.txt``: Linus Torvalds' spinlocking
+- ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking
tutorial in the kernel sources.
- Unix Systems for Modern Architectures: Symmetric Multiprocessing and
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
new file mode 100644
index 000000000000..ef5da7fe9aac
--- /dev/null
+++ b/Documentation/locking/index.rst
@@ -0,0 +1,24 @@
+:orphan:
+
+=======
+locking
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ lockdep-design
+ lockstat
+ locktorture
+ mutex-design
+ rt-mutex-design
+ rt-mutex
+ spinlocks
+ ww-mutex-design
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.rst
similarity index 93%
rename from Documentation/locking/lockdep-design.txt
rename to Documentation/locking/lockdep-design.rst
index f189d130e543..23fcbc4d3fc0 100644
--- a/Documentation/locking/lockdep-design.txt
+++ b/Documentation/locking/lockdep-design.rst
@@ -2,6 +2,7 @@ Runtime locking correctness validator
=====================================
started by Ingo Molnar <mingo@redhat.com>
+
additions by Arjan van de Ven <arjan@linux.intel.com>
Lock-class
@@ -56,7 +57,7 @@ where the last 1 category is:
When locking rules are violated, these usage bits are presented in the
locking error messages, inside curlies, with a total of 2 * n STATEs bits.
-A contrived example:
+A contrived example::
modprobe/2287 is trying to acquire lock:
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
@@ -70,12 +71,14 @@ of the lock and readlock (if exists), for each of the n STATEs listed
above respectively, and the character displayed at each bit position
indicates:
+ === ===================================================
'.' acquired while irqs disabled and not in irq context
'-' acquired in irq context
'+' acquired with irqs enabled
'?' acquired in irq context with irqs enabled.
+ === ===================================================
-The bits are illustrated with an example:
+The bits are illustrated with an example::
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
||||
@@ -90,13 +93,13 @@ context and whether that STATE is enabled yields four possible cases as
shown in the table below. The bit character is able to indicate which
exact case is for the lock as of the reporting time.
- -------------------------------------------
+ +--------------+-------------+--------------+
| | irq enabled | irq disabled |
- |-------------------------------------------|
+ +--------------+-------------+--------------+
| ever in irq | ? | - |
- |-------------------------------------------|
+ +--------------+-------------+--------------+
| never in irq | + | . |
- -------------------------------------------
+ +--------------+-------------+--------------+
The character '-' suggests irq is disabled because if otherwise the
charactor '?' would have been shown instead. Similar deduction can be
@@ -113,7 +116,7 @@ is irq-unsafe means it was ever acquired with irq enabled.
A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The
following states must be exclusive: only one of them is allowed to be set
-for any lock-class based on its usage:
+for any lock-class based on its usage::
<hardirq-safe> or <hardirq-unsafe>
<softirq-safe> or <softirq-unsafe>
@@ -134,7 +137,7 @@ Multi-lock dependency rules:
The same lock-class must not be acquired twice, because this could lead
to lock recursion deadlocks.
-Furthermore, two locks can not be taken in inverse order:
+Furthermore, two locks can not be taken in inverse order::
<L1> -> <L2>
<L2> -> <L1>
@@ -148,7 +151,7 @@ operations; the validator will still find whether these locks can be
acquired in a circular fashion.
Furthermore, the following usage based lock dependencies are not allowed
-between any two lock-classes:
+between any two lock-classes::
<hardirq-safe> -> <hardirq-unsafe>
<softirq-safe> -> <softirq-unsafe>
@@ -204,16 +207,16 @@ the ordering is not static.
In order to teach the validator about this correct usage model, new
versions of the various locking primitives were added that allow you to
specify a "nesting level". An example call, for the block device mutex,
-looks like this:
+looks like this::
-enum bdev_bd_mutex_lock_class
-{
+ enum bdev_bd_mutex_lock_class
+ {
BD_MUTEX_NORMAL,
BD_MUTEX_WHOLE,
BD_MUTEX_PARTITION
-};
+ };
- mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
In this case the locking is done on a bdev object that is known to be a
partition.
@@ -234,7 +237,7 @@ must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock).
As the name suggests, lockdep_assert_held* family of macros assert that a
particular lock is held at a certain time (and generate a WARN() otherwise).
This annotation is largely used all over the kernel, e.g. kernel/sched/
-core.c
+core.c::
void update_rq_clock(struct rq *rq)
{
@@ -253,7 +256,7 @@ out to be especially helpful to debug code with callbacks, where an upper
layer assumes a lock remains taken, but a lower layer thinks it can maybe drop
and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock()
returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check
-that nobody tampered with the lock, e.g. kernel/sched/sched.h
+that nobody tampered with the lock, e.g. kernel/sched/sched.h::
static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf)
{
@@ -280,7 +283,7 @@ correctness) in the sense that for every simple, standalone single-task
locking sequence that occurred at least once during the lifetime of the
kernel, the validator proves it with a 100% certainty that no
combination and timing of these locking sequences can cause any class of
-lock related deadlock. [*]
+lock related deadlock. [1]_
I.e. complex multi-CPU and multi-task locking scenarios do not have to
occur in practice to prove a deadlock: only the simple 'component'
@@ -299,7 +302,9 @@ possible combination of locking interaction between CPUs, combined with
every possible hardirq and softirq nesting scenario (which is impossible
to do in practice).
-[*] assuming that the validator itself is 100% correct, and no other
+.. [1]
+
+ assuming that the validator itself is 100% correct, and no other
part of the system corrupts the state of the validator in any way.
We also assume that all NMI/SMM paths [which could interrupt
even hardirq-disabled codepaths] are correct and do not interfere
@@ -310,7 +315,7 @@ to do in practice).
Performance:
------------
-The above rules require _massive_ amounts of runtime checking. If we did
+The above rules require **massive** amounts of runtime checking. If we did
that for every lock taken and for every irqs-enable event, it would
render the system practically unusably slow. The complexity of checking
is O(N^2), so even with just a few hundred lock-classes we'd have to do
@@ -369,17 +374,17 @@ be harder to do than to say.
Of course, if you do run out of lock classes, the next thing to do is
to find the offending lock classes. First, the following command gives
-you the number of lock classes currently in use along with the maximum:
+you the number of lock classes currently in use along with the maximum::
grep "lock-classes" /proc/lockdep_stats
-This command produces the following output on a modest system:
+This command produces the following output on a modest system::
- lock-classes: 748 [max: 8191]
+ lock-classes: 748 [max: 8191]
If the number allocated (748 above) increases continually over time,
then there is likely a leak. The following command can be used to
-identify the leaking lock classes:
+identify the leaking lock classes::
grep "BD" /proc/lockdep
diff --git a/Documentation/locking/lockstat.rst b/Documentation/locking/lockstat.rst
new file mode 100644
index 000000000000..536eab8dbd99
--- /dev/null
+++ b/Documentation/locking/lockstat.rst
@@ -0,0 +1,204 @@
+===============
+Lock Statistics
+===============
+
+What
+====
+
+As the name suggests, it provides statistics on locks.
+
+
+Why
+===
+
+Because things like lock contention can severely impact performance.
+
+How
+===
+
+Lockdep already has hooks in the lock functions and maps lock instances to
+lock classes. We build on that (see Documentation/locking/lockdep-design.rst).
+The graph below shows the relation between the lock functions and the various
+hooks therein::
+
+ __acquire
+ |
+ lock _____
+ | \
+ | __contended
+ | |
+ | <wait>
+ | _______/
+ |/
+ |
+ __acquired
+ |
+ .
+ <hold>
+ .
+ |
+ __release
+ |
+ unlock
+
+ lock, unlock - the regular lock functions
+ __* - the hooks
+ <> - states
+
+With these hooks we provide the following statistics:
+
+ con-bounces
+ - number of lock contention that involved x-cpu data
+ contentions
+ - number of lock acquisitions that had to wait
+ wait time
+ min
+ - shortest (non-0) time we ever had to wait for a lock
+ max
+ - longest time we ever had to wait for a lock
+ total
+ - total time we spend waiting on this lock
+ avg
+ - average time spent waiting on this lock
+ acq-bounces
+ - number of lock acquisitions that involved x-cpu data
+ acquisitions
+ - number of times we took the lock
+ hold time
+ min
+ - shortest (non-0) time we ever held the lock
+ max
+ - longest time we ever held the lock
+ total
+ - total time this lock was held
+ avg
+ - average time this lock was held
+
+These numbers are gathered per lock class, per read/write state (when
+applicable).
+
+It also tracks 4 contention points per class. A contention point is a call site
+that had to wait on lock acquisition.
+
+Configuration
+-------------
+
+Lock statistics are enabled via CONFIG_LOCK_STAT.
+
+Usage
+-----
+
+Enable collection of statistics::
+
+ # echo 1 >/proc/sys/kernel/lock_stat
+
+Disable collection of statistics::
+
+ # echo 0 >/proc/sys/kernel/lock_stat
+
+Look at the current lock statistics::
+
+ ( line numbers not part of actual output, done for clarity in the explanation
+ below )
+
+ # less /proc/lock_stat
+
+ 01 lock_stat version 0.4
+ 02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
+ 04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 05
+ 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
+ 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
+ 08 ---------------
+ 09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
+ 10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
+ 13 ---------------
+ 14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
+ 15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
+ 16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 18
+ 19.............................................................................................................................................................................................................................
+ 20
+ 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
+ 22 ---------------
+ 23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+ 27 ---------------
+ 28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+
+
+This excerpt shows the first two lock class statistics. Line 01 shows the
+output version - each time the format changes this will be updated. Line 02-04
+show the header with column descriptions. Lines 05-18 and 20-31 show the actual
+statistics. These statistics come in two parts; the actual stats separated by a
+short separator (line 08, 13) from the contention points.
+
+Lines 09-12 show the first 4 recorded contention points (the code
+which tries to get the lock) and lines 14-17 show the first 4 recorded
+contended points (the lock holder). It is possible that the max
+con-bounces point is missing in the statistics.
+
+The first lock (05-18) is a read/write lock, and shows two lines above the
+short separator. The contention points don't match the column descriptors,
+they have two: contentions and [<IP>] symbol. The second set of contention
+points are the points we're contending with.
+
+The integer part of the time values is in us.
+
+Dealing with nested locks, subclasses may appear::
+
+ 32...........................................................................................................................................................................................................................
+ 33
+ 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
+ 35 ---------
+ 36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
+ 39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
+ 40 ---------
+ 41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 45
+ 46...........................................................................................................................................................................................................................
+ 47
+ 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
+ 49 -----------
+ 50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 51 -----------
+ 52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+
+Line 48 shows statistics for the second subclass (/1) of &rq->lock class
+(subclass starts from 0), since in this case, as line 50 suggests,
+double_rq_lock actually acquires a nested lock of two spinlocks.
+
+View the top contending locks::
+
+ # grep : /proc/lock_stat | head
+ clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
+ tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
+ &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
+ &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
+ &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
+ tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
+ tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
+ rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
+ &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
+ rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
+
+Clear the statistics::
+
+ # echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt
deleted file mode 100644
index fdbeb0c45ef3..000000000000
--- a/Documentation/locking/lockstat.txt
+++ /dev/null
@@ -1,183 +0,0 @@
-
-LOCK STATISTICS
-
-- WHAT
-
-As the name suggests, it provides statistics on locks.
-
-- WHY
-
-Because things like lock contention can severely impact performance.
-
-- HOW
-
-Lockdep already has hooks in the lock functions and maps lock instances to
-lock classes. We build on that (see Documentation/locking/lockdep-design.txt).
-The graph below shows the relation between the lock functions and the various
-hooks therein.
-
- __acquire
- |
- lock _____
- | \
- | __contended
- | |
- | <wait>
- | _______/
- |/
- |
- __acquired
- |
- .
- <hold>
- .
- |
- __release
- |
- unlock
-
-lock, unlock - the regular lock functions
-__* - the hooks
-<> - states
-
-With these hooks we provide the following statistics:
-
- con-bounces - number of lock contention that involved x-cpu data
- contentions - number of lock acquisitions that had to wait
- wait time min - shortest (non-0) time we ever had to wait for a lock
- max - longest time we ever had to wait for a lock
- total - total time we spend waiting on this lock
- avg - average time spent waiting on this lock
- acq-bounces - number of lock acquisitions that involved x-cpu data
- acquisitions - number of times we took the lock
- hold time min - shortest (non-0) time we ever held the lock
- max - longest time we ever held the lock
- total - total time this lock was held
- avg - average time this lock was held
-
-These numbers are gathered per lock class, per read/write state (when
-applicable).
-
-It also tracks 4 contention points per class. A contention point is a call site
-that had to wait on lock acquisition.
-
- - CONFIGURATION
-
-Lock statistics are enabled via CONFIG_LOCK_STAT.
-
- - USAGE
-
-Enable collection of statistics:
-
-# echo 1 >/proc/sys/kernel/lock_stat
-
-Disable collection of statistics:
-
-# echo 0 >/proc/sys/kernel/lock_stat
-
-Look at the current lock statistics:
-
-( line numbers not part of actual output, done for clarity in the explanation
- below )
-
-# less /proc/lock_stat
-
-01 lock_stat version 0.4
-02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
-04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-05
-06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
-07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
-08 ---------------
-09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
-10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
-13 ---------------
-14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
-15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
-16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-18
-19.............................................................................................................................................................................................................................
-20
-21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
-22 ---------------
-23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-27 ---------------
-28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-
-
-This excerpt shows the first two lock class statistics. Line 01 shows the
-output version - each time the format changes this will be updated. Line 02-04
-show the header with column descriptions. Lines 05-18 and 20-31 show the actual
-statistics. These statistics come in two parts; the actual stats separated by a
-short separator (line 08, 13) from the contention points.
-
-Lines 09-12 show the first 4 recorded contention points (the code
-which tries to get the lock) and lines 14-17 show the first 4 recorded
-contended points (the lock holder). It is possible that the max
-con-bounces point is missing in the statistics.
-
-The first lock (05-18) is a read/write lock, and shows two lines above the
-short separator. The contention points don't match the column descriptors,
-they have two: contentions and [<IP>] symbol. The second set of contention
-points are the points we're contending with.
-
-The integer part of the time values is in us.
-
-Dealing with nested locks, subclasses may appear:
-
-32...........................................................................................................................................................................................................................
-33
-34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
-35 ---------
-36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
-39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
-40 ---------
-41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
-45
-46...........................................................................................................................................................................................................................
-47
-48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
-49 -----------
-50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-51 -----------
-52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
-54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-
-Line 48 shows statistics for the second subclass (/1) of &rq->lock class
-(subclass starts from 0), since in this case, as line 50 suggests,
-double_rq_lock actually acquires a nested lock of two spinlocks.
-
-View the top contending locks:
-
-# grep : /proc/lock_stat | head
- clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
- tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
- &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
- &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
- &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
- tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
- tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
- rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
- &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
- rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
-
-Clear the statistics:
-
-# echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.rst
similarity index 57%
rename from Documentation/locking/locktorture.txt
rename to Documentation/locking/locktorture.rst
index 6a8df4cd19bf..e79eeeca3ac6 100644
--- a/Documentation/locking/locktorture.txt
+++ b/Documentation/locking/locktorture.rst
@@ -1,6 +1,9 @@
+==================================
Kernel Lock Torture Test Operation
+==================================
CONFIG_LOCK_TORTURE_TEST
+========================
The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
that runs torture tests on core kernel locking primitives. The kernel
@@ -18,61 +21,77 @@ can be simulated by either enlarging this critical region hold time and/or
creating more kthreads.
-MODULE PARAMETERS
+Module Parameters
+=================
This module has the following parameters:
- ** Locktorture-specific **
+Locktorture-specific
+--------------------
-nwriters_stress Number of kernel threads that will stress exclusive lock
+nwriters_stress
+ Number of kernel threads that will stress exclusive lock
ownership (writers). The default value is twice the number
of online CPUs.
-nreaders_stress Number of kernel threads that will stress shared lock
+nreaders_stress
+ Number of kernel threads that will stress shared lock
ownership (readers). The default is the same amount of writer
locks. If the user did not specify nwriters_stress, then
both readers and writers be the amount of online CPUs.
-torture_type Type of lock to torture. By default, only spinlocks will
+torture_type
+ Type of lock to torture. By default, only spinlocks will
be tortured. This module can torture the following locks,
with string values as follows:
- o "lock_busted": Simulates a buggy lock implementation.
+ - "lock_busted":
+ Simulates a buggy lock implementation.
- o "spin_lock": spin_lock() and spin_unlock() pairs.
+ - "spin_lock":
+ spin_lock() and spin_unlock() pairs.
- o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq()
- pairs.
+ - "spin_lock_irq":
+ spin_lock_irq() and spin_unlock_irq() pairs.
- o "rw_lock": read/write lock() and unlock() rwlock pairs.
+ - "rw_lock":
+ read/write lock() and unlock() rwlock pairs.
- o "rw_lock_irq": read/write lock_irq() and unlock_irq()
- rwlock pairs.
+ - "rw_lock_irq":
+ read/write lock_irq() and unlock_irq()
+ rwlock pairs.
- o "mutex_lock": mutex_lock() and mutex_unlock() pairs.
+ - "mutex_lock":
+ mutex_lock() and mutex_unlock() pairs.
- o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock()
- pairs. Kernel must have CONFIG_RT_MUTEX=y.
+ - "rtmutex_lock":
+ rtmutex_lock() and rtmutex_unlock() pairs.
+ Kernel must have CONFIG_RT_MUTEX=y.
- o "rwsem_lock": read/write down() and up() semaphore pairs.
+ - "rwsem_lock":
+ read/write down() and up() semaphore pairs.
- ** Torture-framework (RCU + locking) **
+Torture-framework (RCU + locking)
+---------------------------------
-shutdown_secs The number of seconds to run the test before terminating
+shutdown_secs
+ The number of seconds to run the test before terminating
the test and powering off the system. The default is
zero, which disables test termination and system shutdown.
This capability is useful for automated testing.
-onoff_interval The number of seconds between each attempt to execute a
+onoff_interval
+ The number of seconds between each attempt to execute a
randomly selected CPU-hotplug operation. Defaults
to zero, which disables CPU hotplugging. In
CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
refuse to do any CPU-hotplug operations regardless of
what value is specified for onoff_interval.
-onoff_holdoff The number of seconds to wait until starting CPU-hotplug
+onoff_holdoff
+ The number of seconds to wait until starting CPU-hotplug
operations. This would normally only be used when
locktorture was built into the kernel and started
automatically at boot time, in which case it is useful
@@ -80,53 +99,59 @@ onoff_holdoff The number of seconds to wait until starting CPU-hotplug
coming and going. This parameter is only useful if
CONFIG_HOTPLUG_CPU is enabled.
-stat_interval Number of seconds between statistics-related printk()s.
+stat_interval
+ Number of seconds between statistics-related printk()s.
By default, locktorture will report stats every 60 seconds.
Setting the interval to zero causes the statistics to
be printed -only- when the module is unloaded, and this
is the default.
-stutter The length of time to run the test before pausing for this
+stutter
+ The length of time to run the test before pausing for this
same period of time. Defaults to "stutter=5", so as
to run and pause for (roughly) five-second intervals.
Specifying "stutter=0" causes the test to run continuously
without pausing, which is the old default behavior.
-shuffle_interval The number of seconds to keep the test threads affinitied
+shuffle_interval
+ The number of seconds to keep the test threads affinitied
to a particular subset of the CPUs, defaults to 3 seconds.
Used in conjunction with test_no_idle_hz.
-verbose Enable verbose debugging printing, via printk(). Enabled
+verbose
+ Enable verbose debugging printing, via printk(). Enabled
by default. This extra information is mostly related to
high-level errors and reports from the main 'torture'
framework.
-STATISTICS
+Statistics
+==========
-Statistics are printed in the following format:
+Statistics are printed in the following format::
-spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
- (A) (B) (C) (D) (E)
+ spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
+ (A) (B) (C) (D) (E)
-(A): Lock type that is being tortured -- torture_type parameter.
+ (A): Lock type that is being tortured -- torture_type parameter.
-(B): Number of writer lock acquisitions. If dealing with a read/write primitive
- a second "Reads" statistics line is printed.
+ (B): Number of writer lock acquisitions. If dealing with a read/write
+ primitive a second "Reads" statistics line is printed.
-(C): Number of times the lock was acquired.
+ (C): Number of times the lock was acquired.
-(D): Min and max number of times threads failed to acquire the lock.
+ (D): Min and max number of times threads failed to acquire the lock.
-(E): true/false values if there were errors acquiring the lock. This should
- -only- be positive if there is a bug in the locking primitive's
- implementation. Otherwise a lock should never fail (i.e., spin_lock()).
- Of course, the same applies for (C), above. A dummy example of this is
- the "lock_busted" type.
+ (E): true/false values if there were errors acquiring the lock. This should
+ -only- be positive if there is a bug in the locking primitive's
+ implementation. Otherwise a lock should never fail (i.e., spin_lock()).
+ Of course, the same applies for (C), above. A dummy example of this is
+ the "lock_busted" type.
-USAGE
+Usage
+=====
-The following script may be used to torture locks:
+The following script may be used to torture locks::
#!/bin/sh
diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.rst
similarity index 94%
rename from Documentation/locking/mutex-design.txt
rename to Documentation/locking/mutex-design.rst
index 818aca19612f..4d8236b81fa5 100644
--- a/Documentation/locking/mutex-design.txt
+++ b/Documentation/locking/mutex-design.rst
@@ -1,6 +1,9 @@
+=======================
Generic Mutex Subsystem
+=======================
started by Ingo Molnar <mingo@redhat.com>
+
updated by Davidlohr Bueso <davidlohr@hp.com>
What are mutexes?
@@ -23,7 +26,7 @@ Implementation
Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h
and implemented in kernel/locking/mutex.c. These locks use an atomic variable
(->owner) to keep track of the lock state during its lifetime. Field owner
-actually contains 'struct task_struct *' to the current lock owner and it is
+actually contains `struct task_struct *` to the current lock owner and it is
therefore NULL if not currently owned. Since task_struct pointers are aligned
at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
if waiter list is non-empty). In its most basic form it also includes a
@@ -101,29 +104,36 @@ features that make lock debugging easier and faster:
Interfaces
----------
-Statically define the mutex:
+Statically define the mutex::
+
DEFINE_MUTEX(name);
-Dynamically initialize the mutex:
+Dynamically initialize the mutex::
+
mutex_init(mutex);
-Acquire the mutex, uninterruptible:
+Acquire the mutex, uninterruptible::
+
void mutex_lock(struct mutex *lock);
void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
int mutex_trylock(struct mutex *lock);
-Acquire the mutex, interruptible:
+Acquire the mutex, interruptible::
+
int mutex_lock_interruptible_nested(struct mutex *lock,
unsigned int subclass);
int mutex_lock_interruptible(struct mutex *lock);
-Acquire the mutex, interruptible, if dec to 0:
+Acquire the mutex, interruptible, if dec to 0::
+
int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
-Unlock the mutex:
+Unlock the mutex::
+
void mutex_unlock(struct mutex *lock);
-Test if the mutex is taken:
+Test if the mutex is taken::
+
int mutex_is_locked(struct mutex *lock);
Disadvantages
diff --git a/Documentation/locking/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.rst
similarity index 91%
rename from Documentation/locking/rt-mutex-design.txt
rename to Documentation/locking/rt-mutex-design.rst
index 3d7b865539cc..59c2a64efb21 100644
--- a/Documentation/locking/rt-mutex-design.txt
+++ b/Documentation/locking/rt-mutex-design.rst
@@ -1,14 +1,15 @@
-#
-# Copyright (c) 2006 Steven Rostedt
-# Licensed under the GNU Free Documentation License, Version 1.2
-#
-
+==============================
RT-mutex implementation design
-------------------------------
+==============================
+
+Copyright (c) 2006 Steven Rostedt
+
+Licensed under the GNU Free Documentation License, Version 1.2
+
This document tries to describe the design of the rtmutex.c implementation.
It doesn't describe the reasons why rtmutex.c exists. For that please see
-Documentation/locking/rt-mutex.txt. Although this document does explain problems
+Documentation/locking/rt-mutex.rst. Although this document does explain problems
that happen without this code, but that is in the concept to understand
what the code actually is doing.
@@ -41,17 +42,17 @@ to release the lock, because for all we know, B is a CPU hog and will
never give C a chance to release the lock. This is called unbounded priority
inversion.
-Here's a little ASCII art to show the problem.
+Here's a little ASCII art to show the problem::
- grab lock L1 (owned by C)
- |
-A ---+
- C preempted by B
- |
-C +----+
+ grab lock L1 (owned by C)
+ |
+ A ---+
+ C preempted by B
+ |
+ C +----+
-B +-------->
- B now keeps A from running.
+ B +-------->
+ B now keeps A from running.
Priority Inheritance (PI)
@@ -75,24 +76,29 @@ Terminology
Here I explain some terminology that is used in this document to help describe
the design that is used to implement PI.
-PI chain - The PI chain is an ordered series of locks and processes that cause
+PI chain
+ - The PI chain is an ordered series of locks and processes that cause
processes to inherit priorities from a previous process that is
blocked on one of its locks. This is described in more detail
later in this document.
-mutex - In this document, to differentiate from locks that implement
+mutex
+ - In this document, to differentiate from locks that implement
PI and spin locks that are used in the PI code, from now on
the PI locks will be called a mutex.
-lock - In this document from now on, I will use the term lock when
+lock
+ - In this document from now on, I will use the term lock when
referring to spin locks that are used to protect parts of the PI
algorithm. These locks disable preemption for UP (when
CONFIG_PREEMPT is enabled) and on SMP prevents multiple CPUs from
entering critical sections simultaneously.
-spin lock - Same as lock above.
+spin lock
+ - Same as lock above.
-waiter - A waiter is a struct that is stored on the stack of a blocked
+waiter
+ - A waiter is a struct that is stored on the stack of a blocked
process. Since the scope of the waiter is within the code for
a process being blocked on the mutex, it is fine to allocate
the waiter on the process's stack (local variable). This
@@ -104,14 +110,18 @@ waiter - A waiter is a struct that is stored on the stack of a blocked
waiter is sometimes used in reference to the task that is waiting
on a mutex. This is the same as waiter->task.
-waiters - A list of processes that are blocked on a mutex.
+waiters
+ - A list of processes that are blocked on a mutex.
-top waiter - The highest priority process waiting on a specific mutex.
+top waiter
+ - The highest priority process waiting on a specific mutex.
-top pi waiter - The highest priority process waiting on one of the mutexes
+top pi waiter
+ - The highest priority process waiting on one of the mutexes
that a specific process owns.
-Note: task and process are used interchangeably in this document, mostly to
+Note:
+ task and process are used interchangeably in this document, mostly to
differentiate between two processes that are being described together.
@@ -123,7 +133,7 @@ inheritance to take place. Multiple chains may converge, but a chain
would never diverge, since a process can't be blocked on more than one
mutex at a time.
-Example:
+Example::
Process: A, B, C, D, E
Mutexes: L1, L2, L3, L4
@@ -137,21 +147,21 @@ Example:
D owns L4
E blocked on L4
-The chain would be:
+The chain would be::
E->L4->D->L3->C->L2->B->L1->A
To show where two chains merge, we could add another process F and
another mutex L5 where B owns L5 and F is blocked on mutex L5.
-The chain for F would be:
+The chain for F would be::
F->L5->B->L1->A
Since a process may own more than one mutex, but never be blocked on more than
one, the chains merge.
-Here we show both chains:
+Here we show both chains::
E->L4->D->L3->C->L2-+
|
@@ -165,12 +175,12 @@ than the processes to the left or below in the chain.
Also since a mutex may have more than one process blocked on it, we can
have multiple chains merge at mutexes. If we add another process G that is
-blocked on mutex L2:
+blocked on mutex L2::
G->L2->B->L1->A
And once again, to show how this can grow I will show the merging chains
-again.
+again::
E->L4->D->L3->C-+
+->L2-+
@@ -184,7 +194,7 @@ the chain (A and B in this example), must have their priorities increased
to that of G.
Mutex Waiters Tree
------------------
+------------------
Every mutex keeps track of all the waiters that are blocked on itself. The
mutex has a rbtree to store these waiters by priority. This tree is protected
@@ -219,19 +229,19 @@ defined. But is very complex to figure it out, since it depends on all
the nesting of mutexes. Let's look at the example where we have 3 mutexes,
L1, L2, and L3, and four separate functions func1, func2, func3 and func4.
The following shows a locking order of L1->L2->L3, but may not actually
-be directly nested that way.
+be directly nested that way::
-void func1(void)
-{
+ void func1(void)
+ {
mutex_lock(L1);
/* do anything */
mutex_unlock(L1);
-}
+ }
-void func2(void)
-{
+ void func2(void)
+ {
mutex_lock(L1);
mutex_lock(L2);
@@ -239,10 +249,10 @@ void func2(void)
mutex_unlock(L2);
mutex_unlock(L1);
-}
+ }
-void func3(void)
-{
+ void func3(void)
+ {
mutex_lock(L2);
mutex_lock(L3);
@@ -250,30 +260,30 @@ void func3(void)
mutex_unlock(L3);
mutex_unlock(L2);
-}
+ }
-void func4(void)
-{
+ void func4(void)
+ {
mutex_lock(L3);
/* do something again */
mutex_unlock(L3);
-}
+ }
Now we add 4 processes that run each of these functions separately.
Processes A, B, C, and D which run functions func1, func2, func3 and func4
respectively, and such that D runs first and A last. With D being preempted
-in func4 in the "do something again" area, we have a locking that follows:
+in func4 in the "do something again" area, we have a locking that follows::
-D owns L3
- C blocked on L3
- C owns L2
- B blocked on L2
- B owns L1
- A blocked on L1
+ D owns L3
+ C blocked on L3
+ C owns L2
+ B blocked on L2
+ B owns L1
+ A blocked on L1
-And thus we have the chain A->L1->B->L2->C->L3->D.
+ And thus we have the chain A->L1->B->L2->C->L3->D.
This gives us a PI depth of 4 (four processes), but looking at any of the
functions individually, it seems as though they only have at most a locking
@@ -298,7 +308,7 @@ not true, the rtmutex.c code will be broken!), this allows for the least
significant bit to be used as a flag. Bit 0 is used as the "Has Waiters"
flag. It's set whenever there are waiters on a mutex.
-See Documentation/locking/rt-mutex.txt for further details.
+See Documentation/locking/rt-mutex.rst for further details.
cmpxchg Tricks
--------------
@@ -307,17 +317,17 @@ Some architectures implement an atomic cmpxchg (Compare and Exchange). This
is used (when applicable) to keep the fast path of grabbing and releasing
mutexes short.
-cmpxchg is basically the following function performed atomically:
+cmpxchg is basically the following function performed atomically::
-unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
-{
+ unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
+ {
unsigned long T = *A;
if (*A == *B) {
*A = *C;
}
return T;
-}
-#define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
+ }
+ #define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
This is really nice to have, since it allows you to only update a variable
if the variable is what you expect it to be. You know if it succeeded if
@@ -352,9 +362,10 @@ Then rt_mutex_setprio is called to adjust the priority of the task to the
new priority. Note that rt_mutex_setprio is defined in kernel/sched/core.c
to implement the actual change in priority.
-(Note: For the "prio" field in task_struct, the lower the number, the
+Note:
+ For the "prio" field in task_struct, the lower the number, the
higher the priority. A "prio" of 5 is of higher priority than a
- "prio" of 10.)
+ "prio" of 10.
It is interesting to note that rt_mutex_adjust_prio can either increase
or decrease the priority of the task. In the case that a higher priority
@@ -439,6 +450,7 @@ wait_lock, which this code currently holds. So setting the "Has Waiters" flag
forces the current owner to synchronize with this code.
The lock is taken if the following are true:
+
1) The lock has no owner
2) The current task is the highest priority against all other
waiters of the lock
@@ -546,10 +558,13 @@ Credits
-------
Author: Steven Rostedt <rostedt@goodmis.org>
+
Updated: Alex Shi <alex.shi@linaro.org> - 7/6/2017
-Original Reviewers: Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
+Original Reviewers:
+ Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
Randy Dunlap
+
Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior
Updates
diff --git a/Documentation/locking/rt-mutex.txt b/Documentation/locking/rt-mutex.rst
similarity index 71%
rename from Documentation/locking/rt-mutex.txt
rename to Documentation/locking/rt-mutex.rst
index 35793e003041..c365dc302081 100644
--- a/Documentation/locking/rt-mutex.txt
+++ b/Documentation/locking/rt-mutex.rst
@@ -1,5 +1,6 @@
+==================================
RT-mutex subsystem with PI support
-----------------------------------
+==================================
RT-mutexes with priority inheritance are used to support PI-futexes,
which enable pthread_mutex_t priority inheritance attributes
@@ -46,27 +47,30 @@ The state of the rt-mutex is tracked via the owner field of the rt-mutex
structure:
lock->owner holds the task_struct pointer of the owner. Bit 0 is used to
-keep track of the "lock has waiters" state.
+keep track of the "lock has waiters" state:
- owner bit0
+ ============ ======= ================================================
+ owner bit0 Notes
+ ============ ======= ================================================
NULL 0 lock is free (fast acquire possible)
NULL 1 lock is free and has waiters and the top waiter
- is going to take the lock*
+ is going to take the lock [1]_
taskpointer 0 lock is held (fast release possible)
- taskpointer 1 lock is held and has waiters**
+ taskpointer 1 lock is held and has waiters [2]_
+ ============ ======= ================================================
The fast atomic compare exchange based acquire and release is only
possible when bit 0 of lock->owner is 0.
-(*) It also can be a transitional state when grabbing the lock
-with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
-we need to set the bit0 before looking at the lock, and the owner may be
-NULL in this small time, hence this can be a transitional state.
+.. [1] It also can be a transitional state when grabbing the lock
+ with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
+ we need to set the bit0 before looking at the lock, and the owner may
+ be NULL in this small time, hence this can be a transitional state.
-(**) There is a small time when bit 0 is set but there are no
-waiters. This can happen when grabbing the lock in the slow path.
-To prevent a cmpxchg of the owner releasing the lock, we need to
-set this bit before looking at the lock.
+.. [2] There is a small time when bit 0 is set but there are no
+ waiters. This can happen when grabbing the lock in the slow path.
+ To prevent a cmpxchg of the owner releasing the lock, we need to
+ set this bit before looking at the lock.
BTW, there is still technically a "Pending Owner", it's just not called
that anymore. The pending owner happens to be the top_waiter of a lock
diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.rst
similarity index 89%
rename from Documentation/locking/spinlocks.txt
rename to Documentation/locking/spinlocks.rst
index ff35e40bdf5b..098107fb7d86 100644
--- a/Documentation/locking/spinlocks.txt
+++ b/Documentation/locking/spinlocks.rst
@@ -1,8 +1,13 @@
+===============
+Locking lessons
+===============
+
Lesson 1: Spin locks
+====================
-The most basic primitive for locking is spinlock.
+The most basic primitive for locking is spinlock::
-static DEFINE_SPINLOCK(xxx_lock);
+ static DEFINE_SPINLOCK(xxx_lock);
unsigned long flags;
@@ -19,23 +24,25 @@ worry about UP vs SMP issues: the spinlocks work correctly under both.
NOTE! Implications of spin_locks for memory are further described in:
Documentation/memory-barriers.txt
+
(5) LOCK operations.
+
(6) UNLOCK operations.
The above is usually pretty simple (you usually need and want only one
spinlock for most things - using more than one spinlock can make things a
lot more complex and even slower and is usually worth it only for
-sequences that you _know_ need to be split up: avoid it at all cost if you
+sequences that you **know** need to be split up: avoid it at all cost if you
aren't sure).
This is really the only really hard part about spinlocks: once you start
using spinlocks they tend to expand to areas you might not have noticed
before, because you have to make sure the spinlocks correctly protect the
-shared data structures _everywhere_ they are used. The spinlocks are most
+shared data structures **everywhere** they are used. The spinlocks are most
easily added to places that are completely independent of other code (for
example, internal driver data structures that nobody else ever touches).
- NOTE! The spin-lock is safe only when you _also_ use the lock itself
+ NOTE! The spin-lock is safe only when you **also** use the lock itself
to do locking across CPU's, which implies that EVERYTHING that
touches a shared variable has to agree about the spinlock they want
to use.
@@ -43,6 +50,7 @@ example, internal driver data structures that nobody else ever touches).
----
Lesson 2: reader-writer spinlocks.
+==================================
If your data accesses have a very natural pattern where you usually tend
to mostly read from the shared variables, the reader-writer locks
@@ -54,7 +62,7 @@ to change the variables it has to get an exclusive write lock.
simple spinlocks. Unless the reader critical section is long, you
are better off just using spinlocks.
-The routines look the same as above:
+The routines look the same as above::
rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock);
@@ -71,7 +79,7 @@ The routines look the same as above:
The above kind of lock may be useful for complex data structures like
linked lists, especially searching for entries without changing the list
itself. The read lock allows many concurrent readers. Anything that
-_changes_ the list will have to get the write lock.
+**changes** the list will have to get the write lock.
NOTE! RCU is better for list traversal, but requires careful
attention to design detail (see Documentation/RCU/listRCU.txt).
@@ -87,10 +95,11 @@ to get the write-lock at the very beginning.
----
Lesson 3: spinlocks revisited.
+==============================
The single spin-lock primitives above are by no means the only ones. They
are the most safe ones, and the ones that work under all circumstances,
-but partly _because_ they are safe they are also fairly slow. They are slower
+but partly **because** they are safe they are also fairly slow. They are slower
than they'd need to be, because they do have to disable interrupts
(which is just a single instruction on a x86, but it's an expensive one -
and on other architectures it can be worse).
@@ -98,7 +107,7 @@ and on other architectures it can be worse).
If you have a case where you have to protect a data structure across
several CPU's and you want to use spinlocks you can potentially use
cheaper versions of the spinlocks. IFF you know that the spinlocks are
-never used in interrupt handlers, you can use the non-irq versions:
+never used in interrupt handlers, you can use the non-irq versions::
spin_lock(&lock);
...
@@ -110,7 +119,7 @@ This is useful if you know that the data in question is only ever
manipulated from a "process context", ie no interrupts involved.
The reasons you mustn't use these versions if you have interrupts that
-play with the spinlock is that you can get deadlocks:
+play with the spinlock is that you can get deadlocks::
spin_lock(&lock);
...
@@ -147,9 +156,10 @@ indeed), while write-locks need to protect themselves against interrupts.
----
Reference information:
+======================
For dynamic initialization, use spin_lock_init() or rwlock_init() as
-appropriate:
+appropriate::
spinlock_t xxx_lock;
rwlock_t xxx_rw_lock;
diff --git a/Documentation/locking/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.rst
similarity index 93%
rename from Documentation/locking/ww-mutex-design.txt
rename to Documentation/locking/ww-mutex-design.rst
index f0ed7c30e695..1846c199da23 100644
--- a/Documentation/locking/ww-mutex-design.txt
+++ b/Documentation/locking/ww-mutex-design.rst
@@ -1,3 +1,4 @@
+======================================
Wound/Wait Deadlock-Proof Mutex Design
======================================
@@ -85,6 +86,7 @@ Furthermore there are three different class of w/w lock acquire functions:
no deadlock potential and hence the ww_mutex_lock call will block and not
prematurely return -EDEADLK. The advantage of the _slow functions is in
interface safety:
+
- ww_mutex_lock has a __must_check int return type, whereas ww_mutex_lock_slow
has a void return type. Note that since ww mutex code needs loops/retries
anyway the __must_check doesn't result in spurious warnings, even though the
@@ -115,36 +117,36 @@ expect the number of simultaneous competing transactions to be typically small,
and you want to reduce the number of rollbacks.
Three different ways to acquire locks within the same w/w class. Common
-definitions for methods #1 and #2:
+definitions for methods #1 and #2::
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-struct obj {
+ struct obj {
struct ww_mutex lock;
/* obj data */
-};
+ };
-struct obj_entry {
+ struct obj_entry {
struct list_head head;
struct obj *obj;
-};
+ };
Method 1, using a list in execbuf->buffers that's not allowed to be reordered.
This is useful if a list of required objects is already tracked somewhere.
Furthermore the lock helper can use propagate the -EALREADY return code back to
the caller as a signal that an object is twice on the list. This is useful if
the list is constructed from userspace input and the ABI requires userspace to
-not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl).
+not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl)::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *res_obj = NULL;
struct obj_entry *contended_entry = NULL;
struct obj_entry *entry;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
list_for_each_entry (entry, list, head) {
if (entry->obj == res_obj) {
res_obj = NULL;
@@ -160,7 +162,7 @@ retry:
ww_acquire_done(ctx);
return 0;
-err:
+ err:
list_for_each_entry_continue_reverse (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
@@ -176,14 +178,14 @@ err:
ww_acquire_fini(ctx);
return ret;
-}
+ }
Method 2, using a list in execbuf->buffers that can be reordered. Same semantics
of duplicate entry detection using -EALREADY as method 1 above. But the
-list-reordering allows for a bit more idiomatic code.
+list-reordering allows for a bit more idiomatic code::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry, *entry2;
ww_acquire_init(ctx, &ww_class);
@@ -216,24 +218,25 @@ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
ww_acquire_done(ctx);
return 0;
-}
+ }
-Unlocking works the same way for both methods #1 and #2:
+Unlocking works the same way for both methods #1 and #2::
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry;
list_for_each_entry (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
ww_acquire_fini(ctx);
-}
+ }
Method 3 is useful if the list of objects is constructed ad-hoc and not upfront,
e.g. when adjusting edges in a graph where each node has its own ww_mutex lock,
and edges can only be changed when holding the locks of all involved nodes. w/w
mutexes are a natural fit for such a case for two reasons:
+
- They can handle lock-acquisition in any order which allows us to start walking
a graph from a starting point and then iteratively discovering new edges and
locking down the nodes those edges connect to.
@@ -243,6 +246,7 @@ mutexes are a natural fit for such a case for two reasons:
as a starting point).
Note that this approach differs in two important ways from the above methods:
+
- Since the list of objects is dynamically constructed (and might very well be
different when retrying due to hitting the -EDEADLK die condition) there's
no need to keep any object on a persistent list when it's not locked. We can
@@ -260,17 +264,17 @@ any interface misuse for these cases.
Also, method 3 can't fail the lock acquisition step since it doesn't return
-EALREADY. Of course this would be different when using the _interruptible
-variants, but that's outside of the scope of these examples here.
+variants, but that's outside of the scope of these examples here::
-struct obj {
+ struct obj {
struct ww_mutex ww_mutex;
struct list_head locked_list;
-};
+ };
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-void __unlock_objs(struct list_head *list)
-{
+ void __unlock_objs(struct list_head *list)
+ {
struct obj *entry, *temp;
list_for_each_entry_safe (entry, temp, list, locked_list) {
@@ -279,15 +283,15 @@ void __unlock_objs(struct list_head *list)
list_del(&entry->locked_list);
ww_mutex_unlock(entry->ww_mutex)
}
-}
+ }
-void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *obj;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
/* re-init loop start state */
loop {
/* magic code which walks over a graph and decides which objects
@@ -312,13 +316,13 @@ retry:
ww_acquire_done(ctx);
return 0;
-}
+ }
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
__unlock_objs(list);
ww_acquire_fini(ctx);
-}
+ }
Method 4: Only lock one single objects. In that case deadlock detection and
prevention is obviously overkill, since with grabbing just one lock you can't
@@ -329,11 +333,14 @@ Implementation Details
----------------------
Design:
+^^^^^^^
+
ww_mutex currently encapsulates a struct mutex, this means no extra overhead for
normal mutex locks, which are far more common. As such there is only a small
increase in code size if wait/wound mutexes are not used.
We maintain the following invariants for the wait list:
+
(1) Waiters with an acquire context are sorted by stamp order; waiters
without an acquire context are interspersed in FIFO order.
(2) For Wait-Die, among waiters with contexts, only the first one can have
@@ -355,6 +362,8 @@ Design:
therefore be directed towards the uncontended cases.
Lockdep:
+^^^^^^^^
+
Special care has been taken to warn for as many cases of api abuse
as possible. Some common api abuses will be caught with
CONFIG_DEBUG_MUTEXES, but CONFIG_PROVE_LOCKING is recommended.
@@ -379,5 +388,6 @@ Lockdep:
having called ww_acquire_fini on the first.
- 'normal' deadlocks that can occur.
-FIXME: Update this section once we have the TASK_DEADLOCK task state flag magic
-implemented.
+FIXME:
+ Update this section once we have the TASK_DEADLOCK task state flag magic
+ implemented.
diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.txt
index b154f6c0c36e..c33ba2befbf8 100644
--- a/Documentation/pi-futex.txt
+++ b/Documentation/pi-futex.txt
@@ -119,4 +119,4 @@ properties of futexes, and all four combinations are possible: futex,
robust-futex, PI-futex, robust+PI-futex.
More details about priority inheritance can be found in
-Documentation/locking/rt-mutex.txt.
+Documentation/locking/rt-mutex.rst.
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 5fd8a1abd2be..b9a6be4b8499 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -1404,7 +1404,7 @@ Riferimento per l'API dei Futex
Approfondimenti
===============
-- ``Documentation/locking/spinlocks.txt``: la guida di Linus Torvalds agli
+- ``Documentation/locking/spinlocks.rst``: la guida di Linus Torvalds agli
spinlock del kernel.
- Unix Systems for Modern Architectures: Symmetric Multiprocessing and
diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c
index 53187821df01..fcfe1a03c4a1 100644
--- a/drivers/gpu/drm/drm_modeset_lock.c
+++ b/drivers/gpu/drm/drm_modeset_lock.c
@@ -36,7 +36,7 @@
* of extra utility/tracking out of our acquire-ctx. This is provided
* by &struct drm_modeset_lock and &struct drm_modeset_acquire_ctx.
*
- * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt
+ * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.rst
*
* The basic usage pattern is to::
*
diff --git a/include/linux/lockdep.h b/include/linux/lockdep.h
index 57baa27f238c..0b0d7259276d 100644
--- a/include/linux/lockdep.h
+++ b/include/linux/lockdep.h
@@ -5,7 +5,7 @@
* Copyright (C) 2006,2007 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
* Copyright (C) 2007 Red Hat, Inc., Peter Zijlstra
*
- * see Documentation/locking/lockdep-design.txt for more details.
+ * see Documentation/locking/lockdep-design.rst for more details.
*/
#ifndef __LINUX_LOCKDEP_H
#define __LINUX_LOCKDEP_H
diff --git a/include/linux/mutex.h b/include/linux/mutex.h
index 3093dd162424..dcd03fee6e01 100644
--- a/include/linux/mutex.h
+++ b/include/linux/mutex.h
@@ -151,7 +151,7 @@ static inline bool mutex_is_locked(struct mutex *lock)
/*
* See kernel/locking/mutex.c for detailed documentation of these APIs.
- * Also see Documentation/locking/mutex-design.txt.
+ * Also see Documentation/locking/mutex-design.rst.
*/
#ifdef CONFIG_DEBUG_LOCK_ALLOC
extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
diff --git a/include/linux/rwsem.h b/include/linux/rwsem.h
index e401358c4e7e..9d9c663987d8 100644
--- a/include/linux/rwsem.h
+++ b/include/linux/rwsem.h
@@ -160,7 +160,7 @@ extern void downgrade_write(struct rw_semaphore *sem);
* static then another method for expressing nested locking is
* the explicit definition of lock class keys and the use of
* lockdep_set_class() at lock initialization time.
- * See Documentation/locking/lockdep-design.txt for more details.)
+ * See Documentation/locking/lockdep-design.rst for more details.)
*/
extern void down_read_nested(struct rw_semaphore *sem, int subclass);
extern void down_write_nested(struct rw_semaphore *sem, int subclass);
diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
index 0c601ae072b3..edd1c082dbf5 100644
--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -16,7 +16,7 @@
* by Steven Rostedt, based on work by Gregory Haskins, Peter Morreale
* and Sven Dietrich.
*
- * Also see Documentation/locking/mutex-design.txt.
+ * Also see Documentation/locking/mutex-design.rst.
*/
#include <linux/mutex.h>
#include <linux/ww_mutex.h>
diff --git a/kernel/locking/rtmutex.c b/kernel/locking/rtmutex.c
index 38fbf9fa7f1b..fa83d36e30c6 100644
--- a/kernel/locking/rtmutex.c
+++ b/kernel/locking/rtmutex.c
@@ -9,7 +9,7 @@
* Copyright (C) 2005 Kihon Technologies Inc., Steven Rostedt
* Copyright (C) 2006 Esben Nielsen
*
- * See Documentation/locking/rt-mutex-design.txt for details.
+ * See Documentation/locking/rt-mutex-design.rst for details.
*/
#include <linux/spinlock.h>
#include <linux/export.h>
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index 6d2799190fba..18e8c180a874 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1139,7 +1139,7 @@ config PROVE_LOCKING
the proof of observed correctness is also maintained for an
arbitrary combination of these separate locking variants.
- For more details, see Documentation/locking/lockdep-design.txt.
+ For more details, see Documentation/locking/lockdep-design.rst.
config LOCK_STAT
bool "Lock usage statistics"
@@ -1153,7 +1153,7 @@ config LOCK_STAT
help
This feature enables tracking lock contention points
- For more details, see Documentation/locking/lockstat.txt
+ For more details, see Documentation/locking/lockstat.rst
This also enables lock events required by "perf lock",
subcommand of perf.
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 05/43] docs: powerpc: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (3 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 04/43] docs: locking: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 06/43] docs: connector: convert to ReST and rename to connector.rst Mauro Carvalho Chehab
` (37 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Linas Vepstas, Russell Currey, Sam Bobroff,
Oliver O'Halloran, Bjorn Helgaas, Benjamin Herrenschmidt,
Paul Mackerras, Michael Ellerman, Frederic Barrat,
Andrew Donnellan, Manoj N. Kumar, Matthew R. Ochs, Uma Krishnan,
Qiang Zhao, Li Yang, Greg Kroah-Hartman, Jiri Slaby, linux-pci,
linuxppc-dev, linux-scsi, linux-arm-kernel, Andrew Donnellan
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
Documentation/PCI/pci-error-recovery.rst | 23 ++-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +++-
.../{cpu_families.txt => cpu_families.rst} | 23 +--
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 ++++--
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 ++++++------
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +++++++------
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 ++++++------
Documentation/powerpc/index.rst | 34 ++++
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
Documentation/powerpc/ptrace.rst | 156 ++++++++++++++++++
Documentation/powerpc/ptrace.txt | 151 -----------------
.../{qe_firmware.txt => qe_firmware.rst} | 37 +++--
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 ++--
...al_memory.txt => transactional_memory.rst} | 45 ++---
MAINTAINERS | 6 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
26 files changed, 584 insertions(+), 427 deletions(-)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
create mode 100644 Documentation/powerpc/ptrace.rst
delete mode 100644 Documentation/powerpc/ptrace.txt
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..acc21ecca322 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
.. note::
Implementation details for the powerpc platform are discussed in
- the file Documentation/powerpc/eeh-pci-error-recovery.txt
+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
@@ -422,3 +422,24 @@ That is, the recovery API only requires that:
- drivers/net/cxgb3
- drivers/net/s2io.c
- drivers/net/qlge
+
+>>> As of this writing, there is a growing list of device drivers with
+>>> patches implementing error recovery. Not all of these patches are in
+>>> mainline yet. These may be used as "examples":
+>>>
+>>> drivers/scsi/ipr
+>>> drivers/scsi/sym53c8xx_2
+>>> drivers/scsi/qla2xxx
+>>> drivers/scsi/lpfc
+>>> drivers/next/bnx2.c
+>>> drivers/next/e100.c
+>>> drivers/net/e1000
+>>> drivers/net/e1000e
+>>> drivers/net/ixgb
+>>> drivers/net/ixgbe
+>>> drivers/net/cxgb3
+>>> drivers/net/s2io.c
+>>> drivers/net/qlge
+
+The End
+-------
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+ - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -28,7 +32,7 @@ Introduction
responsible for the initialization of the adapter, setting up the
special path for user space access, and performing error recovery. It
communicates directly the Flash Accelerator Functional Unit (AFU)
- as described in Documentation/powerpc/cxl.txt.
+ as described in Documentation/powerpc/cxl.rst.
The cxlflash driver supports two, mutually exclusive, modes of
operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
if it points to cache inhibited (CI) memory. Currently Linux has no way to
disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
writing the DAWR.
To double check the DAWR is working, run this kernel selftest:
+
tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 0c41d6d463f3..d7fa7c35dd12 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..1ff17268db46
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+:orphan:
+
+=======
+powerpc
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ bootwrapper
+ cpu_families
+ cpu_features
+ cxl
+ cxlflash
+ dawr-power9
+ dscr
+ eeh-pci-error-recovery
+ firmware-assisted-dump
+ hvcs
+ isa-versions
+ mpc52xx
+ pci_iov_resource_on_powernv
+ pmu-ebb
+ ptrace
+ qe_firmware
+ syscall64-abi
+ transactional_memory
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -60,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -73,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.rst b/Documentation/powerpc/ptrace.rst
new file mode 100644
index 000000000000..864d4b6dddd1
--- /dev/null
+++ b/Documentation/powerpc/ptrace.rst
@@ -0,0 +1,156 @@
+======
+Ptrace
+======
+
+GDB intends to support the following hardware debug features of BookE
+processors:
+
+4 hardware breakpoints (IAC)
+2 hardware watchpoints (read, write and read-write) (DAC)
+2 value conditions for the hardware watchpoints (DVC)
+
+For that, we need to extend ptrace so that GDB can query and set these
+resources. Since we're extending, we're trying to create an interface
+that's extendable and that covers both BookE and server processors, so
+that GDB doesn't need to special-case each of them. We added the
+following 3 new ptrace requests.
+
+1. PTRACE_PPC_GETHWDEBUGINFO
+============================
+
+Query for GDB to discover the hardware debug features. The main info to
+be returned here is the minimum alignment for the hardware watchpoints.
+BookE processors don't have restrictions here, but server processors have
+an 8-byte alignment restriction for hardware watchpoints. We'd like to avoid
+adding special cases to GDB based on what it sees in AUXV.
+
+Since we're at it, we added other useful info that the kernel can return to
+GDB: this query will return the number of hardware breakpoints, hardware
+watchpoints and whether it supports a range of addresses and a condition.
+The query will fill the following structure provided by the requesting process::
+
+ struct ppc_debug_info {
+ unit32_t version;
+ unit32_t num_instruction_bps;
+ unit32_t num_data_bps;
+ unit32_t num_condition_regs;
+ unit32_t data_bp_alignment;
+ unit32_t sizeof_condition; /* size of the DVC register */
+ uint64_t features; /* bitmask of the individual flags */
+ };
+
+features will have bits indicating whether there is support for::
+
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+
+2. PTRACE_SETHWDEBUG
+
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
+
+ struct ppc_hw_breakpoint {
+ uint32_t version;
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ uint32_t trigger_type; /* only some combinations allowed */
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
+ uint32_t addr_mode; /* address match mode */
+
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ uint32_t condition_mode; /* break/watchpoint condition flags */
+
+ uint64_t addr;
+ uint64_t addr2;
+ uint64_t condition_value;
+ };
+
+A request specifies one event, not necessarily just one register to be set.
+For instance, if the request is for a watchpoint with a condition, both the
+DAC and DVC registers will be set in the same request.
+
+With this GDB can ask for all kinds of hardware breakpoints and watchpoints
+that the BookE supports. COMEFROM breakpoints available in server processors
+are not contemplated, but that is out of the scope of this work.
+
+ptrace will return an integer (handle) uniquely identifying the breakpoint or
+watchpoint just created. This integer will be used in the PTRACE_DELHWDEBUG
+request to ask for its removal. Return -ENOSPC if the requested breakpoint
+can't be allocated on the registers.
+
+Some examples of using the structure to:
+
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+3. PTRACE_DELHWDEBUG
+
+Takes an integer which identifies an existing breakpoint or watchpoint
+(i.e., the value returned from PTRACE_SETHWDEBUG), and deletes the
+corresponding breakpoint or watchpoint..
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.txt
deleted file mode 100644
index 99c5ce88d0fe..000000000000
--- a/Documentation/powerpc/ptrace.txt
+++ /dev/null
@@ -1,151 +0,0 @@
-GDB intends to support the following hardware debug features of BookE
-processors:
-
-4 hardware breakpoints (IAC)
-2 hardware watchpoints (read, write and read-write) (DAC)
-2 value conditions for the hardware watchpoints (DVC)
-
-For that, we need to extend ptrace so that GDB can query and set these
-resources. Since we're extending, we're trying to create an interface
-that's extendable and that covers both BookE and server processors, so
-that GDB doesn't need to special-case each of them. We added the
-following 3 new ptrace requests.
-
-1. PTRACE_PPC_GETHWDEBUGINFO
-
-Query for GDB to discover the hardware debug features. The main info to
-be returned here is the minimum alignment for the hardware watchpoints.
-BookE processors don't have restrictions here, but server processors have
-an 8-byte alignment restriction for hardware watchpoints. We'd like to avoid
-adding special cases to GDB based on what it sees in AUXV.
-
-Since we're at it, we added other useful info that the kernel can return to
-GDB: this query will return the number of hardware breakpoints, hardware
-watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
-
-struct ppc_debug_info {
- unit32_t version;
- unit32_t num_instruction_bps;
- unit32_t num_data_bps;
- unit32_t num_condition_regs;
- unit32_t data_bp_alignment;
- unit32_t sizeof_condition; /* size of the DVC register */
- uint64_t features; /* bitmask of the individual flags */
-};
-
-features will have bits indicating whether there is support for:
-
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
-
-2. PTRACE_SETHWDEBUG
-
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
-
-struct ppc_hw_breakpoint {
- uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
- uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
- uint32_t addr_mode; /* address match mode */
-
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
- uint32_t condition_mode; /* break/watchpoint condition flags */
-
- uint64_t addr;
- uint64_t addr2;
- uint64_t condition_value;
-};
-
-A request specifies one event, not necessarily just one register to be set.
-For instance, if the request is for a watchpoint with a condition, both the
-DAC and DVC registers will be set in the same request.
-
-With this GDB can ask for all kinds of hardware breakpoints and watchpoints
-that the BookE supports. COMEFROM breakpoints available in server processors
-are not contemplated, but that is out of the scope of this work.
-
-ptrace will return an integer (handle) uniquely identifying the breakpoint or
-watchpoint just created. This integer will be used in the PTRACE_DELHWDEBUG
-request to ask for its removal. Return -ENOSPC if the requested breakpoint
-can't be allocated on the registers.
-
-Some examples of using the structure to:
-
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-3. PTRACE_DELHWDEBUG
-
-Takes an integer which identifies an existing breakpoint or watchpoint
-(i.e., the value returned from PTRACE_SETHWDEBUG), and deletes the
-corresponding breakpoint or watchpoint..
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 9458cdaa5b4b..bad1bbb668bc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4416,7 +4416,7 @@ F: arch/powerpc/platforms/powernv/pci-cxl.c
F: drivers/misc/cxl/
F: include/misc/cxl*
F: include/uapi/misc/cxl.h
-F: Documentation/powerpc/cxl.txt
+F: Documentation/powerpc/cxl.rst
F: Documentation/ABI/testing/sysfs-class-cxl
CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4427,7 +4427,7 @@ L: linux-scsi@vger.kernel.org
S: Supported
F: drivers/scsi/cxlflash/
F: include/uapi/scsi/cxlflash_ioctl.h
-F: Documentation/powerpc/cxlflash.txt
+F: Documentation/powerpc/cxlflash.rst
CYBERPRO FB DRIVER
M: Russell King <linux@armlinux.org.uk>
@@ -12276,7 +12276,7 @@ F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
-F: Documentation/powerpc/eeh-pci-error-recovery.txt
+F: Documentation/powerpc/eeh-pci-error-recovery.rst
F: arch/powerpc/kernel/eeh*.c
F: arch/powerpc/platforms/*/eeh*.c
F: arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index 4d4fd2ad5b7d..d6f48fc845ca 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -910,7 +910,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
*
* Call convention:
*
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
*
* For hypercalls, the register convention is as follows:
* r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index ba38c4bb2a88..417df7e19281 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -430,7 +430,7 @@ static void qe_upload_microcode(const void *base,
/*
* Upload a microcode to the I-RAM at a specific address.
*
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
* uploading.
*
* Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
* using the 2.6 Linux kernel kref construct.
*
* For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
*/
#include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
/* Structure that defines QE firmware binary files.
*
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
* fields.
*/
struct qe_firmware {
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 06/43] docs: connector: convert to ReST and rename to connector.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (4 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 05/43] docs: powerpc: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 07/43] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (36 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Evgeniy Polyakov
As it has some function definitions, move them to connector.h.
The remaining 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>
---
.../{connector.txt => connector.rst} | 130 ++++++------------
drivers/w1/Kconfig | 2 +-
include/linux/connector.h | 63 ++++++++-
samples/Kconfig | 2 +-
4 files changed, 109 insertions(+), 88 deletions(-)
rename Documentation/connector/{connector.txt => connector.rst} (57%)
diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.rst
similarity index 57%
rename from Documentation/connector/connector.txt
rename to Documentation/connector/connector.rst
index ab7ca897fab7..24e26dc22dbf 100644
--- a/Documentation/connector/connector.txt
+++ b/Documentation/connector/connector.rst
@@ -1,6 +1,8 @@
-/*****************************************/
-Kernel Connector.
-/*****************************************/
+:orphan:
+
+================
+Kernel Connector
+================
Kernel connector - new netlink based userspace <-> kernel space easy
to use communication module.
@@ -12,94 +14,55 @@ identifier, the appropriate callback will be called.
From the userspace point of view it's quite straightforward:
- socket();
- bind();
- send();
- recv();
+ - socket();
+ - bind();
+ - send();
+ - recv();
But if kernelspace wants to use the full power of such connections, the
driver writer must create special sockets, must know about struct sk_buff
handling, etc... The Connector driver allows any kernelspace agents to use
netlink based networking for inter-process communication in a significantly
-easier way:
+easier way::
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
-void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
-void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
+ int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
+ void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
-struct cb_id
-{
+ struct cb_id
+ {
__u32 idx;
__u32 val;
-};
+ };
idx and val are unique identifiers which must be registered in the
-connector.h header for in-kernel usage. void (*callback) (void *) is a
+connector.h header for in-kernel usage. `void (*callback) (void *)` is a
callback function which will be called when a message with above idx.val
is received by the connector core. The argument for that function must
-be dereferenced to struct cn_msg *.
+be dereferenced to `struct cn_msg *`::
-struct cn_msg
-{
+ struct cn_msg
+ {
struct cb_id id;
__u32 seq;
__u32 ack;
- __u32 len; /* Length of the following data */
+ __u32 len; /* Length of the following data */
__u8 data[0];
-};
+ };
-/*****************************************/
-Connector interfaces.
-/*****************************************/
+Connector interfaces
+====================
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ .. kernel-doc:: include/linux/connector.h
- Registers new callback with connector core.
+ Note:
+ When registering new callback user, connector core assigns
+ netlink group to the user which is equal to its id.idx.
- struct cb_id *id - unique connector's user identifier.
- It must be registered in connector.h for legal in-kernel users.
- char *name - connector's callback symbolic name.
- void (*callback) (struct cn..) - connector's callback.
- cn_msg and the sender's credentials
-
-
-void cn_del_callback(struct cb_id *id);
-
- Unregisters new callback with connector core.
-
- struct cb_id *id - unique connector's user identifier.
-
-
-int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask);
-int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask);
-
- Sends message to the specified groups. It can be safely called from
- softirq context, but may silently fail under strong memory pressure.
- If there are no listeners for given group -ESRCH can be returned.
-
- struct cn_msg * - message header(with attached data).
- u16 len - for *_multi multiple cn_msg messages can be sent
- u32 port - destination port.
- If non-zero the message will be sent to the
- given port, which should be set to the
- original sender.
- u32 __group - destination group.
- If port and __group is zero, then appropriate group will
- be searched through all registered connector users,
- and message will be delivered to the group which was
- created for user with the same ID as in msg.
- If __group is not zero, then message will be delivered
- to the specified group.
- int gfp_mask - GFP mask.
-
- Note: When registering new callback user, connector core assigns
- netlink group to the user which is equal to its id.idx.
-
-/*****************************************/
-Protocol description.
-/*****************************************/
+Protocol description
+====================
The current framework offers a transport layer with fixed headers. The
recommended protocol which uses such a header is as following:
@@ -132,9 +95,8 @@ driver (it also registers itself with id={-1, -1}).
As example of this usage can be found in the cn_test.c module which
uses the connector to request notification and to send messages.
-/*****************************************/
-Reliability.
-/*****************************************/
+Reliability
+===========
Netlink itself is not a reliable protocol. That means that messages can
be lost due to memory pressure or process' receiving queue overflowed,
@@ -142,32 +104,31 @@ so caller is warned that it must be prepared. That is why the struct
cn_msg [main connector's message header] contains u32 seq and u32 ack
fields.
-/*****************************************/
-Userspace usage.
-/*****************************************/
+Userspace usage
+===============
2.6.14 has a new netlink socket implementation, which by default does not
allow people to send data to netlink groups other than 1.
So, if you wish to use a netlink socket (for example using connector)
with a different group number, the userspace application must subscribe to
-that group first. It can be achieved by the following pseudocode:
+that group first. It can be achieved by the following pseudocode::
-s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
+ s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
-l_local.nl_family = AF_NETLINK;
-l_local.nl_groups = 12345;
-l_local.nl_pid = 0;
+ l_local.nl_family = AF_NETLINK;
+ l_local.nl_groups = 12345;
+ l_local.nl_pid = 0;
-if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
+ if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
perror("bind");
close(s);
return -1;
-}
+ }
-{
+ {
int on = l_local.nl_groups;
setsockopt(s, 270, 1, &on, sizeof(on));
-}
+ }
Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
option. To drop a multicast subscription, one should call the above socket
@@ -180,16 +141,15 @@ group number 12345, you must increment CN_NETLINK_USERS to that number.
Additional 0xf numbers are allocated to be used by non-in-kernel users.
Due to this limitation, group 0xffffffff does not work now, so one can
-not use add/remove connector's group notifications, but as far as I know,
+not use add/remove connector's group notifications, but as far as I know,
only cn_test.c test module used it.
Some work in netlink area is still being done, so things can be changed in
2.6.15 timeframe, if it will happen, documentation will be updated for that
kernel.
-/*****************************************/
Code samples
-/*****************************************/
+============
Sample code for a connector test module and user space can be found
in samples/connector/. To build this code, enable CONFIG_CONNECTOR
diff --git a/drivers/w1/Kconfig b/drivers/w1/Kconfig
index 03dd57581df7..160053c0baea 100644
--- a/drivers/w1/Kconfig
+++ b/drivers/w1/Kconfig
@@ -19,7 +19,7 @@ config W1_CON
default y
---help---
This allows to communicate with userspace using connector. For more
- information see <file:Documentation/connector/connector.txt>.
+ information see <file:Documentation/connector/connector.rst>.
There are three types of messages between w1 core and userspace:
1. Events. They are generated each time new master or slave device found
either due to automatic or requested search.
diff --git a/include/linux/connector.h b/include/linux/connector.h
index 1d72ef76f24f..6b6c7396a584 100644
--- a/include/linux/connector.h
+++ b/include/linux/connector.h
@@ -55,10 +55,71 @@ struct cn_dev {
struct cn_queue_dev *cbdev;
};
+/**
+ * cn_add_callback() - Registers new callback with connector core.
+ *
+ * @id: unique connector's user identifier.
+ * It must be registered in connector.h for legal
+ * in-kernel users.
+ * @name: connector's callback symbolic name.
+ * @callback: connector's callback.
+ * parameters are %cn_msg and the sender's credentials
+ */
int cn_add_callback(struct cb_id *id, const char *name,
void (*callback)(struct cn_msg *, struct netlink_skb_parms *));
-void cn_del_callback(struct cb_id *);
+/**
+ * cn_del_callback() - Unregisters new callback with connector core.
+ *
+ * @id: unique connector's user identifier.
+ */
+void cn_del_callback(struct cb_id *id);
+
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg: message header(with attached data).
+ * @len: Number of @msg to be sent.
+ * @portid: destination port.
+ * If non-zero the message will be sent to the given port,
+ * which should be set to the original sender.
+ * @group: destination group.
+ * If @portid and @group is zero, then appropriate group will
+ * be searched through all registered connector users, and
+ * message will be delivered to the group which was created
+ * for user with the same ID as in @msg.
+ * If @group is not zero, then message will be delivered
+ * to the specified group.
+ * @gfp_mask: GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask);
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg: message header(with attached data).
+ * @portid: destination port.
+ * If non-zero the message will be sent to the given port,
+ * which should be set to the original sender.
+ * @group: destination group.
+ * If @portid and @group is zero, then appropriate group will
+ * be searched through all registered connector users, and
+ * message will be delivered to the group which was created
+ * for user with the same ID as in @msg.
+ * If @group is not zero, then message will be delivered
+ * to the specified group.
+ * @gfp_mask: GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 group, gfp_t gfp_mask);
int cn_queue_add_callback(struct cn_queue_dev *dev, const char *name,
diff --git a/samples/Kconfig b/samples/Kconfig
index 71b5e833dd9e..155da47dc6a4 100644
--- a/samples/Kconfig
+++ b/samples/Kconfig
@@ -99,7 +99,7 @@ config SAMPLE_CONNECTOR
When enabled, this builds both a sample kernel module for
the connector interface and a user space tool to communicate
with it.
- See also Documentation/connector/connector.txt
+ See also Documentation/connector/connector.rst
config SAMPLE_HIDRAW
bool "hidraw sample"
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 07/43] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (5 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 06/43] docs: connector: convert to ReST and rename to connector.rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 08/43] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
` (35 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This small text file describes the usage of parallel port LCD
displays from userspace PoV. So, a good candidate for the
admin guide.
While this is not part of the admin-guide book, mark it as
:orphan:, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{lcd-panel-cgram.txt => lcd-panel-cgram.rst} | 9 +++++++--
MAINTAINERS | 2 +-
2 files changed, 8 insertions(+), 3 deletions(-)
rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%)
diff --git a/Documentation/auxdisplay/lcd-panel-cgram.txt b/Documentation/auxdisplay/lcd-panel-cgram.rst
similarity index 88%
rename from Documentation/auxdisplay/lcd-panel-cgram.txt
rename to Documentation/auxdisplay/lcd-panel-cgram.rst
index 7f82c905763d..dfef50286018 100644
--- a/Documentation/auxdisplay/lcd-panel-cgram.txt
+++ b/Documentation/auxdisplay/lcd-panel-cgram.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+======================================
+Parallel port LCD/Keypad Panel support
+======================================
+
Some LCDs allow you to define up to 8 characters, mapped to ASCII
characters 0 to 7. The escape code to define a new character is
'\e[LG' followed by one digit from 0 to 7, representing the character
@@ -7,7 +13,7 @@ illuminated pixel with LSB on the right. Lines are numbered from the
top of the character to the bottom. On a 5x7 matrix, only the 5 lower
bits of the 7 first bytes are used for each character. If the string
is incomplete, only complete lines will be redefined. Here are some
-examples :
+examples::
printf "\e[LG0010101050D1F0C04;" => 0 = [enter]
printf "\e[LG1040E1F0000000000;" => 1 = [up]
@@ -21,4 +27,3 @@ examples :
printf "\e[LG00002061E1E060200;" => small speaker
Willy
-
diff --git a/MAINTAINERS b/MAINTAINERS
index bad1bbb668bc..1606f6cac24d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12000,7 +12000,7 @@ PARALLEL LCD/KEYPAD PANEL DRIVER
M: Willy Tarreau <willy@haproxy.com>
M: Ksenija Stanojevic <ksenija.stanojevic@gmail.com>
S: Odd Fixes
-F: Documentation/auxdisplay/lcd-panel-cgram.txt
+F: Documentation/auxdisplay/lcd-panel-cgram.rst
F: drivers/auxdisplay/panel.c
PARALLEL PORT SUBSYSTEM
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 08/43] docs: lp855x-driver.txt: convert to ReST and move to kernel-api
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (6 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 07/43] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 09/43] docs: m68k: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (34 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This small file seems to be an attempt to start documenting
backlight drivers.
It contains descriptions of the controls for the driver
with could sound as an somewhat user-faced description, but
it's main focus is to describe, instead, the data that should
be passed via platform data and some driver-specific stuff.
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>
---
Documentation/backlight/lp855x-driver.rst | 83 +++++++++++++++++++++++
Documentation/backlight/lp855x-driver.txt | 66 ------------------
MAINTAINERS | 2 +-
3 files changed, 84 insertions(+), 67 deletions(-)
create mode 100644 Documentation/backlight/lp855x-driver.rst
delete mode 100644 Documentation/backlight/lp855x-driver.txt
diff --git a/Documentation/backlight/lp855x-driver.rst b/Documentation/backlight/lp855x-driver.rst
new file mode 100644
index 000000000000..62b7ed847a77
--- /dev/null
+++ b/Documentation/backlight/lp855x-driver.rst
@@ -0,0 +1,83 @@
+:orphan:
+
+====================
+Kernel driver lp855x
+====================
+
+Backlight driver for LP855x ICs
+
+Supported chips:
+
+ Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
+ LP8557
+
+Author: Milo(Woogyom) Kim <milo.kim@ti.com>
+
+Description
+-----------
+
+* Brightness control
+
+ Brightness can be controlled by the pwm input or the i2c command.
+ The lp855x driver supports both cases.
+
+* Device attributes
+
+ 1) bl_ctl_mode
+
+ Backlight control mode.
+
+ Value: pwm based or register based
+
+ 2) chip_id
+
+ The lp855x chip id.
+
+ Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
+
+Platform data for lp855x
+------------------------
+
+For supporting platform specific data, the lp855x platform data can be used.
+
+* name:
+ Backlight driver name. If it is not defined, default name is set.
+* device_control:
+ Value of DEVICE CONTROL register.
+* initial_brightness:
+ Initial value of backlight brightness.
+* period_ns:
+ Platform specific PWM period value. unit is nano.
+ Only valid when brightness is pwm input mode.
+* size_program:
+ Total size of lp855x_rom_data.
+* rom_data:
+ List of new eeprom/eprom registers.
+
+Examples
+========
+
+1) lp8552 platform data: i2c register mode with new eeprom data::
+
+ #define EEPROM_A5_ADDR 0xA5
+ #define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */
+
+ static struct lp855x_rom_data lp8552_eeprom_arr[] = {
+ {EEPROM_A5_ADDR, EEPROM_A5_VAL},
+ };
+
+ static struct lp855x_platform_data lp8552_pdata = {
+ .name = "lcd-bl",
+ .device_control = I2C_CONFIG(LP8552),
+ .initial_brightness = INITIAL_BRT,
+ .size_program = ARRAY_SIZE(lp8552_eeprom_arr),
+ .rom_data = lp8552_eeprom_arr,
+ };
+
+2) lp8556 platform data: pwm input mode with default rom data::
+
+ static struct lp855x_platform_data lp8556_pdata = {
+ .device_control = PWM_CONFIG(LP8556),
+ .initial_brightness = INITIAL_BRT,
+ .period_ns = 1000000,
+ };
diff --git a/Documentation/backlight/lp855x-driver.txt b/Documentation/backlight/lp855x-driver.txt
deleted file mode 100644
index 01bce243d3d7..000000000000
--- a/Documentation/backlight/lp855x-driver.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-Kernel driver lp855x
-====================
-
-Backlight driver for LP855x ICs
-
-Supported chips:
- Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
- LP8557
-
-Author: Milo(Woogyom) Kim <milo.kim@ti.com>
-
-Description
------------
-
-* Brightness control
-
-Brightness can be controlled by the pwm input or the i2c command.
-The lp855x driver supports both cases.
-
-* Device attributes
-
-1) bl_ctl_mode
-Backlight control mode.
-Value : pwm based or register based
-
-2) chip_id
-The lp855x chip id.
-Value : lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
-
-Platform data for lp855x
-------------------------
-
-For supporting platform specific data, the lp855x platform data can be used.
-
-* name : Backlight driver name. If it is not defined, default name is set.
-* device_control : Value of DEVICE CONTROL register.
-* initial_brightness : Initial value of backlight brightness.
-* period_ns : Platform specific PWM period value. unit is nano.
- Only valid when brightness is pwm input mode.
-* size_program : Total size of lp855x_rom_data.
-* rom_data : List of new eeprom/eprom registers.
-
-example 1) lp8552 platform data : i2c register mode with new eeprom data
-
-#define EEPROM_A5_ADDR 0xA5
-#define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */
-
-static struct lp855x_rom_data lp8552_eeprom_arr[] = {
- {EEPROM_A5_ADDR, EEPROM_A5_VAL},
-};
-
-static struct lp855x_platform_data lp8552_pdata = {
- .name = "lcd-bl",
- .device_control = I2C_CONFIG(LP8552),
- .initial_brightness = INITIAL_BRT,
- .size_program = ARRAY_SIZE(lp8552_eeprom_arr),
- .rom_data = lp8552_eeprom_arr,
-};
-
-example 2) lp8556 platform data : pwm input mode with default rom data
-
-static struct lp855x_platform_data lp8556_pdata = {
- .device_control = PWM_CONFIG(LP8556),
- .initial_brightness = INITIAL_BRT,
- .period_ns = 1000000,
-};
diff --git a/MAINTAINERS b/MAINTAINERS
index 1606f6cac24d..e909436a2fa3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15906,7 +15906,7 @@ F: sound/soc/codecs/isabelle*
TI LP855x BACKLIGHT DRIVER
M: Milo Kim <milo.kim@ti.com>
S: Maintained
-F: Documentation/backlight/lp855x-driver.txt
+F: Documentation/backlight/lp855x-driver.rst
F: drivers/video/backlight/lp855x_bl.c
F: include/linux/platform_data/lp855x.h
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 09/43] docs: m68k: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (7 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 08/43] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 10/43] docs: cma/debugfs.txt: " Mauro Carvalho Chehab
` (33 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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 [flat|nested] 54+ messages in thread
* [PATCH 10/43] docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (8 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 09/43] docs: m68k: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 11/43] docs: console.txt: " Mauro Carvalho Chehab
` (32 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The debugfs interface for CMA should be there together with other
mm-related documents.
Convert this small file to ReST and move it to its rightful place.
The conversion is actually quite simple: just add a title for the
document. In order to make it to look better for the audience,
also mark the "echo" command as a literal block.
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/cma/{debugfs.txt => debugfs.rst} | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%)
diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.rst
similarity index 91%
rename from Documentation/cma/debugfs.txt
rename to Documentation/cma/debugfs.rst
index 6cef20a8cedc..518fe401b5ee 100644
--- a/Documentation/cma/debugfs.txt
+++ b/Documentation/cma/debugfs.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+=====================
+CMA Debugfs Interface
+=====================
+
The CMA debugfs interface is useful to retrieve basic information out of the
different CMA areas and to test allocation/release in each of the areas.
@@ -12,7 +18,7 @@ The structure of the files created under that directory is as follows:
- [RO] count: Amount of memory in the CMA area.
- [RO] order_per_bit: Order of pages represented by one bit.
- [RO] bitmap: The bitmap of page states in the zone.
- - [WO] alloc: Allocate N pages from that CMA area. For example:
+ - [WO] alloc: Allocate N pages from that CMA area. For example::
echo 5 > <debugfs>/cma/cma-2/alloc
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 11/43] docs: console.txt: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (9 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 10/43] docs: cma/debugfs.txt: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:53 ` Bartlomiej Zolnierkiewicz
2019-06-28 12:20 ` [PATCH 12/43] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Mauro Carvalho Chehab
` (31 subsequent siblings)
42 siblings, 1 reply; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 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
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>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.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 1da65b9000de..26bc5cdaabab 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 [flat|nested] 54+ messages in thread
* [PATCH 12/43] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (10 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 11/43] docs: console.txt: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 13/43] docs: early-userspace: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (30 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Convert this small file to ReST format and rename it.
Most of the conversion were related to adjusting whitespaces
in order for each section to be properly parsed.
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/pti/pti_intel_mid.rst | 106 ++++++++++++++++++++++++++++
Documentation/pti/pti_intel_mid.txt | 99 --------------------------
2 files changed, 106 insertions(+), 99 deletions(-)
create mode 100644 Documentation/pti/pti_intel_mid.rst
delete mode 100644 Documentation/pti/pti_intel_mid.txt
diff --git a/Documentation/pti/pti_intel_mid.rst b/Documentation/pti/pti_intel_mid.rst
new file mode 100644
index 000000000000..ea05725174cb
--- /dev/null
+++ b/Documentation/pti/pti_intel_mid.rst
@@ -0,0 +1,106 @@
+:orphan:
+
+=============
+Intel MID PTI
+=============
+
+The Intel MID PTI project is HW implemented in Intel Atom
+system-on-a-chip designs based on the Parallel Trace
+Interface for MIPI P1149.7 cJTAG standard. The kernel solution
+for this platform involves the following files::
+
+ ./include/linux/pti.h
+ ./drivers/.../n_tracesink.h
+ ./drivers/.../n_tracerouter.c
+ ./drivers/.../n_tracesink.c
+ ./drivers/.../pti.c
+
+pti.c is the driver that enables various debugging features
+popular on platforms from certain mobile manufacturers.
+n_tracerouter.c and n_tracesink.c allow extra system information to
+be collected and routed to the pti driver, such as trace
+debugging data from a modem. Although n_tracerouter
+and n_tracesink are a part of the complete PTI solution,
+these two line disciplines can work separately from
+pti.c and route any data stream from one /dev/tty node
+to another /dev/tty node via kernel-space. This provides
+a stable, reliable connection that will not break unless
+the user-space application shuts down (plus avoids
+kernel->user->kernel context switch overheads of routing
+data).
+
+An example debugging usage for this driver system:
+
+ * Hook /dev/ttyPTI0 to syslogd. Opening this port will also start
+ a console device to further capture debugging messages to PTI.
+ * Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
+ This is where n_tracerouter and n_tracesink are used.
+ * Hook /dev/pti to a user-level debugging application for writing
+ to PTI HW.
+ * `Use mipi_` Kernel Driver API in other device drivers for
+ debugging to PTI by first requesting a PTI write address via
+ mipi_request_masterchannel(1).
+
+Below is example pseudo-code on how a 'privileged' application
+can hook up n_tracerouter and n_tracesink to any tty on
+a system. 'Privileged' means the application has enough
+privileges to successfully manipulate the ldisc drivers
+but is not just blindly executing as 'root'. Keep in mind
+the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
+and n_tracesink line discpline drivers but is a generic
+operation for a program to use a line discpline driver
+on a tty port other than the default n_tty::
+
+ /////////// To hook up n_tracerouter and n_tracesink /////////
+
+ // Note that n_tracerouter depends on n_tracesink.
+ #include <errno.h>
+ #define ONE_TTY "/dev/ttyOne"
+ #define TWO_TTY "/dev/ttyTwo"
+
+ // needed global to hand onto ldisc connection
+ static int g_fd_source = -1;
+ static int g_fd_sink = -1;
+
+ // these two vars used to grab LDISC values from loaded ldisc drivers
+ // in OS. Look at /proc/tty/ldiscs to get the right numbers from
+ // the ldiscs loaded in the system.
+ int source_ldisc_num, sink_ldisc_num = -1;
+ int retval;
+
+ g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
+ g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W
+
+ if (g_fd_source <= 0) || (g_fd_sink <= 0) {
+ // doubt you'll want to use these exact error lines of code
+ printf("Error on open(). errno: %d\n",errno);
+ return errno;
+ }
+
+ retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
+ if (retval < 0) {
+ printf("Error on ioctl(). errno: %d\n", errno);
+ return errno;
+ }
+
+ retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
+ if (retval < 0) {
+ printf("Error on ioctl(). errno: %d\n", errno);
+ return errno;
+ }
+
+ /////////// To disconnect n_tracerouter and n_tracesink ////////
+
+ // First make sure data through the ldiscs has stopped.
+
+ // Second, disconnect ldiscs. This provides a
+ // little cleaner shutdown on tty stack.
+ sink_ldisc_num = 0;
+ source_ldisc_num = 0;
+ ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
+ ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
+
+ // Three, program closes connection, and cleanup:
+ close(g_fd_uart);
+ close(g_fd_gadget);
+ g_fd_uart = g_fd_gadget = NULL;
diff --git a/Documentation/pti/pti_intel_mid.txt b/Documentation/pti/pti_intel_mid.txt
deleted file mode 100644
index e7a5b6d1f7a9..000000000000
--- a/Documentation/pti/pti_intel_mid.txt
+++ /dev/null
@@ -1,99 +0,0 @@
-The Intel MID PTI project is HW implemented in Intel Atom
-system-on-a-chip designs based on the Parallel Trace
-Interface for MIPI P1149.7 cJTAG standard. The kernel solution
-for this platform involves the following files:
-
-./include/linux/pti.h
-./drivers/.../n_tracesink.h
-./drivers/.../n_tracerouter.c
-./drivers/.../n_tracesink.c
-./drivers/.../pti.c
-
-pti.c is the driver that enables various debugging features
-popular on platforms from certain mobile manufacturers.
-n_tracerouter.c and n_tracesink.c allow extra system information to
-be collected and routed to the pti driver, such as trace
-debugging data from a modem. Although n_tracerouter
-and n_tracesink are a part of the complete PTI solution,
-these two line disciplines can work separately from
-pti.c and route any data stream from one /dev/tty node
-to another /dev/tty node via kernel-space. This provides
-a stable, reliable connection that will not break unless
-the user-space application shuts down (plus avoids
-kernel->user->kernel context switch overheads of routing
-data).
-
-An example debugging usage for this driver system:
- *Hook /dev/ttyPTI0 to syslogd. Opening this port will also start
- a console device to further capture debugging messages to PTI.
- *Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
- This is where n_tracerouter and n_tracesink are used.
- *Hook /dev/pti to a user-level debugging application for writing
- to PTI HW.
- *Use mipi_* Kernel Driver API in other device drivers for
- debugging to PTI by first requesting a PTI write address via
- mipi_request_masterchannel(1).
-
-Below is example pseudo-code on how a 'privileged' application
-can hook up n_tracerouter and n_tracesink to any tty on
-a system. 'Privileged' means the application has enough
-privileges to successfully manipulate the ldisc drivers
-but is not just blindly executing as 'root'. Keep in mind
-the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
-and n_tracesink line discpline drivers but is a generic
-operation for a program to use a line discpline driver
-on a tty port other than the default n_tty.
-
-/////////// To hook up n_tracerouter and n_tracesink /////////
-
-// Note that n_tracerouter depends on n_tracesink.
-#include <errno.h>
-#define ONE_TTY "/dev/ttyOne"
-#define TWO_TTY "/dev/ttyTwo"
-
-// needed global to hand onto ldisc connection
-static int g_fd_source = -1;
-static int g_fd_sink = -1;
-
-// these two vars used to grab LDISC values from loaded ldisc drivers
-// in OS. Look at /proc/tty/ldiscs to get the right numbers from
-// the ldiscs loaded in the system.
-int source_ldisc_num, sink_ldisc_num = -1;
-int retval;
-
-g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
-g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W
-
-if (g_fd_source <= 0) || (g_fd_sink <= 0) {
- // doubt you'll want to use these exact error lines of code
- printf("Error on open(). errno: %d\n",errno);
- return errno;
-}
-
-retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
-if (retval < 0) {
- printf("Error on ioctl(). errno: %d\n", errno);
- return errno;
-}
-
-retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
-if (retval < 0) {
- printf("Error on ioctl(). errno: %d\n", errno);
- return errno;
-}
-
-/////////// To disconnect n_tracerouter and n_tracesink ////////
-
-// First make sure data through the ldiscs has stopped.
-
-// Second, disconnect ldiscs. This provides a
-// little cleaner shutdown on tty stack.
-sink_ldisc_num = 0;
-source_ldisc_num = 0;
-ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
-ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
-
-// Three, program closes connection, and cleanup:
-close(g_fd_uart);
-close(g_fd_gadget);
-g_fd_uart = g_fd_gadget = NULL;
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 13/43] docs: early-userspace: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (11 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 12/43] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 15/43] docs: memory-devices: convert ti-emif.txt to ReST Mauro Carvalho Chehab
` (29 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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 [flat|nested] 54+ messages in thread
* [PATCH 15/43] docs: memory-devices: convert ti-emif.txt to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (12 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 13/43] docs: early-userspace: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 16/43] docs: xen-tpmfront.txt: convert it to .rst Mauro Carvalho Chehab
` (28 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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 [flat|nested] 54+ messages in thread
* [PATCH 16/43] docs: xen-tpmfront.txt: convert it to .rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (13 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 15/43] docs: memory-devices: convert ti-emif.txt to ReST Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 17/43] docs: bus-devices: ti-gpmc.rst: convert it to ReST Mauro Carvalho Chehab
` (27 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In order to be able to add this file to the security book,
we need first to convert it to reST.
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>
---
.../{xen-tpmfront.txt => xen-tpmfront.rst} | 103 ++++++++++--------
1 file changed, 58 insertions(+), 45 deletions(-)
rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)
diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.rst
similarity index 66%
rename from Documentation/security/tpm/xen-tpmfront.txt
rename to Documentation/security/tpm/xen-tpmfront.rst
index 69346de87ff3..98a16ab87360 100644
--- a/Documentation/security/tpm/xen-tpmfront.txt
+++ b/Documentation/security/tpm/xen-tpmfront.rst
@@ -1,4 +1,8 @@
+:orphan:
+
+=============================
Virtual TPM interface for Xen
+=============================
Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
@@ -6,7 +10,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for
Xen. The reader is assumed to have familiarity with building and installing Xen,
Linux, and a basic understanding of the TPM and vTPM concepts.
-INTRODUCTION
+Introduction
+------------
The goal of this work is to provide a TPM functionality to a virtual guest
operating system (in Xen terms, a DomU). This allows programs to interact with
@@ -24,81 +29,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by
IBM and Intel corporation.
-DESIGN OVERVIEW
+Design Overview
---------------
-The architecture of vTPM is described below:
+The architecture of vTPM is described below::
-+------------------+
-| Linux DomU | ...
-| | ^ |
-| v | |
-| xen-tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpm-stubdom | ...
-| | ^ |
-| v | |
-| mini-os/tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpmmgr-stubdom |
-| | ^ |
-| v | |
-| mini-os/tpm_tis |
-+------------------+
- | ^
- v |
-+------------------+
-| Hardware TPM |
-+------------------+
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM |
+ +------------------+
- * Linux DomU: The Linux based guest that wants to use a vTPM. There may be
+* Linux DomU:
+ The Linux based guest that wants to use a vTPM. There may be
more than one of these.
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
+* xen-tpmfront.ko:
+ Linux kernel virtual TPM frontend driver. This driver
provides vTPM access to a Linux-based DomU.
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
+* mini-os/tpmback:
+ Mini-os TPM backend driver. The Linux frontend driver
connects to this backend driver to facilitate communications
between the Linux DomU and its vTPM. This driver is also
used by vtpmmgr-stubdom to communicate with vtpm-stubdom.
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
+* vtpm-stubdom:
+ A mini-os stub domain that implements a vTPM. There is a
one to one mapping between running vtpm-stubdom instances and
logical vtpms on the system. The vTPM Platform Configuration
Registers (PCRs) are normally all initialized to zero.
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
+* mini-os/tpmfront:
+ Mini-os TPM frontend driver. The vTPM mini-os domain
vtpm-stubdom uses this driver to communicate with
vtpmmgr-stubdom. This driver is also used in mini-os
domains such as pv-grub that talk to the vTPM domain.
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is
+* vtpmmgr-stubdom:
+ A mini-os domain that implements the vTPM manager. There is
only one vTPM manager and it should be running during the
entire lifetime of the machine. This domain regulates
access to the physical TPM on the system and secures the
persistent state of each vTPM.
- * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+* mini-os/tpm_tis:
+ Mini-os TPM version 1.2 TPM Interface Specification (TIS)
driver. This driver used by vtpmmgr-stubdom to talk directly to
the hardware TPM. Communication is facilitated by mapping
hardware memory pages into vtpmmgr-stubdom.
- * Hardware TPM: The physical TPM that is soldered onto the motherboard.
+* Hardware TPM:
+ The physical TPM that is soldered onto the motherboard.
-INTEGRATION WITH XEN
+Integration With Xen
--------------------
Support for the vTPM driver was added in Xen using the libxl toolstack in Xen
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 17/43] docs: bus-devices: ti-gpmc.rst: convert it to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (14 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 16/43] docs: xen-tpmfront.txt: convert it to .rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 18/43] docs: nvmem: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
` (26 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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 [flat|nested] 54+ messages in thread
* [PATCH 18/43] docs: nvmem: convert docs to ReST and rename to *.rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (15 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 17/43] docs: bus-devices: ti-gpmc.rst: convert it to ReST Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 19/43] docs: phy: convert samsung-usb2.txt to ReST format Mauro Carvalho Chehab
` (25 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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 [flat|nested] 54+ messages in thread
* [PATCH 19/43] docs: phy: convert samsung-usb2.txt to ReST format
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (16 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 18/43] docs: nvmem: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 20/43] docs: rbtree.txt: fix Sphinx build warnings Mauro Carvalho Chehab
` (24 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In order to merge it into a Sphinx book, we need first to
convert to ReST.
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>
---
.../{samsung-usb2.txt => samsung-usb2.rst} | 62 ++++++++++---------
MAINTAINERS | 2 +-
2 files changed, 34 insertions(+), 30 deletions(-)
rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%)
diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.rst
similarity index 77%
rename from Documentation/phy/samsung-usb2.txt
rename to Documentation/phy/samsung-usb2.rst
index ed12d437189d..98b5952fcb97 100644
--- a/Documentation/phy/samsung-usb2.txt
+++ b/Documentation/phy/samsung-usb2.rst
@@ -1,9 +1,11 @@
-.------------------------------------------------------------------------------+
-| Samsung USB 2.0 PHY adaptation layer |
-+-----------------------------------------------------------------------------+'
+:orphan:
-| 1. Description
-+----------------
+====================================
+Samsung USB 2.0 PHY adaptation layer
+====================================
+
+1. Description
+--------------
The architecture of the USB 2.0 PHY module in Samsung SoCs is similar
among many SoCs. In spite of the similarities it proved difficult to
@@ -14,8 +16,8 @@ the PHY powering up process had to be altered. This adaptation layer is
a compromise between having separate drivers and having a single driver
with added support for many special cases.
-| 2. Files description
-+----------------------
+2. Files description
+--------------------
- phy-samsung-usb2.c
This is the main file of the adaptation layer. This file contains
@@ -32,44 +34,45 @@ with added support for many special cases.
driver. In addition it should contain extern declarations for
structures that describe particular SoCs.
-| 3. Supporting SoCs
-+--------------------
+3. Supporting SoCs
+------------------
To support a new SoC a new file should be added to the drivers/phy
directory. Each SoC's configuration is stored in an instance of the
-struct samsung_usb2_phy_config.
+struct samsung_usb2_phy_config::
-struct samsung_usb2_phy_config {
+ struct samsung_usb2_phy_config {
const struct samsung_usb2_common_phy *phys;
int (*rate_to_clk)(unsigned long, u32 *);
unsigned int num_phys;
bool has_mode_switch;
-};
+ };
-The num_phys is the number of phys handled by the driver. *phys is an
+The num_phys is the number of phys handled by the driver. `*phys` is an
array that contains the configuration for each phy. The has_mode_switch
property is a boolean flag that determines whether the SoC has USB host
and device on a single pair of pins. If so, a special register has to
be modified to change the internal routing of these pins between a USB
device or host module.
-For example the configuration for Exynos 4210 is following:
+For example the configuration for Exynos 4210 is following::
-const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
+ const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
.has_mode_switch = 0,
.num_phys = EXYNOS4210_NUM_PHYS,
.phys = exynos4210_phys,
.rate_to_clk = exynos4210_rate_to_clk,
-}
+ }
+
+- `int (*rate_to_clk)(unsigned long, u32 *)`
-- int (*rate_to_clk)(unsigned long, u32 *)
The rate_to_clk callback is to convert the rate of the clock
used as the reference clock for the PHY module to the value
that should be written in the hardware register.
-The exynos4210_phys configuration array is as follows:
+The exynos4210_phys configuration array is as follows::
-static const struct samsung_usb2_common_phy exynos4210_phys[] = {
+ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
{
.label = "device",
.id = EXYNOS4210_DEVICE,
@@ -95,29 +98,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
.power_off = exynos4210_power_off,
},
{},
-};
+ };
+
+- `int (*power_on)(struct samsung_usb2_phy_instance *);`
+ `int (*power_off)(struct samsung_usb2_phy_instance *);`
-- int (*power_on)(struct samsung_usb2_phy_instance *);
-- int (*power_off)(struct samsung_usb2_phy_instance *);
These two callbacks are used to power on and power off the phy
by modifying appropriate registers.
Final change to the driver is adding appropriate compatible value to the
phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were
-added to the struct of_device_id samsung_usb2_phy_of_match[] array:
+added to the struct of_device_id samsung_usb2_phy_of_match[] array::
-#ifdef CONFIG_PHY_EXYNOS4210_USB2
+ #ifdef CONFIG_PHY_EXYNOS4210_USB2
{
.compatible = "samsung,exynos4210-usb2-phy",
.data = &exynos4210_usb2_phy_config,
},
-#endif
+ #endif
To add further flexibility to the driver the Kconfig file enables to
include support for selected SoCs in the compiled driver. The Kconfig
-entry for Exynos 4210 is following:
+entry for Exynos 4210 is following::
-config PHY_EXYNOS4210_USB2
+ config PHY_EXYNOS4210_USB2
bool "Support for Exynos 4210"
depends on PHY_SAMSUNG_USB2
depends on CPU_EXYNOS4210
@@ -128,8 +132,8 @@ config PHY_EXYNOS4210_USB2
phys are available - device, host, HSCI0 and HSCI1.
The newly created file that supports the new SoC has to be also added to the
-Makefile. In case of Exynos 4210 the added line is following:
+Makefile. In case of Exynos 4210 the added line is following::
-obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o
+ obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o
After completing these steps the support for the new SoC should be ready.
diff --git a/MAINTAINERS b/MAINTAINERS
index 04606ea55503..f738b413914e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14031,7 +14031,7 @@ M: Sylwester Nawrocki <s.nawrocki@samsung.com>
L: linux-kernel@vger.kernel.org
S: Supported
F: Documentation/devicetree/bindings/phy/samsung-phy.txt
-F: Documentation/phy/samsung-usb2.txt
+F: Documentation/phy/samsung-usb2.rst
F: drivers/phy/samsung/phy-exynos4210-usb2.c
F: drivers/phy/samsung/phy-exynos4x12-usb2.c
F: drivers/phy/samsung/phy-exynos5250-usb2.c
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 20/43] docs: rbtree.txt: fix Sphinx build warnings
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (17 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 19/43] docs: phy: convert samsung-usb2.txt to ReST format Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 21/43] docs: DMA-API-HOWTO.txt: fix an unmarked code block Mauro Carvalho Chehab
` (23 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Ths file is already at ReST format. Yet, some recent changes
made it to produce a few warnings when building it with
Sphinx.
Those are trivially fixed by marking some literal blocks.
Fix them before adding it to the docs building system.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/rbtree.txt | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt
index c42a21b99046..523d54b60087 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.txt
@@ -204,21 +204,21 @@ potentially expensive tree iterations. This is done at negligible runtime
overhead for maintanence; albeit larger memory footprint.
Similar to the rb_root structure, cached rbtrees are initialized to be
-empty via:
+empty via::
struct rb_root_cached mytree = RB_ROOT_CACHED;
Cached rbtree is simply a regular rb_root with an extra pointer to cache the
leftmost node. This allows rb_root_cached to exist wherever rb_root does,
which permits augmented trees to be supported as well as only a few extra
-interfaces:
+interfaces::
struct rb_node *rb_first_cached(struct rb_root_cached *tree);
void rb_insert_color_cached(struct rb_node *, struct rb_root_cached *, bool);
void rb_erase_cached(struct rb_node *node, struct rb_root_cached *);
Both insert and erase calls have their respective counterpart of augmented
-trees:
+trees::
void rb_insert_augmented_cached(struct rb_node *node, struct rb_root_cached *,
bool, struct rb_augment_callbacks *);
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 21/43] docs: DMA-API-HOWTO.txt: fix an unmarked code block
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (18 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 20/43] docs: rbtree.txt: fix Sphinx build warnings Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 22/43] docs: accounting: convert to ReST Mauro Carvalho Chehab
` (22 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
When building with Sphinx, it would produce this warning:
docs/Documentation/DMA-API-HOWTO.rst:222: WARNING: Definition list ends without a blank line; unexpected unindent.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/DMA-API-HOWTO.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index cb712a02f59f..358d495456d1 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -212,7 +212,7 @@ The standard 64-bit addressing device would do something like this::
If the device only supports 32-bit addressing for descriptors in the
coherent allocations, but supports full 64-bits for streaming mappings
-it would look like this:
+it would look like this::
if (dma_set_mask(dev, DMA_BIT_MASK(64))) {
dev_warn(dev, "mydev: No suitable DMA available\n");
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 22/43] docs: accounting: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (19 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 21/43] docs: DMA-API-HOWTO.txt: fix an unmarked code block Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 23/43] docs: ia64: " Mauro Carvalho Chehab
` (21 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 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
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 e2e51b5f84e8..95ec166e2c2e 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -526,7 +526,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 [flat|nested] 54+ messages in thread
* [PATCH 23/43] docs: ia64: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (20 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 22/43] docs: accounting: convert to ReST Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 24/43] docs: leds: " Mauro Carvalho Chehab
` (20 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 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
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 f738b413914e..f4f24d0e7954 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14331,7 +14331,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 5e3e7b1fdac5..0c0de2c4ec69 100644
--- a/arch/ia64/mm/ioremap.c
+++ b/arch/ia64/mm/ioremap.c
@@ -42,7 +42,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 [flat|nested] 54+ messages in thread
* [PATCH 24/43] docs: leds: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (21 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 23/43] docs: ia64: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 19:01 ` Jacek Anaszewski
2019-06-28 12:20 ` [PATCH 25/43] docs: laptops: " Mauro Carvalho Chehab
` (19 subsequent siblings)
42 siblings, 1 reply; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 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
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>
Acked-by: Pavel Machek <pavel@ucw.cz>
---
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 f4f24d0e7954..cc8a52d2ce83 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10244,7 +10244,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 [flat|nested] 54+ messages in thread
* [PATCH 25/43] docs: laptops: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (22 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 24/43] docs: leds: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 26/43] docs: namespaces: " Mauro Carvalho Chehab
` (18 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Arnd Bergmann, Greg Kroah-Hartman, Darren Hart,
Andy Shevchenko, platform-driver-x86, Andy Shevchenko
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>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
---
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 e5eb04f673ae..92d335837c52 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4373,7 +4373,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 cc8a52d2ce83..8aa3d0bd5b80 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14830,7 +14830,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 c318501773bc..1f616844fb87 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -448,7 +448,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"
@@ -500,7 +500,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 [flat|nested] 54+ messages in thread
* [PATCH 26/43] docs: namespaces: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (23 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 25/43] docs: laptops: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 27/43] docs: nfc: " Mauro Carvalho Chehab
` (17 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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 [flat|nested] 54+ messages in thread
* [PATCH 27/43] docs: nfc: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (24 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 26/43] docs: namespaces: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 28/43] docs: md: " Mauro Carvalho Chehab
` (16 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
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 [flat|nested] 54+ messages in thread
* [PATCH 28/43] docs: md: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (25 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 27/43] docs: nfc: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 29/43] docs: mtd: " Mauro Carvalho Chehab
` (15 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Rename the md 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/md/index.rst | 12 ++
.../md/{md-cluster.txt => md-cluster.rst} | 188 ++++++++++++------
.../md/{raid5-cache.txt => raid5-cache.rst} | 28 +--
.../md/{raid5-ppl.txt => raid5-ppl.rst} | 2 +
4 files changed, 153 insertions(+), 77 deletions(-)
create mode 100644 Documentation/md/index.rst
rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)
diff --git a/Documentation/md/index.rst b/Documentation/md/index.rst
new file mode 100644
index 000000000000..c4db34ed327d
--- /dev/null
+++ b/Documentation/md/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+====
+RAID
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ md-cluster
+ raid5-cache
+ raid5-ppl
diff --git a/Documentation/md/md-cluster.txt b/Documentation/md/md-cluster.rst
similarity index 68%
rename from Documentation/md/md-cluster.txt
rename to Documentation/md/md-cluster.rst
index e1055f105cf5..96eb52cec7eb 100644
--- a/Documentation/md/md-cluster.txt
+++ b/Documentation/md/md-cluster.rst
@@ -1,19 +1,24 @@
+==========
+MD Cluster
+==========
+
The cluster MD is a shared-device RAID for a cluster, it supports
two levels: raid1 and raid10 (limited support).
1. On-disk format
+=================
Separate write-intent-bitmaps are used for each cluster node.
The bitmaps record all writes that may have been started on that node,
-and may not yet have finished. The on-disk layout is:
+and may not yet have finished. The on-disk layout is::
-0 4k 8k 12k
--------------------------------------------------------------------
-| idle | md super | bm super [0] + bits |
-| bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] |
-| bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits |
-| bm bits [3, contd] | | |
+ 0 4k 8k 12k
+ -------------------------------------------------------------------
+ | idle | md super | bm super [0] + bits |
+ | bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] |
+ | bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits |
+ | bm bits [3, contd] | | |
During "normal" functioning we assume the filesystem ensures that only
one node writes to any given block at a time, so a write request will
@@ -28,10 +33,12 @@ node) is writing.
2. DLM Locks for management
+===========================
There are three groups of locks for managing the device:
2.1 Bitmap lock resource (bm_lockres)
+-------------------------------------
The bm_lockres protects individual node bitmaps. They are named in
the form bitmap000 for node 1, bitmap001 for node 2 and so on. When a
@@ -48,6 +55,7 @@ There are three groups of locks for managing the device:
joins the cluster.
2.2 Message passing locks
+-------------------------
Each node has to communicate with other nodes when starting or ending
resync, and for metadata superblock updates. This communication is
@@ -55,116 +63,155 @@ There are three groups of locks for managing the device:
with the Lock Value Block (LVB) of one of the "message" lock.
2.3 new-device management
+-------------------------
A single lock: "no-new-dev" is used to co-ordinate the addition of
new devices - this must be synchronized across the array.
Normally all nodes hold a concurrent-read lock on this device.
3. Communication
+================
Messages can be broadcast to all nodes, and the sender waits for all
other nodes to acknowledge the message before proceeding. Only one
message can be processed at a time.
3.1 Message Types
+-----------------
There are six types of messages which are passed:
- 3.1.1 METADATA_UPDATED: informs other nodes that the metadata has
+3.1.1 METADATA_UPDATED
+^^^^^^^^^^^^^^^^^^^^^^
+
+ informs other nodes that the metadata has
been updated, and the node must re-read the md superblock. This is
performed synchronously. It is primarily used to signal device
failure.
- 3.1.2 RESYNCING: informs other nodes that a resync is initiated or
+3.1.2 RESYNCING
+^^^^^^^^^^^^^^^
+ informs other nodes that a resync is initiated or
ended so that each node may suspend or resume the region. Each
RESYNCING message identifies a range of the devices that the
sending node is about to resync. This overrides any previous
notification from that node: only one ranged can be resynced at a
time per-node.
- 3.1.3 NEWDISK: informs other nodes that a device is being added to
+3.1.3 NEWDISK
+^^^^^^^^^^^^^
+
+ informs other nodes that a device is being added to
the array. Message contains an identifier for that device. See
below for further details.
- 3.1.4 REMOVE: A failed or spare device is being removed from the
+3.1.4 REMOVE
+^^^^^^^^^^^^
+
+ A failed or spare device is being removed from the
array. The slot-number of the device is included in the message.
- 3.1.5 RE_ADD: A failed device is being re-activated - the assumption
+ 3.1.5 RE_ADD:
+
+ A failed device is being re-activated - the assumption
is that it has been determined to be working again.
- 3.1.6 BITMAP_NEEDS_SYNC: if a node is stopped locally but the bitmap
+ 3.1.6 BITMAP_NEEDS_SYNC:
+
+ If a node is stopped locally but the bitmap
isn't clean, then another node is informed to take the ownership of
resync.
3.2 Communication mechanism
+---------------------------
The DLM LVB is used to communicate within nodes of the cluster. There
are three resources used for the purpose:
- 3.2.1 token: The resource which protects the entire communication
+3.2.1 token
+^^^^^^^^^^^
+ The resource which protects the entire communication
system. The node having the token resource is allowed to
communicate.
- 3.2.2 message: The lock resource which carries the data to
- communicate.
+3.2.2 message
+^^^^^^^^^^^^^
+ The lock resource which carries the data to communicate.
- 3.2.3 ack: The resource, acquiring which means the message has been
+3.2.3 ack
+^^^^^^^^^
+
+ The resource, acquiring which means the message has been
acknowledged by all nodes in the cluster. The BAST of the resource
is used to inform the receiving node that a node wants to
communicate.
The algorithm is:
- 1. receive status - all nodes have concurrent-reader lock on "ack".
+ 1. receive status - all nodes have concurrent-reader lock on "ack"::
- sender receiver receiver
- "ack":CR "ack":CR "ack":CR
+ sender receiver receiver
+ "ack":CR "ack":CR "ack":CR
- 2. sender get EX on "token"
- sender get EX on "message"
- sender receiver receiver
- "token":EX "ack":CR "ack":CR
- "message":EX
- "ack":CR
+ 2. sender get EX on "token",
+ sender get EX on "message"::
+
+ sender receiver receiver
+ "token":EX "ack":CR "ack":CR
+ "message":EX
+ "ack":CR
Sender checks that it still needs to send a message. Messages
received or other events that happened while waiting for the
"token" may have made this message inappropriate or redundant.
- 3. sender writes LVB.
+ 3. sender writes LVB
+
sender down-convert "message" from EX to CW
+
sender try to get EX of "ack"
- [ wait until all receivers have *processed* the "message" ]
-
- [ triggered by bast of "ack" ]
- receiver get CR on "message"
- receiver read LVB
- receiver processes the message
- [ wait finish ]
- receiver releases "ack"
- receiver tries to get PR on "message"
-
- sender receiver receiver
- "token":EX "message":CR "message":CR
- "message":CW
- "ack":EX
+
+ ::
+
+ [ wait until all receivers have *processed* the "message" ]
+
+ [ triggered by bast of "ack" ]
+ receiver get CR on "message"
+ receiver read LVB
+ receiver processes the message
+ [ wait finish ]
+ receiver releases "ack"
+ receiver tries to get PR on "message"
+
+ sender receiver receiver
+ "token":EX "message":CR "message":CR
+ "message":CW
+ "ack":EX
4. triggered by grant of EX on "ack" (indicating all receivers
have processed message)
+
sender down-converts "ack" from EX to CR
+
sender releases "message"
+
sender releases "token"
- receiver upconvert to PR on "message"
- receiver get CR of "ack"
- receiver release "message"
- sender receiver receiver
- "ack":CR "ack":CR "ack":CR
+ ::
+
+ receiver upconvert to PR on "message"
+ receiver get CR of "ack"
+ receiver release "message"
+
+ sender receiver receiver
+ "ack":CR "ack":CR "ack":CR
4. Handling Failures
+====================
4.1 Node Failure
+----------------
When a node fails, the DLM informs the cluster with the slot
number. The node starts a cluster recovery thread. The cluster
@@ -177,11 +224,11 @@ The algorithm is:
- cleans the bitmap of the failed node
- releases bitmap<number> lock of the failed node
- initiates resync of the bitmap on the current node
- md_check_recovery is invoked within recover_bitmaps,
- then md_check_recovery -> metadata_update_start/finish,
- it will lock the communication by lock_comm.
- Which means when one node is resyncing it blocks all
- other nodes from writing anywhere on the array.
+ md_check_recovery is invoked within recover_bitmaps,
+ then md_check_recovery -> metadata_update_start/finish,
+ it will lock the communication by lock_comm.
+ Which means when one node is resyncing it blocks all
+ other nodes from writing anywhere on the array.
The resync process is the regular md resync. However, in a clustered
environment when a resync is performed, it needs to tell other nodes
@@ -198,6 +245,7 @@ The algorithm is:
particular I/O range should be suspended or not.
4.2 Device Failure
+==================
Device failures are handled and communicated with the metadata update
routine. When a node detects a device failure it does not allow
@@ -205,38 +253,41 @@ The algorithm is:
acknowledged by all other nodes.
5. Adding a new Device
+----------------------
For adding a new device, it is necessary that all nodes "see" the new
device to be added. For this, the following algorithm is used:
- 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
+ 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CLUSTER_ADD)
- 2. Node 1 sends a NEWDISK message with uuid and slot number
- 3. Other nodes issue kobject_uevent_env with uuid and slot number
+ 2. Node 1 sends a NEWDISK message with uuid and slot number
+ 3. Other nodes issue kobject_uevent_env with uuid and slot number
(Steps 4,5 could be a udev rule)
- 4. In userspace, the node searches for the disk, perhaps
+ 4. In userspace, the node searches for the disk, perhaps
using blkid -t SUB_UUID=""
- 5. Other nodes issue either of the following depending on whether
+ 5. Other nodes issue either of the following depending on whether
the disk was found:
ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CANDIDATE and
- disc.number set to slot number)
+ disc.number set to slot number)
ioctl(CLUSTERED_DISK_NACK)
- 6. Other nodes drop lock on "no-new-devs" (CR) if device is found
- 7. Node 1 attempts EX lock on "no-new-dev"
- 8. If node 1 gets the lock, it sends METADATA_UPDATED after
+ 6. Other nodes drop lock on "no-new-devs" (CR) if device is found
+ 7. Node 1 attempts EX lock on "no-new-dev"
+ 8. If node 1 gets the lock, it sends METADATA_UPDATED after
unmarking the disk as SpareLocal
- 9. If not (get "no-new-dev" lock), it fails the operation and sends
+ 9. If not (get "no-new-dev" lock), it fails the operation and sends
METADATA_UPDATED.
10. Other nodes get the information whether a disk is added or not
by the following METADATA_UPDATED.
-6. Module interface.
+6. Module interface
+===================
There are 17 call-backs which the md core can make to the cluster
module. Understanding these can give a good overview of the whole
process.
6.1 join(nodes) and leave()
+---------------------------
These are called when an array is started with a clustered bitmap,
and when the array is stopped. join() ensures the cluster is
@@ -244,11 +295,13 @@ The algorithm is:
Only the first 'nodes' nodes in the cluster can use the array.
6.2 slot_number()
+-----------------
Reports the slot number advised by the cluster infrastructure.
Range is from 0 to nodes-1.
6.3 resync_info_update()
+------------------------
This updates the resync range that is stored in the bitmap lock.
The starting point is updated as the resync progresses. The
@@ -256,6 +309,7 @@ The algorithm is:
It does *not* send a RESYNCING message.
6.4 resync_start(), resync_finish()
+-----------------------------------
These are called when resync/recovery/reshape starts or stops.
They update the resyncing range in the bitmap lock and also
@@ -265,8 +319,8 @@ The algorithm is:
resync_finish() also sends a BITMAP_NEEDS_SYNC message which
allows some other node to take over.
-6.5 metadata_update_start(), metadata_update_finish(),
- metadata_update_cancel().
+6.5 metadata_update_start(), metadata_update_finish(), metadata_update_cancel()
+-------------------------------------------------------------------------------
metadata_update_start is used to get exclusive access to
the metadata. If a change is still needed once that access is
@@ -275,6 +329,7 @@ The algorithm is:
can be used to release the lock.
6.6 area_resyncing()
+--------------------
This combines two elements of functionality.
@@ -289,6 +344,7 @@ The algorithm is:
a node failure.
6.7 add_new_disk_start(), add_new_disk_finish(), new_disk_ack()
+---------------------------------------------------------------
These are used to manage the new-disk protocol described above.
When a new device is added, add_new_disk_start() is called before
@@ -300,17 +356,20 @@ The algorithm is:
new_disk_ack() is called.
6.8 remove_disk()
+-----------------
This is called when a spare or failed device is removed from
the array. It causes a REMOVE message to be send to other nodes.
6.9 gather_bitmaps()
+--------------------
This sends a RE_ADD message to all other nodes and then
gathers bitmap information from all bitmaps. This combined
bitmap is then used to recovery the re-added device.
6.10 lock_all_bitmaps() and unlock_all_bitmaps()
+------------------------------------------------
These are called when change bitmap to none. If a node plans
to clear the cluster raid's bitmap, it need to make sure no other
@@ -319,6 +378,7 @@ The algorithm is:
accordingly.
7. Unsupported features
+=======================
There are somethings which are not supported by cluster MD yet.
diff --git a/Documentation/md/raid5-cache.txt b/Documentation/md/raid5-cache.rst
similarity index 92%
rename from Documentation/md/raid5-cache.txt
rename to Documentation/md/raid5-cache.rst
index 2b210f295786..d7a15f44a7c3 100644
--- a/Documentation/md/raid5-cache.txt
+++ b/Documentation/md/raid5-cache.rst
@@ -1,4 +1,6 @@
-RAID5 cache
+================
+RAID 4/5/6 cache
+================
Raid 4/5/6 could include an extra disk for data cache besides normal RAID
disks. The role of RAID disks isn't changed with the cache disk. The cache disk
@@ -6,19 +8,19 @@ caches data to the RAID disks. The cache can be in write-through (supported
since 4.4) or write-back mode (supported since 4.10). mdadm (supported since
3.4) has a new option '--write-journal' to create array with cache. Please
refer to mdadm manual for details. By default (RAID array starts), the cache is
-in write-through mode. A user can switch it to write-back mode by:
+in write-through mode. A user can switch it to write-back mode by::
-echo "write-back" > /sys/block/md0/md/journal_mode
+ echo "write-back" > /sys/block/md0/md/journal_mode
-And switch it back to write-through mode by:
+And switch it back to write-through mode by::
-echo "write-through" > /sys/block/md0/md/journal_mode
+ echo "write-through" > /sys/block/md0/md/journal_mode
In both modes, all writes to the array will hit cache disk first. This means
the cache disk must be fast and sustainable.
--------------------------------------
-write-through mode:
+write-through mode
+==================
This mode mainly fixes the 'write hole' issue. For RAID 4/5/6 array, an unclean
shutdown can cause data in some stripes to not be in consistent state, eg, data
@@ -42,8 +44,8 @@ exposed to 'write hole' again.
In write-through mode, the cache disk isn't required to be big. Several
hundreds megabytes are enough.
---------------------------------------
-write-back mode:
+write-back mode
+===============
write-back mode fixes the 'write hole' issue too, since all write data is
cached on cache disk. But the main goal of 'write-back' cache is to speed up
@@ -64,16 +66,16 @@ data loss.
In write-back mode, MD also caches data in memory. The memory cache includes
the same data stored on cache disk, so a power loss doesn't cause data loss.
The memory cache size has performance impact for the array. It's recommended
-the size is big. A user can configure the size by:
+the size is big. A user can configure the size by::
-echo "2048" > /sys/block/md0/md/stripe_cache_size
+ echo "2048" > /sys/block/md0/md/stripe_cache_size
Too small cache disk will make the write aggregation less efficient in this
mode depending on the workloads. It's recommended to use a cache disk with at
least several gigabytes size in write-back mode.
---------------------------------------
-The implementation:
+The implementation
+==================
The write-through and write-back cache use the same disk format. The cache disk
is organized as a simple write log. The log consists of 'meta data' and 'data'
diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/md/raid5-ppl.rst
similarity index 98%
rename from Documentation/md/raid5-ppl.txt
rename to Documentation/md/raid5-ppl.rst
index bfa092589e00..357e5515bc55 100644
--- a/Documentation/md/raid5-ppl.txt
+++ b/Documentation/md/raid5-ppl.rst
@@ -1,4 +1,6 @@
+==================
Partial Parity Log
+==================
Partial Parity Log (PPL) is a feature available for RAID5 arrays. The issue
addressed by PPL is that after a dirty shutdown, parity of a particular stripe
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 29/43] docs: mtd: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (26 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 28/43] docs: md: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 30/43] docs: nvdimm: " Mauro Carvalho Chehab
` (14 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 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
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 [flat|nested] 54+ messages in thread
* [PATCH 30/43] docs: nvdimm: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (27 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 29/43] docs: mtd: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 16:32 ` Dan Williams
2019-06-28 12:20 ` [PATCH 31/43] docs: xtensa: " Mauro Carvalho Chehab
` (13 subsequent siblings)
42 siblings, 1 reply; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 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
Rename the nvdimm 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 [flat|nested] 54+ messages in thread
* [PATCH 31/43] docs: xtensa: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (28 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 30/43] docs: nvdimm: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 32/43] docs: mmc: " Mauro Carvalho Chehab
` (12 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 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
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 [flat|nested] 54+ messages in thread
* [PATCH 32/43] docs: mmc: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (29 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 31/43] docs: xtensa: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 33/43] docs: ioctl-number.txt: convert it to ReST format Mauro Carvalho Chehab
` (11 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Rename the mmc 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/mmc/index.rst | 13 +++++
.../{mmc-async-req.txt => mmc-async-req.rst} | 53 +++++++++++--------
.../{mmc-dev-attrs.txt => mmc-dev-attrs.rst} | 32 +++++++----
.../{mmc-dev-parts.txt => mmc-dev-parts.rst} | 13 ++---
.../mmc/{mmc-tools.txt => mmc-tools.rst} | 5 +-
5 files changed, 79 insertions(+), 37 deletions(-)
create mode 100644 Documentation/mmc/index.rst
rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%)
rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%)
rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%)
rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%)
diff --git a/Documentation/mmc/index.rst b/Documentation/mmc/index.rst
new file mode 100644
index 000000000000..3305478ddadb
--- /dev/null
+++ b/Documentation/mmc/index.rst
@@ -0,0 +1,13 @@
+:orphan:
+
+========================
+MMC/SD/SDIO card support
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ mmc-dev-attrs
+ mmc-dev-parts
+ mmc-async-req
+ mmc-tools
diff --git a/Documentation/mmc/mmc-async-req.txt b/Documentation/mmc/mmc-async-req.rst
similarity index 75%
rename from Documentation/mmc/mmc-async-req.txt
rename to Documentation/mmc/mmc-async-req.rst
index ae1907b10e4a..0f7197c9c3b5 100644
--- a/Documentation/mmc/mmc-async-req.txt
+++ b/Documentation/mmc/mmc-async-req.rst
@@ -1,13 +1,20 @@
+========================
+MMC Asynchronous Request
+========================
+
Rationale
=========
How significant is the cache maintenance overhead?
+
It depends. Fast eMMC and multiple cache levels with speculative cache
pre-fetch makes the cache overhead relatively significant. If the DMA
preparations for the next request are done in parallel with the current
transfer, the DMA preparation overhead would not affect the MMC performance.
+
The intention of non-blocking (asynchronous) MMC requests is to minimize the
time between when an MMC request ends and another MMC request begins.
+
Using mmc_wait_for_req(), the MMC controller is idle while dma_map_sg and
dma_unmap_sg are processing. Using non-blocking MMC requests makes it
possible to prepare the caches for next job in parallel with an active
@@ -17,6 +24,7 @@ MMC block driver
================
The mmc_blk_issue_rw_rq() in the MMC block driver is made non-blocking.
+
The increase in throughput is proportional to the time it takes to
prepare (major part of preparations are dma_map_sg() and dma_unmap_sg())
a request and how fast the memory is. The faster the MMC/SD is the
@@ -35,6 +43,7 @@ MMC core API extension
======================
There is one new public function mmc_start_req().
+
It starts a new MMC command request for a host. The function isn't
truly non-blocking. If there is an ongoing async request it waits
for completion of that request and starts the new one and returns. It
@@ -47,6 +56,7 @@ MMC host extensions
There are two optional members in the mmc_host_ops -- pre_req() and
post_req() -- that the host driver may implement in order to move work
to before and after the actual mmc_host_ops.request() function is called.
+
In the DMA case pre_req() may do dma_map_sg() and prepare the DMA
descriptor, and post_req() runs the dma_unmap_sg().
@@ -55,33 +65,34 @@ Optimize for the first request
The first request in a series of requests can't be prepared in parallel
with the previous transfer, since there is no previous request.
+
The argument is_first_req in pre_req() indicates that there is no previous
request. The host driver may optimize for this scenario to minimize
the performance loss. A way to optimize for this is to split the current
request in two chunks, prepare the first chunk and start the request,
and finally prepare the second chunk and start the transfer.
-Pseudocode to handle is_first_req scenario with minimal prepare overhead:
+Pseudocode to handle is_first_req scenario with minimal prepare overhead::
-if (is_first_req && req->size > threshold)
- /* start MMC transfer for the complete transfer size */
- mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
+ if (is_first_req && req->size > threshold)
+ /* start MMC transfer for the complete transfer size */
+ mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
- /*
- * Begin to prepare DMA while cmd is being processed by MMC.
- * The first chunk of the request should take the same time
- * to prepare as the "MMC process command time".
- * If prepare time exceeds MMC cmd time
- * the transfer is delayed, guesstimate max 4k as first chunk size.
- */
- prepare_1st_chunk_for_dma(req);
- /* flush pending desc to the DMAC (dmaengine.h) */
- dma_issue_pending(req->dma_desc);
+ /*
+ * Begin to prepare DMA while cmd is being processed by MMC.
+ * The first chunk of the request should take the same time
+ * to prepare as the "MMC process command time".
+ * If prepare time exceeds MMC cmd time
+ * the transfer is delayed, guesstimate max 4k as first chunk size.
+ */
+ prepare_1st_chunk_for_dma(req);
+ /* flush pending desc to the DMAC (dmaengine.h) */
+ dma_issue_pending(req->dma_desc);
- prepare_2nd_chunk_for_dma(req);
- /*
- * The second issue_pending should be called before MMC runs out
- * of the first chunk. If the MMC runs out of the first data chunk
- * before this call, the transfer is delayed.
- */
- dma_issue_pending(req->dma_desc);
+ prepare_2nd_chunk_for_dma(req);
+ /*
+ * The second issue_pending should be called before MMC runs out
+ * of the first chunk. If the MMC runs out of the first data chunk
+ * before this call, the transfer is delayed.
+ */
+ dma_issue_pending(req->dma_desc);
diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/mmc/mmc-dev-attrs.rst
similarity index 73%
rename from Documentation/mmc/mmc-dev-attrs.txt
rename to Documentation/mmc/mmc-dev-attrs.rst
index 4ad0bb17f343..4f44b1b730d6 100644
--- a/Documentation/mmc/mmc-dev-attrs.txt
+++ b/Documentation/mmc/mmc-dev-attrs.rst
@@ -1,3 +1,4 @@
+==================================
SD and MMC Block Device Attributes
==================================
@@ -6,23 +7,29 @@ SD or MMC device.
The following attributes are read/write.
- force_ro Enforce read-only access even if write protect switch is off.
+ ======== ===============================================
+ force_ro Enforce read-only access even if write protect switch is off.
+ ======== ===============================================
SD and MMC Device Attributes
============================
All attributes are read-only.
+ ====================== ===============================================
cid Card Identification Register
csd Card Specific Data Register
scr SD Card Configuration Register (SD only)
date Manufacturing Date (from CID Register)
- fwrev Firmware/Product Revision (from CID Register) (SD and MMCv1 only)
- hwrev Hardware/Product Revision (from CID Register) (SD and MMCv1 only)
+ fwrev Firmware/Product Revision (from CID Register)
+ (SD and MMCv1 only)
+ hwrev Hardware/Product Revision (from CID Register)
+ (SD and MMCv1 only)
manfid Manufacturer ID (from CID Register)
name Product Name (from CID Register)
oemid OEM/Application ID (from CID Register)
- prv Product Revision (from CID Register) (SD and MMCv4 only)
+ prv Product Revision (from CID Register)
+ (SD and MMCv4 only)
serial Product Serial Number (from CID Register)
erase_size Erase group size
preferred_erase_size Preferred erase size
@@ -30,7 +37,10 @@ All attributes are read-only.
rel_sectors Reliable write sector count
ocr Operation Conditions Register
dsr Driver Stage Register
- cmdq_en Command Queue enabled: 1 => enabled, 0 => not enabled
+ cmdq_en Command Queue enabled:
+
+ 1 => enabled, 0 => not enabled
+ ====================== ===============================================
Note on Erase Size and Preferred Erase Size:
@@ -44,14 +54,15 @@ Note on Erase Size and Preferred Erase Size:
SD/MMC cards can erase an arbitrarily large area up to and
including the whole card. When erasing a large area it may
be desirable to do it in smaller chunks for three reasons:
- 1. A single erase command will make all other I/O on
+
+ 1. A single erase command will make all other I/O on
the card wait. This is not a problem if the whole card
is being erased, but erasing one partition will make
I/O for another partition on the same card wait for the
duration of the erase - which could be a several
minutes.
- 2. To be able to inform the user of erase progress.
- 3. The erase timeout becomes too large to be very
+ 2. To be able to inform the user of erase progress.
+ 3. The erase timeout becomes too large to be very
useful. Because the erase timeout contains a margin
which is multiplied by the size of the erase area,
the value can end up being several minutes for large
@@ -72,6 +83,9 @@ Note on Erase Size and Preferred Erase Size:
"preferred_erase_size" is in bytes.
Note on raw_rpmb_size_mult:
+
"raw_rpmb_size_mult" is a multiple of 128kB block.
+
RPMB size in byte is calculated by using the following equation:
- RPMB partition size = 128kB x raw_rpmb_size_mult
+
+ RPMB partition size = 128kB x raw_rpmb_size_mult
diff --git a/Documentation/mmc/mmc-dev-parts.txt b/Documentation/mmc/mmc-dev-parts.rst
similarity index 83%
rename from Documentation/mmc/mmc-dev-parts.txt
rename to Documentation/mmc/mmc-dev-parts.rst
index f08d078d43cf..995922f1f744 100644
--- a/Documentation/mmc/mmc-dev-parts.txt
+++ b/Documentation/mmc/mmc-dev-parts.rst
@@ -1,3 +1,4 @@
+============================
SD and MMC Device Partitions
============================
@@ -18,18 +19,18 @@ platform, write access is disabled by default to reduce the chance of
accidental bricking.
To enable write access to /dev/mmcblkXbootY, disable the forced read-only
-access with:
+access with::
-echo 0 > /sys/block/mmcblkXbootY/force_ro
+ echo 0 > /sys/block/mmcblkXbootY/force_ro
-To re-enable read-only access:
+To re-enable read-only access::
-echo 1 > /sys/block/mmcblkXbootY/force_ro
+ echo 1 > /sys/block/mmcblkXbootY/force_ro
The boot partitions can also be locked read only until the next power on,
-with:
+with::
-echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
+ echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
This is a feature of the card and not of the kernel. If the card does
not support boot partition locking, the file will not exist. If the
diff --git a/Documentation/mmc/mmc-tools.txt b/Documentation/mmc/mmc-tools.rst
similarity index 92%
rename from Documentation/mmc/mmc-tools.txt
rename to Documentation/mmc/mmc-tools.rst
index 735509c165d5..54406093768b 100644
--- a/Documentation/mmc/mmc-tools.txt
+++ b/Documentation/mmc/mmc-tools.rst
@@ -1,14 +1,17 @@
+======================
MMC tools introduction
======================
There is one MMC test tools called mmc-utils, which is maintained by Chris Ball,
you can find it at the below public git repository:
-http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
+
+ http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
Functions
=========
The mmc-utils tools can do the following:
+
- Print and parse extcsd data.
- Determine the eMMC writeprotect status.
- Set the eMMC writeprotect status.
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 33/43] docs: ioctl-number.txt: convert it to ReST format
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (30 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 32/43] docs: mmc: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 34/43] docs: ioctl: convert to ReST Mauro Carvalho Chehab
` (10 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Federico Vaga, Harry Wei, Alex Shi,
Doug Ledford, Jason Gunthorpe, linux-rdma
The conversion itself is simple: add a markup for the
title of this file and add markups for both tables.
Yet, the big table here with IOCTL numbers is badly formatted:
on several lines, the "Include File" column has some values that
are bigger than the reserved space there.
Also, on several places, a comment was misplaced at the "Include
File" space.
So, most of the work here is to actually ensure that each field
will be properly fixed.
Also worth to mention that some URLs have the asterisk character
on it. Well, Sphinx has an issue with asterisks in the middle
of an string. As this is URL, use the alternate format: %2A.
As a side effect of this patch, it is now a lot easier to see that
some reserved ioctl numbers are missing the include files
where it is supposed to be used.
PS.: While this is part of a subdir, I opted to convert this
single file alone, as this file has a potential of conflicts,
as most subsystem maintainers touch it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ioctl/ioctl-number.rst | 362 ++++++++++++++++++
Documentation/ioctl/ioctl-number.txt | 350 -----------------
Documentation/process/submit-checklist.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
include/uapi/rdma/rdma_user_ioctl_cmds.h | 2 +-
6 files changed, 366 insertions(+), 354 deletions(-)
create mode 100644 Documentation/ioctl/ioctl-number.rst
delete mode 100644 Documentation/ioctl/ioctl-number.txt
diff --git a/Documentation/ioctl/ioctl-number.rst b/Documentation/ioctl/ioctl-number.rst
new file mode 100644
index 000000000000..e6d07badafb1
--- /dev/null
+++ b/Documentation/ioctl/ioctl-number.rst
@@ -0,0 +1,362 @@
+:orphan:
+
+=============
+Ioctl Numbers
+=============
+
+19 October 1999
+
+Michael Elizabeth Chastain
+<mec@shout.net>
+
+If you are adding new ioctl's to the kernel, you should use the _IO
+macros defined in <linux/ioctl.h>:
+
+ ====== == ============================================
+ _IO an ioctl with no parameters
+ _IOW an ioctl with write parameters (copy_from_user)
+ _IOR an ioctl with read parameters (copy_to_user)
+ _IOWR an ioctl with both write and read parameters.
+ ====== == ============================================
+
+'Write' and 'read' are from the user's point of view, just like the
+system calls 'write' and 'read'. For example, a SET_FOO ioctl would
+be _IOW, although the kernel would actually read data from user space;
+a GET_FOO ioctl would be _IOR, although the kernel would actually write
+data to user space.
+
+The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter
+or number from the table below. Because of the large number of drivers,
+many drivers share a partial letter with other drivers.
+
+If you are writing a driver for a new device and need a letter, pick an
+unused block with enough room for expansion: 32 to 256 ioctl commands.
+You can register the block by patching this file and submitting the
+patch to Linus Torvalds. Or you can e-mail me at <mec@shout.net> and
+I'll register one for you.
+
+The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number
+to distinguish ioctls from each other. The third argument to _IOW,
+_IOR, or _IOWR is the type of the data going into the kernel or coming
+out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use
+sizeof(arg) as the third argument as this results in your ioctl thinking
+it passes an argument of type size_t.
+
+Some devices use their major number as the identifier; this is OK, as
+long as it is unique. Some devices are irregular and don't follow any
+convention at all.
+
+Following this convention is good because:
+
+(1) Keeping the ioctl's globally unique helps error checking:
+ if a program calls an ioctl on the wrong device, it will get an
+ error rather than some unexpected behaviour.
+
+(2) The 'strace' build procedure automatically finds ioctl numbers
+ defined with _IO, _IOW, _IOR, or _IOWR.
+
+(3) 'strace' can decode numbers back into useful names when the
+ numbers are unique.
+
+(4) People looking for ioctls can grep for them more easily when
+ this convention is used to define the ioctl numbers.
+
+(5) When following the convention, the driver code can use generic
+ code to copy the parameters between user and kernel space.
+
+This table lists ioctls visible from user land for Linux/x86. It contains
+most drivers up to 2.6.31, but I know I am missing some. There has been
+no attempt to list non-X86 architectures or ioctls from drivers/staging/.
+
+==== ===== ======================================================= ================================================================
+Code Seq# Include File Comments
+ (hex)
+==== ===== ======================================================= ================================================================
+0x00 00-1F linux/fs.h conflict!
+0x00 00-1F scsi/scsi_ioctl.h conflict!
+0x00 00-1F linux/fb.h conflict!
+0x00 00-1F linux/wavefront.h conflict!
+0x02 all linux/fd.h
+0x03 all linux/hdreg.h
+0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these.
+0x06 all linux/lp.h
+0x09 all linux/raid/md_u.h
+0x10 00-0F drivers/char/s390/vmcp.h
+0x10 10-1F arch/s390/include/uapi/sclp_ctl.h
+0x10 20-2F arch/s390/include/uapi/asm/hypfs.h
+0x12 all linux/fs.h
+ linux/blkpg.h
+0x1b all InfiniBand Subsystem
+ <http://infiniband.sourceforge.net/>
+0x20 all drivers/cdrom/cm206.h
+0x22 all scsi/sg.h
+'!' 00-1F uapi/linux/seccomp.h
+'#' 00-3F IEEE 1394 Subsystem
+ Block for the entire subsystem
+'$' 00-0F linux/perf_counter.h, linux/perf_event.h
+'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem
+ <mailto:alexander.shishkin@linux.intel.com>
+'&' 00-07 drivers/firewire/nosy-user.h
+'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl
+ <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
+'2' 01-04 linux/i2o.h
+'3' 00-0F drivers/s390/char/raw3270.h conflict!
+'3' 00-1F linux/suspend_ioctls.h, conflict!
+ kernel/power/user.c
+'8' all SNP8023 advanced NIC card
+ <mailto:mcr@solidum.com>
+';' 64-7F linux/vfio.h
+'@' 00-0F linux/radeonfb.h conflict!
+'@' 00-0F drivers/video/aty/aty128fb.c conflict!
+'A' 00-1F linux/apm_bios.h conflict!
+'A' 00-0F linux/agpgart.h, conflict!
+ drivers/char/agp/compat_ioctl.h
+'A' 00-7F sound/asound.h conflict!
+'B' 00-1F linux/cciss_ioctl.h conflict!
+'B' 00-0F include/linux/pmu.h conflict!
+'B' C0-FF advanced bbus <mailto:maassen@uni-freiburg.de>
+'C' all linux/soundcard.h conflict!
+'C' 01-2F linux/capi.h conflict!
+'C' F0-FF drivers/net/wan/cosa.h conflict!
+'D' all arch/s390/include/asm/dasd.h
+'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h
+'D' 05 drivers/scsi/pmcraid.h
+'E' all linux/input.h conflict!
+'E' 00-0F xen/evtchn.h conflict!
+'F' all linux/fb.h conflict!
+'F' 01-02 drivers/scsi/pmcraid.h conflict!
+'F' 20 drivers/video/fsl-diu-fb.h conflict!
+'F' 20 drivers/video/intelfb/intelfb.h conflict!
+'F' 20 linux/ivtvfb.h conflict!
+'F' 20 linux/matroxfb.h conflict!
+'F' 20 drivers/video/aty/atyfb_base.c conflict!
+'F' 00-0F video/da8xx-fb.h conflict!
+'F' 80-8F linux/arcfb.h conflict!
+'F' DD video/sstfb.h conflict!
+'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict!
+'G' 00-0F linux/gigaset_dev.h conflict!
+'H' 00-7F linux/hiddev.h conflict!
+'H' 00-0F linux/hidraw.h conflict!
+'H' 01 linux/mei.h conflict!
+'H' 02 linux/mei.h conflict!
+'H' 03 linux/mei.h conflict!
+'H' 00-0F sound/asound.h conflict!
+'H' 20-40 sound/asound_fm.h conflict!
+'H' 80-8F sound/sfnt_info.h conflict!
+'H' 10-8F sound/emu10k1.h conflict!
+'H' 10-1F sound/sb16_csp.h conflict!
+'H' 10-1F sound/hda_hwdep.h conflict!
+'H' 40-4F sound/hdspm.h conflict!
+'H' 40-4F sound/hdsp.h conflict!
+'H' 90 sound/usb/usx2y/usb_stream.h
+'H' A0 uapi/linux/usb/cdc-wdm.h
+'H' C0-F0 net/bluetooth/hci.h conflict!
+'H' C0-DF net/bluetooth/hidp/hidp.h conflict!
+'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict!
+'H' C0-DF net/bluetooth/bnep/bnep.h conflict!
+'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net>
+'H' F8-FA sound/firewire.h
+'I' all linux/isdn.h conflict!
+'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict!
+'I' 40-4F linux/mISDNif.h conflict!
+'J' 00-1F drivers/scsi/gdth_ioctl.h
+'K' all linux/kd.h
+'L' 00-1F linux/loop.h conflict!
+'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict!
+'L' 20-2F linux/lightnvm.h
+'L' E0-FF linux/ppdd.h encrypted disk device driver
+ <http://linux01.gwdg.de/~alatham/ppdd.html>
+'M' all linux/soundcard.h conflict!
+'M' 01-16 mtd/mtd-abi.h conflict!
+ and drivers/mtd/mtdchar.c
+'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h
+'M' 00-0F drivers/video/fsl-diu-fb.h conflict!
+'N' 00-1F drivers/usb/scanner.h
+'N' 40-7F drivers/block/nvme.c
+'O' 00-06 mtd/ubi-user.h UBI
+'P' all linux/soundcard.h conflict!
+'P' 60-6F sound/sscape_ioctl.h conflict!
+'P' 00-0F drivers/usb/class/usblp.c conflict!
+'P' 01-09 drivers/misc/pci_endpoint_test.c conflict!
+'Q' all linux/soundcard.h
+'R' 00-1F linux/random.h conflict!
+'R' 01 linux/rfkill.h conflict!
+'R' C0-DF net/bluetooth/rfcomm.h
+'S' all linux/cdrom.h conflict!
+'S' 80-81 scsi/scsi_ioctl.h conflict!
+'S' 82-FF scsi/scsi.h conflict!
+'S' 00-7F sound/asequencer.h conflict!
+'T' all linux/soundcard.h conflict!
+'T' 00-AF sound/asound.h conflict!
+'T' all arch/x86/include/asm/ioctls.h conflict!
+'T' C0-DF linux/if_tun.h conflict!
+'U' all sound/asound.h conflict!
+'U' 00-CF linux/uinput.h conflict!
+'U' 00-EF linux/usbdevice_fs.h
+'U' C0-CF drivers/bluetooth/hci_uart.h
+'V' all linux/vt.h conflict!
+'V' all linux/videodev2.h conflict!
+'V' C0 linux/ivtvfb.h conflict!
+'V' C0 linux/ivtv.h conflict!
+'V' C0 media/davinci/vpfe_capture.h conflict!
+'V' C0 media/si4713.h conflict!
+'W' 00-1F linux/watchdog.h conflict!
+'W' 00-1F linux/wanrouter.h conflict! (pre 3.9)
+'W' 00-3F sound/asound.h conflict!
+'W' 40-5F drivers/pci/switch/switchtec.c
+'X' all fs/xfs/xfs_fs.h, conflict!
+ fs/xfs/linux-2.6/xfs_ioctl32.h,
+ include/linux/falloc.h,
+ linux/fs.h,
+'X' all fs/ocfs2/ocfs_fs.h conflict!
+'X' 01 linux/pktcdvd.h conflict!
+'Y' all linux/cyclades.h
+'Z' 14-15 drivers/message/fusion/mptctl.h
+'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices
+ <mailto:gregkh@linuxfoundation.org>
+'a' all linux/atm*.h, linux/sonet.h ATM on linux
+ <http://lrcwww.epfl.ch/>
+'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver
+'b' 00-FF conflict! bit3 vme host bridge
+ <mailto:natalia@nikhefk.nikhef.nl>
+'c' all linux/cm4000_cs.h conflict!
+'c' 00-7F linux/comstats.h conflict!
+'c' 00-7F linux/coda.h conflict!
+'c' 00-1F linux/chio.h conflict!
+'c' 80-9F arch/s390/include/asm/chsc.h conflict!
+'c' A0-AF arch/x86/include/asm/msr.h conflict!
+'d' 00-FF linux/char/drm/drm.h conflict!
+'d' 02-40 pcmcia/ds.h conflict!
+'d' F0-FF linux/digi1.h
+'e' all linux/digi1.h conflict!
+'f' 00-1F linux/ext2_fs.h conflict!
+'f' 00-1F linux/ext3_fs.h conflict!
+'f' 00-0F fs/jfs/jfs_dinode.h conflict!
+'f' 00-0F fs/ext4/ext4.h conflict!
+'f' 00-0F linux/fs.h conflict!
+'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict!
+'g' 00-0F linux/usb/gadgetfs.h
+'g' 20-2F linux/usb/g_printer.h
+'h' 00-7F conflict! Charon filesystem
+ <mailto:zapman@interlan.net>
+'h' 00-1F linux/hpet.h conflict!
+'h' 80-8F fs/hfsplus/ioctl.c
+'i' 00-3F linux/i2o-dev.h conflict!
+'i' 0B-1F linux/ipmi.h conflict!
+'i' 80-8F linux/i8k.h
+'j' 00-3F linux/joystick.h
+'k' 00-0F linux/spi/spidev.h conflict!
+'k' 00-05 video/kyro.h conflict!
+'k' 10-17 linux/hsi/hsi_char.h HSI character device
+'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system
+ <http://web.archive.org/web/%2A/http://mikonos.dia.unisa.it/tcfs>
+'l' 40-7F linux/udf_fs_i.h in development:
+ <http://sourceforge.net/projects/linux-udf/>
+'m' 00-09 linux/mmtimer.h conflict!
+'m' all linux/mtio.h conflict!
+'m' all linux/soundcard.h conflict!
+'m' all linux/synclink.h conflict!
+'m' 00-19 drivers/message/fusion/mptctl.h conflict!
+'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict!
+'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c
+'n' 80-8F uapi/linux/nilfs2_api.h NILFS2
+'n' E0-FF linux/matroxfb.h matroxfb
+'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2
+'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps)
+'o' 40-41 mtd/ubi-user.h UBI
+'o' 01-A1 `linux/dvb/*.h` DVB
+'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this)
+'p' 00-1F linux/rtc.h conflict!
+'p' 00-3F linux/mc146818rtc.h conflict!
+'p' 40-7F linux/nvram.h
+'p' 80-9F linux/ppdev.h user-space parport
+ <mailto:tim@cyberelk.net>
+'p' A1-A5 linux/pps.h LinuxPPS
+ <mailto:giometti@linux.it>
+'q' 00-1F linux/serio.h
+'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK
+ linux/ixjuser.h <http://web.archive.org/web/%2A/http://www.quicknet.net>
+'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c
+'s' all linux/cdk.h
+'t' 00-7F linux/ppp-ioctl.h
+'t' 80-8F linux/isdn_ppp.h
+'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM
+'u' 00-1F linux/smb_fs.h gone
+'u' 20-3F linux/uvcvideo.h USB video class host driver
+'u' 40-4f linux/udmabuf.h userspace dma-buf misc device
+'v' 00-1F linux/ext2_fs.h conflict!
+'v' 00-1F linux/fs.h conflict!
+'v' 00-0F linux/sonypi.h conflict!
+'v' 00-0F media/v4l2-subdev.h conflict!
+'v' C0-FF linux/meye.h conflict!
+'w' all CERN SCI driver
+'y' 00-1F packet based user level communications
+ <mailto:zapman@interlan.net>
+'z' 00-3F CAN bus card conflict!
+ <mailto:hdstich@connectu.ulm.circular.de>
+'z' 40-7F CAN bus card conflict!
+ <mailto:oe@port.de>
+'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict!
+'|' 00-7F linux/media.h
+0x80 00-1F linux/fb.h
+0x89 00-06 arch/x86/include/asm/sockios.h
+0x89 0B-DF linux/sockios.h
+0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range
+0x89 E0-EF linux/dn.h PROTOPRIVATE range
+0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range
+0x8B all linux/wireless.h
+0x8C 00-3F WiNRADiO driver
+ <http://www.winradio.com.au/>
+0x90 00 drivers/cdrom/sbpcd.h
+0x92 00-0F drivers/usb/mon/mon_bin.c
+0x93 60-7F linux/auto_fs.h
+0x94 all fs/btrfs/ioctl.h Btrfs filesystem
+ and linux/fs.h some lifted to vfs/generic
+0x97 00-7F fs/ceph/ioctl.h Ceph file system
+0x99 00-0F 537-Addinboard driver
+ <mailto:buk@buks.ipn.de>
+0xA0 all linux/sdp/sdp.h Industrial Device Project
+ <mailto:kenji@bitgate.com>
+0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver
+0xA3 80-8F Port ACL in development:
+ <mailto:tlewis@mindspring.com>
+0xA3 90-9F linux/dtlk.h
+0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem
+0xAA 00-3F linux/uapi/linux/userfaultfd.h
+0xAB 00-1F linux/nbd.h
+0xAC 00-1F linux/raw.h
+0xAD 00 Netfilter device in development:
+ <mailto:rusty@rustcorp.com.au>
+0xAE all linux/kvm.h Kernel-based Virtual Machine
+ <mailto:kvm@vger.kernel.org>
+0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor
+0xB0 all RATIO devices in development:
+ <mailto:vgo@ratio.de>
+0xB1 00-1F PPPoX
+ <mailto:mostrows@styx.uwaterloo.ca>
+0xB3 00 linux/mmc/ioctl.h
+0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org>
+0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org>
+0xB6 all linux/fpga-dfl.h
+0xC0 00-0F linux/usb/iowarrior.h
+0xCA 00-0F uapi/misc/cxl.h
+0xCA 10-2F uapi/misc/ocxl.h
+0xCA 80-BF uapi/scsi/cxlflash_ioctl.h
+0xCB 00-1F CBM serial IEC bus in development:
+ <mailto:michael.klein@puffin.lb.shuttle.de>
+0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver
+0xCD 01 linux/reiserfs_fs.h
+0xCF 02 fs/cifs/ioctl.c
+0xDB 00-0F drivers/char/mwave/mwavepub.h
+0xDD 00-3F ZFCP device driver see drivers/s390/scsi/
+ <mailto:aherrman@de.ibm.com>
+0xE5 00-3F linux/fuse.h
+0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver
+0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development)
+ <mailto:thomas@winischhofer.net>
+0xF4 00-1F video/mbxfb.h mbxfb
+ <mailto:raph@8d.com>
+0xF6 all LTTng Linux Trace Toolkit Next Generation
+ <mailto:mathieu.desnoyers@efficios.com>
+0xFD all linux/dm-ioctl.h
+==== ===== ======================================================= ================================================================
diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt
deleted file mode 100644
index c9558146ac58..000000000000
--- a/Documentation/ioctl/ioctl-number.txt
+++ /dev/null
@@ -1,350 +0,0 @@
-Ioctl Numbers
-19 October 1999
-Michael Elizabeth Chastain
-<mec@shout.net>
-
-If you are adding new ioctl's to the kernel, you should use the _IO
-macros defined in <linux/ioctl.h>:
-
- _IO an ioctl with no parameters
- _IOW an ioctl with write parameters (copy_from_user)
- _IOR an ioctl with read parameters (copy_to_user)
- _IOWR an ioctl with both write and read parameters.
-
-'Write' and 'read' are from the user's point of view, just like the
-system calls 'write' and 'read'. For example, a SET_FOO ioctl would
-be _IOW, although the kernel would actually read data from user space;
-a GET_FOO ioctl would be _IOR, although the kernel would actually write
-data to user space.
-
-The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter
-or number from the table below. Because of the large number of drivers,
-many drivers share a partial letter with other drivers.
-
-If you are writing a driver for a new device and need a letter, pick an
-unused block with enough room for expansion: 32 to 256 ioctl commands.
-You can register the block by patching this file and submitting the
-patch to Linus Torvalds. Or you can e-mail me at <mec@shout.net> and
-I'll register one for you.
-
-The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number
-to distinguish ioctls from each other. The third argument to _IOW,
-_IOR, or _IOWR is the type of the data going into the kernel or coming
-out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use
-sizeof(arg) as the third argument as this results in your ioctl thinking
-it passes an argument of type size_t.
-
-Some devices use their major number as the identifier; this is OK, as
-long as it is unique. Some devices are irregular and don't follow any
-convention at all.
-
-Following this convention is good because:
-
-(1) Keeping the ioctl's globally unique helps error checking:
- if a program calls an ioctl on the wrong device, it will get an
- error rather than some unexpected behaviour.
-
-(2) The 'strace' build procedure automatically finds ioctl numbers
- defined with _IO, _IOW, _IOR, or _IOWR.
-
-(3) 'strace' can decode numbers back into useful names when the
- numbers are unique.
-
-(4) People looking for ioctls can grep for them more easily when
- this convention is used to define the ioctl numbers.
-
-(5) When following the convention, the driver code can use generic
- code to copy the parameters between user and kernel space.
-
-This table lists ioctls visible from user land for Linux/x86. It contains
-most drivers up to 2.6.31, but I know I am missing some. There has been
-no attempt to list non-X86 architectures or ioctls from drivers/staging/.
-
-Code Seq#(hex) Include File Comments
-========================================================
-0x00 00-1F linux/fs.h conflict!
-0x00 00-1F scsi/scsi_ioctl.h conflict!
-0x00 00-1F linux/fb.h conflict!
-0x00 00-1F linux/wavefront.h conflict!
-0x02 all linux/fd.h
-0x03 all linux/hdreg.h
-0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these.
-0x06 all linux/lp.h
-0x09 all linux/raid/md_u.h
-0x10 00-0F drivers/char/s390/vmcp.h
-0x10 10-1F arch/s390/include/uapi/sclp_ctl.h
-0x10 20-2F arch/s390/include/uapi/asm/hypfs.h
-0x12 all linux/fs.h
- linux/blkpg.h
-0x1b all InfiniBand Subsystem <http://infiniband.sourceforge.net/>
-0x20 all drivers/cdrom/cm206.h
-0x22 all scsi/sg.h
-'!' 00-1F uapi/linux/seccomp.h
-'#' 00-3F IEEE 1394 Subsystem Block for the entire subsystem
-'$' 00-0F linux/perf_counter.h, linux/perf_event.h
-'%' 00-0F include/uapi/linux/stm.h
- System Trace Module subsystem
- <mailto:alexander.shishkin@linux.intel.com>
-'&' 00-07 drivers/firewire/nosy-user.h
-'1' 00-1F <linux/timepps.h> PPS kit from Ulrich Windl
- <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
-'2' 01-04 linux/i2o.h
-'3' 00-0F drivers/s390/char/raw3270.h conflict!
-'3' 00-1F linux/suspend_ioctls.h conflict!
- and kernel/power/user.c
-'8' all SNP8023 advanced NIC card
- <mailto:mcr@solidum.com>
-';' 64-7F linux/vfio.h
-'@' 00-0F linux/radeonfb.h conflict!
-'@' 00-0F drivers/video/aty/aty128fb.c conflict!
-'A' 00-1F linux/apm_bios.h conflict!
-'A' 00-0F linux/agpgart.h conflict!
- and drivers/char/agp/compat_ioctl.h
-'A' 00-7F sound/asound.h conflict!
-'B' 00-1F linux/cciss_ioctl.h conflict!
-'B' 00-0F include/linux/pmu.h conflict!
-'B' C0-FF advanced bbus
- <mailto:maassen@uni-freiburg.de>
-'C' all linux/soundcard.h conflict!
-'C' 01-2F linux/capi.h conflict!
-'C' F0-FF drivers/net/wan/cosa.h conflict!
-'D' all arch/s390/include/asm/dasd.h
-'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h
-'D' 05 drivers/scsi/pmcraid.h
-'E' all linux/input.h conflict!
-'E' 00-0F xen/evtchn.h conflict!
-'F' all linux/fb.h conflict!
-'F' 01-02 drivers/scsi/pmcraid.h conflict!
-'F' 20 drivers/video/fsl-diu-fb.h conflict!
-'F' 20 drivers/video/intelfb/intelfb.h conflict!
-'F' 20 linux/ivtvfb.h conflict!
-'F' 20 linux/matroxfb.h conflict!
-'F' 20 drivers/video/aty/atyfb_base.c conflict!
-'F' 00-0F video/da8xx-fb.h conflict!
-'F' 80-8F linux/arcfb.h conflict!
-'F' DD video/sstfb.h conflict!
-'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict!
-'G' 00-0F linux/gigaset_dev.h conflict!
-'H' 00-7F linux/hiddev.h conflict!
-'H' 00-0F linux/hidraw.h conflict!
-'H' 01 linux/mei.h conflict!
-'H' 02 linux/mei.h conflict!
-'H' 03 linux/mei.h conflict!
-'H' 00-0F sound/asound.h conflict!
-'H' 20-40 sound/asound_fm.h conflict!
-'H' 80-8F sound/sfnt_info.h conflict!
-'H' 10-8F sound/emu10k1.h conflict!
-'H' 10-1F sound/sb16_csp.h conflict!
-'H' 10-1F sound/hda_hwdep.h conflict!
-'H' 40-4F sound/hdspm.h conflict!
-'H' 40-4F sound/hdsp.h conflict!
-'H' 90 sound/usb/usx2y/usb_stream.h
-'H' A0 uapi/linux/usb/cdc-wdm.h
-'H' C0-F0 net/bluetooth/hci.h conflict!
-'H' C0-DF net/bluetooth/hidp/hidp.h conflict!
-'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict!
-'H' C0-DF net/bluetooth/bnep/bnep.h conflict!
-'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net>
-'H' F8-FA sound/firewire.h
-'I' all linux/isdn.h conflict!
-'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict!
-'I' 40-4F linux/mISDNif.h conflict!
-'J' 00-1F drivers/scsi/gdth_ioctl.h
-'K' all linux/kd.h
-'L' 00-1F linux/loop.h conflict!
-'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict!
-'L' 20-2F linux/lightnvm.h
-'L' E0-FF linux/ppdd.h encrypted disk device driver
- <http://linux01.gwdg.de/~alatham/ppdd.html>
-'M' all linux/soundcard.h conflict!
-'M' 01-16 mtd/mtd-abi.h conflict!
- and drivers/mtd/mtdchar.c
-'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h
-'M' 00-0F drivers/video/fsl-diu-fb.h conflict!
-'N' 00-1F drivers/usb/scanner.h
-'N' 40-7F drivers/block/nvme.c
-'O' 00-06 mtd/ubi-user.h UBI
-'P' all linux/soundcard.h conflict!
-'P' 60-6F sound/sscape_ioctl.h conflict!
-'P' 00-0F drivers/usb/class/usblp.c conflict!
-'P' 01-09 drivers/misc/pci_endpoint_test.c conflict!
-'Q' all linux/soundcard.h
-'R' 00-1F linux/random.h conflict!
-'R' 01 linux/rfkill.h conflict!
-'R' C0-DF net/bluetooth/rfcomm.h
-'S' all linux/cdrom.h conflict!
-'S' 80-81 scsi/scsi_ioctl.h conflict!
-'S' 82-FF scsi/scsi.h conflict!
-'S' 00-7F sound/asequencer.h conflict!
-'T' all linux/soundcard.h conflict!
-'T' 00-AF sound/asound.h conflict!
-'T' all arch/x86/include/asm/ioctls.h conflict!
-'T' C0-DF linux/if_tun.h conflict!
-'U' all sound/asound.h conflict!
-'U' 00-CF linux/uinput.h conflict!
-'U' 00-EF linux/usbdevice_fs.h
-'U' C0-CF drivers/bluetooth/hci_uart.h
-'V' all linux/vt.h conflict!
-'V' all linux/videodev2.h conflict!
-'V' C0 linux/ivtvfb.h conflict!
-'V' C0 linux/ivtv.h conflict!
-'V' C0 media/davinci/vpfe_capture.h conflict!
-'V' C0 media/si4713.h conflict!
-'W' 00-1F linux/watchdog.h conflict!
-'W' 00-1F linux/wanrouter.h conflict! (pre 3.9)
-'W' 00-3F sound/asound.h conflict!
-'W' 40-5F drivers/pci/switch/switchtec.c
-'X' all fs/xfs/xfs_fs.h conflict!
- and fs/xfs/linux-2.6/xfs_ioctl32.h
- and include/linux/falloc.h
- and linux/fs.h
-'X' all fs/ocfs2/ocfs_fs.h conflict!
-'X' 01 linux/pktcdvd.h conflict!
-'Y' all linux/cyclades.h
-'Z' 14-15 drivers/message/fusion/mptctl.h
-'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices
- <mailto:gregkh@linuxfoundation.org>
-'a' all linux/atm*.h, linux/sonet.h ATM on linux
- <http://lrcwww.epfl.ch/>
-'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver
-'b' 00-FF conflict! bit3 vme host bridge
- <mailto:natalia@nikhefk.nikhef.nl>
-'c' all linux/cm4000_cs.h conflict!
-'c' 00-7F linux/comstats.h conflict!
-'c' 00-7F linux/coda.h conflict!
-'c' 00-1F linux/chio.h conflict!
-'c' 80-9F arch/s390/include/asm/chsc.h conflict!
-'c' A0-AF arch/x86/include/asm/msr.h conflict!
-'d' 00-FF linux/char/drm/drm.h conflict!
-'d' 02-40 pcmcia/ds.h conflict!
-'d' F0-FF linux/digi1.h
-'e' all linux/digi1.h conflict!
-'f' 00-1F linux/ext2_fs.h conflict!
-'f' 00-1F linux/ext3_fs.h conflict!
-'f' 00-0F fs/jfs/jfs_dinode.h conflict!
-'f' 00-0F fs/ext4/ext4.h conflict!
-'f' 00-0F linux/fs.h conflict!
-'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict!
-'g' 00-0F linux/usb/gadgetfs.h
-'g' 20-2F linux/usb/g_printer.h
-'h' 00-7F conflict! Charon filesystem
- <mailto:zapman@interlan.net>
-'h' 00-1F linux/hpet.h conflict!
-'h' 80-8F fs/hfsplus/ioctl.c
-'i' 00-3F linux/i2o-dev.h conflict!
-'i' 0B-1F linux/ipmi.h conflict!
-'i' 80-8F linux/i8k.h
-'j' 00-3F linux/joystick.h
-'k' 00-0F linux/spi/spidev.h conflict!
-'k' 00-05 video/kyro.h conflict!
-'k' 10-17 linux/hsi/hsi_char.h HSI character device
-'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system
- <http://web.archive.org/web/*/http://mikonos.dia.unisa.it/tcfs>
-'l' 40-7F linux/udf_fs_i.h in development:
- <http://sourceforge.net/projects/linux-udf/>
-'m' 00-09 linux/mmtimer.h conflict!
-'m' all linux/mtio.h conflict!
-'m' all linux/soundcard.h conflict!
-'m' all linux/synclink.h conflict!
-'m' 00-19 drivers/message/fusion/mptctl.h conflict!
-'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict!
-'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c
-'n' 80-8F uapi/linux/nilfs2_api.h NILFS2
-'n' E0-FF linux/matroxfb.h matroxfb
-'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2
-'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps)
-'o' 40-41 mtd/ubi-user.h UBI
-'o' 01-A1 linux/dvb/*.h DVB
-'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this)
-'p' 00-1F linux/rtc.h conflict!
-'p' 00-3F linux/mc146818rtc.h conflict!
-'p' 40-7F linux/nvram.h
-'p' 80-9F linux/ppdev.h user-space parport
- <mailto:tim@cyberelk.net>
-'p' A1-A5 linux/pps.h LinuxPPS
- <mailto:giometti@linux.it>
-'q' 00-1F linux/serio.h
-'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK
- linux/ixjuser.h <http://web.archive.org/web/*/http://www.quicknet.net>
-'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c
-'s' all linux/cdk.h
-'t' 00-7F linux/ppp-ioctl.h
-'t' 80-8F linux/isdn_ppp.h
-'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM
-'u' 00-1F linux/smb_fs.h gone
-'u' 20-3F linux/uvcvideo.h USB video class host driver
-'u' 40-4f linux/udmabuf.h userspace dma-buf misc device
-'v' 00-1F linux/ext2_fs.h conflict!
-'v' 00-1F linux/fs.h conflict!
-'v' 00-0F linux/sonypi.h conflict!
-'v' 00-0F media/v4l2-subdev.h conflict!
-'v' C0-FF linux/meye.h conflict!
-'w' all CERN SCI driver
-'y' 00-1F packet based user level communications
- <mailto:zapman@interlan.net>
-'z' 00-3F CAN bus card conflict!
- <mailto:hdstich@connectu.ulm.circular.de>
-'z' 40-7F CAN bus card conflict!
- <mailto:oe@port.de>
-'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict!
-'|' 00-7F linux/media.h
-0x80 00-1F linux/fb.h
-0x89 00-06 arch/x86/include/asm/sockios.h
-0x89 0B-DF linux/sockios.h
-0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range
-0x89 E0-EF linux/dn.h PROTOPRIVATE range
-0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range
-0x8B all linux/wireless.h
-0x8C 00-3F WiNRADiO driver
- <http://www.winradio.com.au/>
-0x90 00 drivers/cdrom/sbpcd.h
-0x92 00-0F drivers/usb/mon/mon_bin.c
-0x93 60-7F linux/auto_fs.h
-0x94 all fs/btrfs/ioctl.h Btrfs filesystem
- and linux/fs.h some lifted to vfs/generic
-0x97 00-7F fs/ceph/ioctl.h Ceph file system
-0x99 00-0F 537-Addinboard driver
- <mailto:buk@buks.ipn.de>
-0xA0 all linux/sdp/sdp.h Industrial Device Project
- <mailto:kenji@bitgate.com>
-0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver
-0xA3 80-8F Port ACL in development:
- <mailto:tlewis@mindspring.com>
-0xA3 90-9F linux/dtlk.h
-0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem
-0xAA 00-3F linux/uapi/linux/userfaultfd.h
-0xAB 00-1F linux/nbd.h
-0xAC 00-1F linux/raw.h
-0xAD 00 Netfilter device in development:
- <mailto:rusty@rustcorp.com.au>
-0xAE all linux/kvm.h Kernel-based Virtual Machine
- <mailto:kvm@vger.kernel.org>
-0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor
-0xB0 all RATIO devices in development:
- <mailto:vgo@ratio.de>
-0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca>
-0xB3 00 linux/mmc/ioctl.h
-0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org>
-0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org>
-0xB6 all linux/fpga-dfl.h
-0xC0 00-0F linux/usb/iowarrior.h
-0xCA 00-0F uapi/misc/cxl.h
-0xCA 10-2F uapi/misc/ocxl.h
-0xCA 80-BF uapi/scsi/cxlflash_ioctl.h
-0xCB 00-1F CBM serial IEC bus in development:
- <mailto:michael.klein@puffin.lb.shuttle.de>
-0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver
-0xCD 01 linux/reiserfs_fs.h
-0xCF 02 fs/cifs/ioctl.c
-0xDB 00-0F drivers/char/mwave/mwavepub.h
-0xDD 00-3F ZFCP device driver see drivers/s390/scsi/
- <mailto:aherrman@de.ibm.com>
-0xE5 00-3F linux/fuse.h
-0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver
-0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development)
- <mailto:thomas@winischhofer.net>
-0xF4 00-1F video/mbxfb.h mbxfb
- <mailto:raph@8d.com>
-0xF6 all LTTng Linux Trace Toolkit Next Generation
- <mailto:mathieu.desnoyers@efficios.com>
-0xFD all linux/dm-ioctl.h
diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
index 365efc9e4aa8..8e56337d422d 100644
--- a/Documentation/process/submit-checklist.rst
+++ b/Documentation/process/submit-checklist.rst
@@ -107,7 +107,7 @@ and elsewhere regarding submitting Linux kernel patches.
and why.
26) If any ioctl's are added by the patch, then also update
- ``Documentation/ioctl/ioctl-number.txt``.
+ ``Documentation/ioctl/ioctl-number.rst``.
27) If your modified source code depends on or uses any of the kernel
APIs or features that are related to the following ``Kconfig`` symbols,
diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst
index ea74cae958d7..995ee69fab11 100644
--- a/Documentation/translations/it_IT/process/submit-checklist.rst
+++ b/Documentation/translations/it_IT/process/submit-checklist.rst
@@ -117,7 +117,7 @@ sottomissione delle patch, in particolare
sorgenti che ne spieghi la logica: cosa fanno e perché.
25) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate
- ``Documentation/ioctl/ioctl-number.txt``.
+ ``Documentation/ioctl/ioctl-number.rst``.
26) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o
funzionalità del kernel che è associata a uno dei seguenti simboli
diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst
index f4785d2b0491..8738c55e42a2 100644
--- a/Documentation/translations/zh_CN/process/submit-checklist.rst
+++ b/Documentation/translations/zh_CN/process/submit-checklist.rst
@@ -97,7 +97,7 @@ Linux内核补丁提交清单
24) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注
释来解释它们正在执行的操作及其原因的逻辑。
-25) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/ioctl/ioctl-number.txt``
+25) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/ioctl/ioctl-number.rst``
26) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或
功能，则在禁用相关 ``Kconfig`` 符号和/或 ``=m`` （如果该选项可用）的情况
diff --git a/include/uapi/rdma/rdma_user_ioctl_cmds.h b/include/uapi/rdma/rdma_user_ioctl_cmds.h
index 26213f49f5c8..54e16a589472 100644
--- a/include/uapi/rdma/rdma_user_ioctl_cmds.h
+++ b/include/uapi/rdma/rdma_user_ioctl_cmds.h
@@ -36,7 +36,7 @@
#include <linux/types.h>
#include <linux/ioctl.h>
-/* Documentation/ioctl/ioctl-number.txt */
+/* Documentation/ioctl/ioctl-number.rst */
#define RDMA_IOCTL_MAGIC 0x1b
#define RDMA_VERBS_IOCTL \
_IOWR(RDMA_IOCTL_MAGIC, 1, struct ib_uverbs_ioctl_hdr)
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 34/43] docs: ioctl: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (31 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 33/43] docs: ioctl-number.txt: convert it to ReST format Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 35/43] docs: thermal: " Mauro Carvalho Chehab
` (9 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Maarten Lankhorst, Maxime Ripard, Sean Paul,
David Airlie, Daniel Vetter, dri-devel
Rename the iio documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
The cdrom.txt and hdio.txt have their own particular syntax.
In order to speedup the conversion, I used a small ancillary
perl script:
my $d;
$d .= $_ while(<>);
$d =~ s/(\nCDROM\S+)\s+(\w[^\n]*)/$1\n\t$2\n/g;
$d =~ s/(\nHDIO\S+)\s+(\w[^\n]*)/$1\n\t$2\n/g;
$d =~ s/(\n\s*usage:)[\s\n]*(\w[^\n]*)/$1:\n\n\t $2\n/g;
$d =~ s/(\n\s*)(E\w+[\s\n]*\w[^\n]*)/$1- $2/g;
$d =~ s/(\n\s*)(inputs|outputs|notes):\s*(\w[^\n]*)/$1$2:\n\t\t$3\n/g;
print $d;
It basically add blank lines on a few interesting places. The
script is not perfect: still several things require manual work,
but it saved quite some time doing some obvious stuff.
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>
---
...g-up-ioctls.txt => botching-up-ioctls.rst} | 1 +
Documentation/ioctl/cdrom.rst | 1233 +++++++++++++++++
Documentation/ioctl/cdrom.txt | 967 -------------
Documentation/ioctl/{hdio.txt => hdio.rst} | 835 +++++++----
Documentation/ioctl/index.rst | 16 +
...{ioctl-decoding.txt => ioctl-decoding.rst} | 13 +-
drivers/gpu/drm/drm_ioctl.c | 2 +-
7 files changed, 1814 insertions(+), 1253 deletions(-)
rename Documentation/ioctl/{botching-up-ioctls.txt => botching-up-ioctls.rst} (99%)
create mode 100644 Documentation/ioctl/cdrom.rst
delete mode 100644 Documentation/ioctl/cdrom.txt
rename Documentation/ioctl/{hdio.txt => hdio.rst} (54%)
create mode 100644 Documentation/ioctl/index.rst
rename Documentation/ioctl/{ioctl-decoding.txt => ioctl-decoding.rst} (54%)
diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.rst
similarity index 99%
rename from Documentation/ioctl/botching-up-ioctls.txt
rename to Documentation/ioctl/botching-up-ioctls.rst
index 883fb034bd04..ac697fef3545 100644
--- a/Documentation/ioctl/botching-up-ioctls.txt
+++ b/Documentation/ioctl/botching-up-ioctls.rst
@@ -1,3 +1,4 @@
+=================================
(How to avoid) Botching up ioctls
=================================
diff --git a/Documentation/ioctl/cdrom.rst b/Documentation/ioctl/cdrom.rst
new file mode 100644
index 000000000000..3b4c0506de46
--- /dev/null
+++ b/Documentation/ioctl/cdrom.rst
@@ -0,0 +1,1233 @@
+============================
+Summary of CDROM ioctl calls
+============================
+
+- Edward A. Falk <efalk@google.com>
+
+November, 2004
+
+This document attempts to describe the ioctl(2) calls supported by
+the CDROM layer. These are by-and-large implemented (as of Linux 2.6)
+in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c
+
+ioctl values are listed in <linux/cdrom.h>. As of this writing, they
+are as follows:
+
+ ====================== ===============================================
+ CDROMPAUSE Pause Audio Operation
+ CDROMRESUME Resume paused Audio Operation
+ CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
+ CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti)
+ CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr)
+ CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry)
+ CDROMSTOP Stop the cdrom drive
+ CDROMSTART Start the cdrom drive
+ CDROMEJECT Ejects the cdrom media
+ CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
+ CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
+ CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
+ (struct cdrom_read)
+ CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
+ (struct cdrom_read)
+ CDROMREADAUDIO (struct cdrom_read_audio)
+ CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
+ CDROMMULTISESSION Obtain the start-of-last-session
+ address of multi session disks
+ (struct cdrom_multisession)
+ CDROM_GET_MCN Obtain the "Universal Product Code"
+ if available (struct cdrom_mcn)
+ CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead.
+ CDROMRESET hard-reset the drive
+ CDROMVOLREAD Get the drive's volume setting
+ (struct cdrom_volctrl)
+ CDROMREADRAW read data in raw mode (2352 Bytes)
+ (struct cdrom_read)
+ CDROMREADCOOKED read data in cooked mode
+ CDROMSEEK seek msf address
+ CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
+ CDROMREADALL read all 2646 bytes
+ CDROMGETSPINDOWN return 4-bit spindown value
+ CDROMSETSPINDOWN set 4-bit spindown value
+ CDROMCLOSETRAY pendant of CDROMEJECT
+ CDROM_SET_OPTIONS Set behavior options
+ CDROM_CLEAR_OPTIONS Clear behavior options
+ CDROM_SELECT_SPEED Set the CD-ROM speed
+ CDROM_SELECT_DISC Select disc (for juke-boxes)
+ CDROM_MEDIA_CHANGED Check is media changed
+ CDROM_DRIVE_STATUS Get tray position, etc.
+ CDROM_DISC_STATUS Get disc type, etc.
+ CDROM_CHANGER_NSLOTS Get number of slots
+ CDROM_LOCKDOOR lock or unlock door
+ CDROM_DEBUG Turn debug messages on/off
+ CDROM_GET_CAPABILITY get capabilities
+ CDROMAUDIOBUFSIZ set the audio buffer size
+ DVD_READ_STRUCT Read structure
+ DVD_WRITE_STRUCT Write structure
+ DVD_AUTH Authentication
+ CDROM_SEND_PACKET send a packet to the drive
+ CDROM_NEXT_WRITABLE get next writable block
+ CDROM_LAST_WRITTEN get last block written on disc
+ ====================== ===============================================
+
+
+The information that follows was determined from reading kernel source
+code. It is likely that some corrections will be made over time.
+
+------------------------------------------------------------------------------
+
+General:
+
+ Unless otherwise specified, all ioctl calls return 0 on success
+ and -1 with errno set to an appropriate value on error. (Some
+ ioctls return non-negative data values.)
+
+ Unless otherwise specified, all ioctl calls return -1 and set
+ errno to EFAULT on a failed attempt to copy data to or from user
+ address space.
+
+ Individual drivers may return error codes not listed here.
+
+ Unless otherwise specified, all data structures and constants
+ are defined in <linux/cdrom.h>
+
+------------------------------------------------------------------------------
+
+
+CDROMPAUSE
+ Pause Audio Operation
+
+
+ usage::
+
+ ioctl(fd, CDROMPAUSE, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+
+CDROMRESUME
+ Resume paused Audio Operation
+
+
+ usage::
+
+ ioctl(fd, CDROMRESUME, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+
+CDROMPLAYMSF
+ Play Audio MSF
+
+ (struct cdrom_msf)
+
+
+ usage::
+
+ struct cdrom_msf msf;
+
+ ioctl(fd, CDROMPLAYMSF, &msf);
+
+ inputs:
+ cdrom_msf structure, describing a segment of music to play
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+ notes:
+ - MSF stands for minutes-seconds-frames
+ - LBA stands for logical block address
+ - Segment is described as start and end times, where each time
+ is described as minutes:seconds:frames.
+ A frame is 1/75 of a second.
+
+
+CDROMPLAYTRKIND
+ Play Audio Track/index
+
+ (struct cdrom_ti)
+
+
+ usage::
+
+ struct cdrom_ti ti;
+
+ ioctl(fd, CDROMPLAYTRKIND, &ti);
+
+ inputs:
+ cdrom_ti structure, describing a segment of music to play
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+ notes:
+ - Segment is described as start and end times, where each time
+ is described as a track and an index.
+
+
+
+CDROMREADTOCHDR
+ Read TOC header
+
+ (struct cdrom_tochdr)
+
+
+ usage::
+
+ cdrom_tochdr header;
+
+ ioctl(fd, CDROMREADTOCHDR, &header);
+
+ inputs:
+ cdrom_tochdr structure
+
+
+ outputs:
+ cdrom_tochdr structure
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+
+
+CDROMREADTOCENTRY
+ Read TOC entry
+
+ (struct cdrom_tocentry)
+
+
+ usage::
+
+ struct cdrom_tocentry entry;
+
+ ioctl(fd, CDROMREADTOCENTRY, &entry);
+
+ inputs:
+ cdrom_tocentry structure
+
+
+ outputs:
+ cdrom_tocentry structure
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+ - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA
+ - EINVAL requested track out of bounds
+ - EIO I/O error reading TOC
+
+ notes:
+ - TOC stands for Table Of Contents
+ - MSF stands for minutes-seconds-frames
+ - LBA stands for logical block address
+
+
+
+CDROMSTOP
+ Stop the cdrom drive
+
+
+ usage::
+
+ ioctl(fd, CDROMSTOP, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+ notes:
+ - Exact interpretation of this ioctl depends on the device,
+ but most seem to spin the drive down.
+
+
+CDROMSTART
+ Start the cdrom drive
+
+
+ usage::
+
+ ioctl(fd, CDROMSTART, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+ notes:
+ - Exact interpretation of this ioctl depends on the device,
+ but most seem to spin the drive up and/or close the tray.
+ Other devices ignore the ioctl completely.
+
+
+CDROMEJECT
+ - Ejects the cdrom media
+
+
+ usage::
+
+ ioctl(fd, CDROMEJECT, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ none
+
+
+ error returns:
+ - ENOSYS cd drive not capable of ejecting
+ - EBUSY other processes are accessing drive, or door is locked
+
+ notes:
+ - See CDROM_LOCKDOOR, below.
+
+
+
+
+CDROMCLOSETRAY
+ pendant of CDROMEJECT
+
+
+ usage::
+
+ ioctl(fd, CDROMCLOSETRAY, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ none
+
+
+ error returns:
+ - ENOSYS cd drive not capable of closing the tray
+ - EBUSY other processes are accessing drive, or door is locked
+
+ notes:
+ - See CDROM_LOCKDOOR, below.
+
+
+
+
+CDROMVOLCTRL
+ Control output volume (struct cdrom_volctrl)
+
+
+ usage::
+
+ struct cdrom_volctrl volume;
+
+ ioctl(fd, CDROMVOLCTRL, &volume);
+
+ inputs:
+ cdrom_volctrl structure containing volumes for up to 4
+ channels.
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+
+
+CDROMVOLREAD
+ Get the drive's volume setting
+
+ (struct cdrom_volctrl)
+
+
+ usage::
+
+ struct cdrom_volctrl volume;
+
+ ioctl(fd, CDROMVOLREAD, &volume);
+
+ inputs:
+ none
+
+
+ outputs:
+ The current volume settings.
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+
+
+
+CDROMSUBCHNL
+ Read subchannel data
+
+ (struct cdrom_subchnl)
+
+
+ usage::
+
+ struct cdrom_subchnl q;
+
+ ioctl(fd, CDROMSUBCHNL, &q);
+
+ inputs:
+ cdrom_subchnl structure
+
+
+ outputs:
+ cdrom_subchnl structure
+
+
+ error return:
+ - ENOSYS cd drive not audio-capable.
+ - EINVAL format not CDROM_MSF or CDROM_LBA
+
+ notes:
+ - Format is converted to CDROM_MSF or CDROM_LBA
+ as per user request on return
+
+
+
+CDROMREADRAW
+ read data in raw mode (2352 Bytes)
+
+ (struct cdrom_read)
+
+ usage::
+
+ union {
+
+ struct cdrom_msf msf; /* input */
+ char buffer[CD_FRAMESIZE_RAW]; /* return */
+ } arg;
+ ioctl(fd, CDROMREADRAW, &arg);
+
+ inputs:
+ cdrom_msf structure indicating an address to read.
+
+ Only the start values are significant.
+
+ outputs:
+ Data written to address provided by user.
+
+
+ error return:
+ - EINVAL address less than 0, or msf less than 0:2:0
+ - ENOMEM out of memory
+
+ notes:
+ - As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
+ ioctl accepts a cdrom_read structure, but actual source code
+ reads a cdrom_msf structure and writes a buffer of data to
+ the same address.
+
+ - MSF values are converted to LBA values via this formula::
+
+ lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
+
+
+
+
+CDROMREADMODE1
+ Read CDROM mode 1 data (2048 Bytes)
+
+ (struct cdrom_read)
+
+ notes:
+ Identical to CDROMREADRAW except that block size is
+ CD_FRAMESIZE (2048) bytes
+
+
+
+CDROMREADMODE2
+ Read CDROM mode 2 data (2336 Bytes)
+
+ (struct cdrom_read)
+
+ notes:
+ Identical to CDROMREADRAW except that block size is
+ CD_FRAMESIZE_RAW0 (2336) bytes
+
+
+
+CDROMREADAUDIO
+ (struct cdrom_read_audio)
+
+ usage::
+
+ struct cdrom_read_audio ra;
+
+ ioctl(fd, CDROMREADAUDIO, &ra);
+
+ inputs:
+ cdrom_read_audio structure containing read start
+ point and length
+
+ outputs:
+ audio data, returned to buffer indicated by ra
+
+
+ error return:
+ - EINVAL format not CDROM_MSF or CDROM_LBA
+ - EINVAL nframes not in range [1 75]
+ - ENXIO drive has no queue (probably means invalid fd)
+ - ENOMEM out of memory
+
+
+CDROMEJECT_SW
+ enable(1)/disable(0) auto-ejecting
+
+
+ usage::
+
+ int val;
+
+ ioctl(fd, CDROMEJECT_SW, val);
+
+ inputs:
+ Flag specifying auto-eject flag.
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS Drive is not capable of ejecting.
+ - EBUSY Door is locked
+
+
+
+
+CDROMMULTISESSION
+ Obtain the start-of-last-session address of multi session disks
+
+ (struct cdrom_multisession)
+
+ usage::
+
+ struct cdrom_multisession ms_info;
+
+ ioctl(fd, CDROMMULTISESSION, &ms_info);
+
+ inputs:
+ cdrom_multisession structure containing desired
+
+ format.
+
+ outputs:
+ cdrom_multisession structure is filled with last_session
+ information.
+
+ error return:
+ - EINVAL format not CDROM_MSF or CDROM_LBA
+
+
+CDROM_GET_MCN
+ Obtain the "Universal Product Code"
+ if available
+
+ (struct cdrom_mcn)
+
+
+ usage::
+
+ struct cdrom_mcn mcn;
+
+ ioctl(fd, CDROM_GET_MCN, &mcn);
+
+ inputs:
+ none
+
+
+ outputs:
+ Universal Product Code
+
+
+ error return:
+ - ENOSYS Drive is not capable of reading MCN data.
+
+ notes:
+ - Source code comments state::
+
+ The following function is implemented, although very few
+ audio discs give Universal Product Code information, which
+ should just be the Medium Catalog Number on the box. Note,
+ that the way the code is written on the CD is /not/ uniform
+ across all discs!
+
+
+
+
+CDROM_GET_UPC
+ CDROM_GET_MCN (deprecated)
+
+
+ Not implemented, as of 2.6.8.1
+
+
+
+CDROMRESET
+ hard-reset the drive
+
+
+ usage::
+
+ ioctl(fd, CDROMRESET, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ none
+
+
+ error return:
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - ENOSYS Drive is not capable of resetting.
+
+
+
+
+CDROMREADCOOKED
+ read data in cooked mode
+
+
+ usage::
+
+ u8 buffer[CD_FRAMESIZE]
+
+ ioctl(fd, CDROMREADCOOKED, buffer);
+
+ inputs:
+ none
+
+
+ outputs:
+ 2048 bytes of data, "cooked" mode.
+
+
+ notes:
+ Not implemented on all drives.
+
+
+
+
+
+CDROMREADALL
+ read all 2646 bytes
+
+
+ Same as CDROMREADCOOKED, but reads 2646 bytes.
+
+
+
+CDROMSEEK
+ seek msf address
+
+
+ usage::
+
+ struct cdrom_msf msf;
+
+ ioctl(fd, CDROMSEEK, &msf);
+
+ inputs:
+ MSF address to seek to.
+
+
+ outputs:
+ none
+
+
+
+
+CDROMPLAYBLK
+ scsi-cd only
+
+ (struct cdrom_blk)
+
+
+ usage::
+
+ struct cdrom_blk blk;
+
+ ioctl(fd, CDROMPLAYBLK, &blk);
+
+ inputs:
+ Region to play
+
+
+ outputs:
+ none
+
+
+
+
+CDROMGETSPINDOWN
+ usage::
+
+ char spindown;
+
+ ioctl(fd, CDROMGETSPINDOWN, &spindown);
+
+ inputs:
+ none
+
+
+ outputs:
+ The value of the current 4-bit spindown value.
+
+
+
+
+
+CDROMSETSPINDOWN
+ usage::
+
+ char spindown
+
+ ioctl(fd, CDROMSETSPINDOWN, &spindown);
+
+ inputs:
+ 4-bit value used to control spindown (TODO: more detail here)
+
+
+ outputs:
+ none
+
+
+
+
+
+
+CDROM_SET_OPTIONS
+ Set behavior options
+
+
+ usage::
+
+ int options;
+
+ ioctl(fd, CDROM_SET_OPTIONS, options);
+
+ inputs:
+ New values for drive options. The logical 'or' of:
+
+ ============== ==================================
+ CDO_AUTO_CLOSE close tray on first open(2)
+ CDO_AUTO_EJECT open tray on last release
+ CDO_USE_FFLAGS use O_NONBLOCK information on open
+ CDO_LOCK lock tray on open files
+ CDO_CHECK_TYPE check type on open for data
+ ============== ==================================
+
+ outputs:
+ Returns the resulting options settings in the
+ ioctl return value. Returns -1 on error.
+
+ error return:
+ - ENOSYS selected option(s) not supported by drive.
+
+
+
+
+CDROM_CLEAR_OPTIONS
+ Clear behavior options
+
+
+ Same as CDROM_SET_OPTIONS, except that selected options are
+ turned off.
+
+
+
+CDROM_SELECT_SPEED
+ Set the CD-ROM speed
+
+
+ usage::
+
+ int speed;
+
+ ioctl(fd, CDROM_SELECT_SPEED, speed);
+
+ inputs:
+ New drive speed.
+
+
+ outputs:
+ none
+
+
+ error return:
+ - ENOSYS speed selection not supported by drive.
+
+
+
+CDROM_SELECT_DISC
+ Select disc (for juke-boxes)
+
+
+ usage::
+
+ int disk;
+
+ ioctl(fd, CDROM_SELECT_DISC, disk);
+
+ inputs:
+ Disk to load into drive.
+
+
+ outputs:
+ none
+
+
+ error return:
+ - EINVAL Disk number beyond capacity of drive
+
+
+
+CDROM_MEDIA_CHANGED
+ Check is media changed
+
+
+ usage::
+
+ int slot;
+
+ ioctl(fd, CDROM_MEDIA_CHANGED, slot);
+
+ inputs:
+ Slot number to be tested, always zero except for jukeboxes.
+
+ May also be special values CDSL_NONE or CDSL_CURRENT
+
+ outputs:
+ Ioctl return value is 0 or 1 depending on whether the media
+
+ has been changed, or -1 on error.
+
+ error returns:
+ - ENOSYS Drive can't detect media change
+ - EINVAL Slot number beyond capacity of drive
+ - ENOMEM Out of memory
+
+
+
+CDROM_DRIVE_STATUS
+ Get tray position, etc.
+
+
+ usage::
+
+ int slot;
+
+ ioctl(fd, CDROM_DRIVE_STATUS, slot);
+
+ inputs:
+ Slot number to be tested, always zero except for jukeboxes.
+
+ May also be special values CDSL_NONE or CDSL_CURRENT
+
+ outputs:
+ Ioctl return value will be one of the following values
+
+ from <linux/cdrom.h>:
+
+ =================== ==========================
+ CDS_NO_INFO Information not available.
+ CDS_NO_DISC
+ CDS_TRAY_OPEN
+ CDS_DRIVE_NOT_READY
+ CDS_DISC_OK
+ -1 error
+ =================== ==========================
+
+ error returns:
+ - ENOSYS Drive can't detect drive status
+ - EINVAL Slot number beyond capacity of drive
+ - ENOMEM Out of memory
+
+
+
+
+CDROM_DISC_STATUS
+ Get disc type, etc.
+
+
+ usage::
+
+ ioctl(fd, CDROM_DISC_STATUS, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ Ioctl return value will be one of the following values
+
+ from <linux/cdrom.h>:
+
+ - CDS_NO_INFO
+ - CDS_AUDIO
+ - CDS_MIXED
+ - CDS_XA_2_2
+ - CDS_XA_2_1
+ - CDS_DATA_1
+
+ error returns:
+ none at present
+
+ notes:
+ - Source code comments state::
+
+
+ Ok, this is where problems start. The current interface for
+ the CDROM_DISC_STATUS ioctl is flawed. It makes the false
+ assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
+ Unfortunately, while this is often the case, it is also
+ very common for CDs to have some tracks with data, and some
+ tracks with audio. Just because I feel like it, I declare
+ the following to be the best way to cope. If the CD has
+ ANY data tracks on it, it will be returned as a data CD.
+ If it has any XA tracks, I will return it as that. Now I
+ could simplify this interface by combining these returns with
+ the above, but this more clearly demonstrates the problem
+ with the current interface. Too bad this wasn't designed
+ to use bitmasks... -Erik
+
+ Well, now we have the option CDS_MIXED: a mixed-type CD.
+ User level programmers might feel the ioctl is not very
+ useful.
+ ---david
+
+
+
+
+CDROM_CHANGER_NSLOTS
+ Get number of slots
+
+
+ usage::
+
+ ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ The ioctl return value will be the number of slots in a
+ CD changer. Typically 1 for non-multi-disk devices.
+
+ error returns:
+ none
+
+
+
+CDROM_LOCKDOOR
+ lock or unlock door
+
+
+ usage::
+
+ int lock;
+
+ ioctl(fd, CDROM_LOCKDOOR, lock);
+
+ inputs:
+ Door lock flag, 1=lock, 0=unlock
+
+
+ outputs:
+ none
+
+
+ error returns:
+ - EDRIVE_CANT_DO_THIS
+
+ Door lock function not supported.
+ - EBUSY
+
+ Attempt to unlock when multiple users
+ have the drive open and not CAP_SYS_ADMIN
+
+ notes:
+ As of 2.6.8.1, the lock flag is a global lock, meaning that
+ all CD drives will be locked or unlocked together. This is
+ probably a bug.
+
+ The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
+ and is currently (2.6.8.1) the same as EOPNOTSUPP
+
+
+
+CDROM_DEBUG
+ Turn debug messages on/off
+
+
+ usage::
+
+ int debug;
+
+ ioctl(fd, CDROM_DEBUG, debug);
+
+ inputs:
+ Cdrom debug flag, 0=disable, 1=enable
+
+
+ outputs:
+ The ioctl return value will be the new debug flag.
+
+
+ error return:
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+
+
+
+CDROM_GET_CAPABILITY
+ get capabilities
+
+
+ usage::
+
+ ioctl(fd, CDROM_GET_CAPABILITY, 0);
+
+
+ inputs:
+ none
+
+
+ outputs:
+ The ioctl return value is the current device capability
+ flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
+
+
+
+CDROMAUDIOBUFSIZ
+ set the audio buffer size
+
+
+ usage::
+
+ int arg;
+
+ ioctl(fd, CDROMAUDIOBUFSIZ, val);
+
+ inputs:
+ New audio buffer size
+
+
+ outputs:
+ The ioctl return value is the new audio buffer size, or -1
+ on error.
+
+ error return:
+ - ENOSYS Not supported by this driver.
+
+ notes:
+ Not supported by all drivers.
+
+
+
+
+DVD_READ_STRUCT Read structure
+
+ usage::
+
+ dvd_struct s;
+
+ ioctl(fd, DVD_READ_STRUCT, &s);
+
+ inputs:
+ dvd_struct structure, containing:
+
+ =================== ==========================================
+ type specifies the information desired, one of
+ DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
+ DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,
+ DVD_STRUCT_MANUFACT
+ physical.layer_num desired layer, indexed from 0
+ copyright.layer_num desired layer, indexed from 0
+ disckey.agid
+ =================== ==========================================
+
+ outputs:
+ dvd_struct structure, containing:
+
+ =================== ================================
+ physical for type == DVD_STRUCT_PHYSICAL
+ copyright for type == DVD_STRUCT_COPYRIGHT
+ disckey.value for type == DVD_STRUCT_DISCKEY
+ bca.{len,value} for type == DVD_STRUCT_BCA
+ manufact.{len,valu} for type == DVD_STRUCT_MANUFACT
+ =================== ================================
+
+ error returns:
+ - EINVAL physical.layer_num exceeds number of layers
+ - EIO Received invalid response from drive
+
+
+
+DVD_WRITE_STRUCT Write structure
+
+ Not implemented, as of 2.6.8.1
+
+
+
+DVD_AUTH Authentication
+
+ usage::
+
+ dvd_authinfo ai;
+
+ ioctl(fd, DVD_AUTH, &ai);
+
+ inputs:
+ dvd_authinfo structure. See <linux/cdrom.h>
+
+
+ outputs:
+ dvd_authinfo structure.
+
+
+ error return:
+ - ENOTTY ai.type not recognized.
+
+
+
+CDROM_SEND_PACKET
+ send a packet to the drive
+
+
+ usage::
+
+ struct cdrom_generic_command cgc;
+
+ ioctl(fd, CDROM_SEND_PACKET, &cgc);
+
+ inputs:
+ cdrom_generic_command structure containing the packet to send.
+
+
+ outputs:
+ none
+
+ cdrom_generic_command structure containing results.
+
+ error return:
+ - EIO
+
+ command failed.
+ - EPERM
+
+ Operation not permitted, either because a
+ write command was attempted on a drive which
+ is opened read-only, or because the command
+ requires CAP_SYS_RAWIO
+ - EINVAL
+
+ cgc.data_direction not set
+
+
+
+CDROM_NEXT_WRITABLE
+ get next writable block
+
+
+ usage::
+
+ long next;
+
+ ioctl(fd, CDROM_NEXT_WRITABLE, &next);
+
+ inputs:
+ none
+
+
+ outputs:
+ The next writable block.
+
+
+ notes:
+ If the device does not support this ioctl directly, the
+
+ ioctl will return CDROM_LAST_WRITTEN + 7.
+
+
+
+CDROM_LAST_WRITTEN
+ get last block written on disc
+
+
+ usage::
+
+ long last;
+
+ ioctl(fd, CDROM_LAST_WRITTEN, &last);
+
+ inputs:
+ none
+
+
+ outputs:
+ The last block written on disc
+
+
+ notes:
+ If the device does not support this ioctl directly, the
+ result is derived from the disc's table of contents. If the
+ table of contents can't be read, this ioctl returns an
+ error.
diff --git a/Documentation/ioctl/cdrom.txt b/Documentation/ioctl/cdrom.txt
deleted file mode 100644
index a4d62a9d6771..000000000000
--- a/Documentation/ioctl/cdrom.txt
+++ /dev/null
@@ -1,967 +0,0 @@
- Summary of CDROM ioctl calls.
- ============================
-
- Edward A. Falk <efalk@google.com>
-
- November, 2004
-
-This document attempts to describe the ioctl(2) calls supported by
-the CDROM layer. These are by-and-large implemented (as of Linux 2.6)
-in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c
-
-ioctl values are listed in <linux/cdrom.h>. As of this writing, they
-are as follows:
-
- CDROMPAUSE Pause Audio Operation
- CDROMRESUME Resume paused Audio Operation
- CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
- CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti)
- CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr)
- CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry)
- CDROMSTOP Stop the cdrom drive
- CDROMSTART Start the cdrom drive
- CDROMEJECT Ejects the cdrom media
- CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
- CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
- CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
- (struct cdrom_read)
- CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
- (struct cdrom_read)
- CDROMREADAUDIO (struct cdrom_read_audio)
- CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
- CDROMMULTISESSION Obtain the start-of-last-session
- address of multi session disks
- (struct cdrom_multisession)
- CDROM_GET_MCN Obtain the "Universal Product Code"
- if available (struct cdrom_mcn)
- CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead.
- CDROMRESET hard-reset the drive
- CDROMVOLREAD Get the drive's volume setting
- (struct cdrom_volctrl)
- CDROMREADRAW read data in raw mode (2352 Bytes)
- (struct cdrom_read)
- CDROMREADCOOKED read data in cooked mode
- CDROMSEEK seek msf address
- CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
- CDROMREADALL read all 2646 bytes
- CDROMGETSPINDOWN return 4-bit spindown value
- CDROMSETSPINDOWN set 4-bit spindown value
- CDROMCLOSETRAY pendant of CDROMEJECT
- CDROM_SET_OPTIONS Set behavior options
- CDROM_CLEAR_OPTIONS Clear behavior options
- CDROM_SELECT_SPEED Set the CD-ROM speed
- CDROM_SELECT_DISC Select disc (for juke-boxes)
- CDROM_MEDIA_CHANGED Check is media changed
- CDROM_DRIVE_STATUS Get tray position, etc.
- CDROM_DISC_STATUS Get disc type, etc.
- CDROM_CHANGER_NSLOTS Get number of slots
- CDROM_LOCKDOOR lock or unlock door
- CDROM_DEBUG Turn debug messages on/off
- CDROM_GET_CAPABILITY get capabilities
- CDROMAUDIOBUFSIZ set the audio buffer size
- DVD_READ_STRUCT Read structure
- DVD_WRITE_STRUCT Write structure
- DVD_AUTH Authentication
- CDROM_SEND_PACKET send a packet to the drive
- CDROM_NEXT_WRITABLE get next writable block
- CDROM_LAST_WRITTEN get last block written on disc
-
-
-The information that follows was determined from reading kernel source
-code. It is likely that some corrections will be made over time.
-
-
-
-
-
-
-
-General:
-
- Unless otherwise specified, all ioctl calls return 0 on success
- and -1 with errno set to an appropriate value on error. (Some
- ioctls return non-negative data values.)
-
- Unless otherwise specified, all ioctl calls return -1 and set
- errno to EFAULT on a failed attempt to copy data to or from user
- address space.
-
- Individual drivers may return error codes not listed here.
-
- Unless otherwise specified, all data structures and constants
- are defined in <linux/cdrom.h>
-
-
-
-
-CDROMPAUSE Pause Audio Operation
-
- usage:
-
- ioctl(fd, CDROMPAUSE, 0);
-
- inputs: none
-
- outputs: none
-
- error return:
- ENOSYS cd drive not audio-capable.
-
-
-CDROMRESUME Resume paused Audio Operation
-
- usage:
-
- ioctl(fd, CDROMRESUME, 0);
-
- inputs: none
-
- outputs: none
-
- error return:
- ENOSYS cd drive not audio-capable.
-
-
-CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
-
- usage:
-
- struct cdrom_msf msf;
- ioctl(fd, CDROMPLAYMSF, &msf);
-
- inputs:
- cdrom_msf structure, describing a segment of music to play
-
- outputs: none
-
- error return:
- ENOSYS cd drive not audio-capable.
-
- notes:
- MSF stands for minutes-seconds-frames
- LBA stands for logical block address
-
- Segment is described as start and end times, where each time
- is described as minutes:seconds:frames. A frame is 1/75 of
- a second.
-
-
-CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti)
-
- usage:
-
- struct cdrom_ti ti;
- ioctl(fd, CDROMPLAYTRKIND, &ti);
-
- inputs:
- cdrom_ti structure, describing a segment of music to play
-
- outputs: none
-
- error return:
- ENOSYS cd drive not audio-capable.
-
- notes:
- Segment is described as start and end times, where each time
- is described as a track and an index.
-
-
-
-CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr)
-
- usage:
-
- cdrom_tochdr header;
- ioctl(fd, CDROMREADTOCHDR, &header);
-
- inputs:
- cdrom_tochdr structure
-
- outputs:
- cdrom_tochdr structure
-
- error return:
- ENOSYS cd drive not audio-capable.
-
-
-
-CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry)
-
- usage:
-
- struct cdrom_tocentry entry;
- ioctl(fd, CDROMREADTOCENTRY, &entry);
-
- inputs:
- cdrom_tocentry structure
-
- outputs:
- cdrom_tocentry structure
-
- error return:
- ENOSYS cd drive not audio-capable.
- EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA
- EINVAL requested track out of bounds
- EIO I/O error reading TOC
-
- notes:
- TOC stands for Table Of Contents
- MSF stands for minutes-seconds-frames
- LBA stands for logical block address
-
-
-
-CDROMSTOP Stop the cdrom drive
-
- usage:
-
- ioctl(fd, CDROMSTOP, 0);
-
- inputs: none
-
- outputs: none
-
- error return:
- ENOSYS cd drive not audio-capable.
-
- notes:
- Exact interpretation of this ioctl depends on the device,
- but most seem to spin the drive down.
-
-
-CDROMSTART Start the cdrom drive
-
- usage:
-
- ioctl(fd, CDROMSTART, 0);
-
- inputs: none
-
- outputs: none
-
- error return:
- ENOSYS cd drive not audio-capable.
-
- notes:
- Exact interpretation of this ioctl depends on the device,
- but most seem to spin the drive up and/or close the tray.
- Other devices ignore the ioctl completely.
-
-
-CDROMEJECT Ejects the cdrom media
-
- usage:
-
- ioctl(fd, CDROMEJECT, 0);
-
- inputs: none
-
- outputs: none
-
- error returns:
- ENOSYS cd drive not capable of ejecting
- EBUSY other processes are accessing drive, or door is locked
-
- notes:
- See CDROM_LOCKDOOR, below.
-
-
-
-CDROMCLOSETRAY pendant of CDROMEJECT
-
- usage:
-
- ioctl(fd, CDROMCLOSETRAY, 0);
-
- inputs: none
-
- outputs: none
-
- error returns:
- ENOSYS cd drive not capable of closing the tray
- EBUSY other processes are accessing drive, or door is locked
-
- notes:
- See CDROM_LOCKDOOR, below.
-
-
-
-CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
-
- usage:
-
- struct cdrom_volctrl volume;
- ioctl(fd, CDROMVOLCTRL, &volume);
-
- inputs:
- cdrom_volctrl structure containing volumes for up to 4
- channels.
-
- outputs: none
-
- error return:
- ENOSYS cd drive not audio-capable.
-
-
-
-CDROMVOLREAD Get the drive's volume setting
- (struct cdrom_volctrl)
-
- usage:
-
- struct cdrom_volctrl volume;
- ioctl(fd, CDROMVOLREAD, &volume);
-
- inputs: none
-
- outputs:
- The current volume settings.
-
- error return:
- ENOSYS cd drive not audio-capable.
-
-
-
-CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
-
- usage:
-
- struct cdrom_subchnl q;
- ioctl(fd, CDROMSUBCHNL, &q);
-
- inputs:
- cdrom_subchnl structure
-
- outputs:
- cdrom_subchnl structure
-
- error return:
- ENOSYS cd drive not audio-capable.
- EINVAL format not CDROM_MSF or CDROM_LBA
-
- notes:
- Format is converted to CDROM_MSF or CDROM_LBA
- as per user request on return
-
-
-
-CDROMREADRAW read data in raw mode (2352 Bytes)
- (struct cdrom_read)
-
- usage:
-
- union {
- struct cdrom_msf msf; /* input */
- char buffer[CD_FRAMESIZE_RAW]; /* return */
- } arg;
- ioctl(fd, CDROMREADRAW, &arg);
-
- inputs:
- cdrom_msf structure indicating an address to read.
- Only the start values are significant.
-
- outputs:
- Data written to address provided by user.
-
- error return:
- EINVAL address less than 0, or msf less than 0:2:0
- ENOMEM out of memory
-
- notes:
- As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
- ioctl accepts a cdrom_read structure, but actual source code
- reads a cdrom_msf structure and writes a buffer of data to
- the same address.
-
- MSF values are converted to LBA values via this formula:
-
- lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
-
-
-
-
-CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
- (struct cdrom_read)
-
- notes:
- Identical to CDROMREADRAW except that block size is
- CD_FRAMESIZE (2048) bytes
-
-
-
-CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
- (struct cdrom_read)
-
- notes:
- Identical to CDROMREADRAW except that block size is
- CD_FRAMESIZE_RAW0 (2336) bytes
-
-
-
-CDROMREADAUDIO (struct cdrom_read_audio)
-
- usage:
-
- struct cdrom_read_audio ra;
- ioctl(fd, CDROMREADAUDIO, &ra);
-
- inputs:
- cdrom_read_audio structure containing read start
- point and length
-
- outputs:
- audio data, returned to buffer indicated by ra
-
- error return:
- EINVAL format not CDROM_MSF or CDROM_LBA
- EINVAL nframes not in range [1 75]
- ENXIO drive has no queue (probably means invalid fd)
- ENOMEM out of memory
-
-
-CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
-
- usage:
-
- int val;
- ioctl(fd, CDROMEJECT_SW, val);
-
- inputs:
- Flag specifying auto-eject flag.
-
- outputs: none
-
- error return:
- ENOSYS Drive is not capable of ejecting.
- EBUSY Door is locked
-
-
-
-
-CDROMMULTISESSION Obtain the start-of-last-session
- address of multi session disks
- (struct cdrom_multisession)
- usage:
-
- struct cdrom_multisession ms_info;
- ioctl(fd, CDROMMULTISESSION, &ms_info);
-
- inputs:
- cdrom_multisession structure containing desired
- format.
-
- outputs:
- cdrom_multisession structure is filled with last_session
- information.
-
- error return:
- EINVAL format not CDROM_MSF or CDROM_LBA
-
-
-CDROM_GET_MCN Obtain the "Universal Product Code"
- if available (struct cdrom_mcn)
-
- usage:
-
- struct cdrom_mcn mcn;
- ioctl(fd, CDROM_GET_MCN, &mcn);
-
- inputs: none
-
- outputs:
- Universal Product Code
-
- error return:
- ENOSYS Drive is not capable of reading MCN data.
-
- notes:
- Source code comments state:
-
- The following function is implemented, although very few
- audio discs give Universal Product Code information, which
- should just be the Medium Catalog Number on the box. Note,
- that the way the code is written on the CD is /not/ uniform
- across all discs!
-
-
-
-
-CDROM_GET_UPC CDROM_GET_MCN (deprecated)
-
- Not implemented, as of 2.6.8.1
-
-
-
-CDROMRESET hard-reset the drive
-
- usage:
-
- ioctl(fd, CDROMRESET, 0);
-
- inputs: none
-
- outputs: none
-
- error return:
- EACCES Access denied: requires CAP_SYS_ADMIN
- ENOSYS Drive is not capable of resetting.
-
-
-
-
-CDROMREADCOOKED read data in cooked mode
-
- usage:
-
- u8 buffer[CD_FRAMESIZE]
- ioctl(fd, CDROMREADCOOKED, buffer);
-
- inputs: none
-
- outputs:
- 2048 bytes of data, "cooked" mode.
-
- notes:
- Not implemented on all drives.
-
-
-
-
-CDROMREADALL read all 2646 bytes
-
- Same as CDROMREADCOOKED, but reads 2646 bytes.
-
-
-
-CDROMSEEK seek msf address
-
- usage:
-
- struct cdrom_msf msf;
- ioctl(fd, CDROMSEEK, &msf);
-
- inputs:
- MSF address to seek to.
-
- outputs: none
-
-
-
-CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
-
- usage:
-
- struct cdrom_blk blk;
- ioctl(fd, CDROMPLAYBLK, &blk);
-
- inputs:
- Region to play
-
- outputs: none
-
-
-
-CDROMGETSPINDOWN
-
- usage:
-
- char spindown;
- ioctl(fd, CDROMGETSPINDOWN, &spindown);
-
- inputs: none
-
- outputs:
- The value of the current 4-bit spindown value.
-
-
-
-
-CDROMSETSPINDOWN
-
- usage:
-
- char spindown
- ioctl(fd, CDROMSETSPINDOWN, &spindown);
-
- inputs:
- 4-bit value used to control spindown (TODO: more detail here)
-
- outputs: none
-
-
-
-
-
-CDROM_SET_OPTIONS Set behavior options
-
- usage:
-
- int options;
- ioctl(fd, CDROM_SET_OPTIONS, options);
-
- inputs:
- New values for drive options. The logical 'or' of:
- CDO_AUTO_CLOSE close tray on first open(2)
- CDO_AUTO_EJECT open tray on last release
- CDO_USE_FFLAGS use O_NONBLOCK information on open
- CDO_LOCK lock tray on open files
- CDO_CHECK_TYPE check type on open for data
-
- outputs:
- Returns the resulting options settings in the
- ioctl return value. Returns -1 on error.
-
- error return:
- ENOSYS selected option(s) not supported by drive.
-
-
-
-
-CDROM_CLEAR_OPTIONS Clear behavior options
-
- Same as CDROM_SET_OPTIONS, except that selected options are
- turned off.
-
-
-
-CDROM_SELECT_SPEED Set the CD-ROM speed
-
- usage:
-
- int speed;
- ioctl(fd, CDROM_SELECT_SPEED, speed);
-
- inputs:
- New drive speed.
-
- outputs: none
-
- error return:
- ENOSYS speed selection not supported by drive.
-
-
-
-CDROM_SELECT_DISC Select disc (for juke-boxes)
-
- usage:
-
- int disk;
- ioctl(fd, CDROM_SELECT_DISC, disk);
-
- inputs:
- Disk to load into drive.
-
- outputs: none
-
- error return:
- EINVAL Disk number beyond capacity of drive
-
-
-
-CDROM_MEDIA_CHANGED Check is media changed
-
- usage:
-
- int slot;
- ioctl(fd, CDROM_MEDIA_CHANGED, slot);
-
- inputs:
- Slot number to be tested, always zero except for jukeboxes.
- May also be special values CDSL_NONE or CDSL_CURRENT
-
- outputs:
- Ioctl return value is 0 or 1 depending on whether the media
- has been changed, or -1 on error.
-
- error returns:
- ENOSYS Drive can't detect media change
- EINVAL Slot number beyond capacity of drive
- ENOMEM Out of memory
-
-
-
-CDROM_DRIVE_STATUS Get tray position, etc.
-
- usage:
-
- int slot;
- ioctl(fd, CDROM_DRIVE_STATUS, slot);
-
- inputs:
- Slot number to be tested, always zero except for jukeboxes.
- May also be special values CDSL_NONE or CDSL_CURRENT
-
- outputs:
- Ioctl return value will be one of the following values
- from <linux/cdrom.h>:
-
- CDS_NO_INFO Information not available.
- CDS_NO_DISC
- CDS_TRAY_OPEN
- CDS_DRIVE_NOT_READY
- CDS_DISC_OK
- -1 error
-
- error returns:
- ENOSYS Drive can't detect drive status
- EINVAL Slot number beyond capacity of drive
- ENOMEM Out of memory
-
-
-
-
-CDROM_DISC_STATUS Get disc type, etc.
-
- usage:
-
- ioctl(fd, CDROM_DISC_STATUS, 0);
-
- inputs: none
-
- outputs:
- Ioctl return value will be one of the following values
- from <linux/cdrom.h>:
- CDS_NO_INFO
- CDS_AUDIO
- CDS_MIXED
- CDS_XA_2_2
- CDS_XA_2_1
- CDS_DATA_1
-
- error returns: none at present
-
- notes:
- Source code comments state:
-
- Ok, this is where problems start. The current interface for
- the CDROM_DISC_STATUS ioctl is flawed. It makes the false
- assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
- Unfortunately, while this is often the case, it is also
- very common for CDs to have some tracks with data, and some
- tracks with audio. Just because I feel like it, I declare
- the following to be the best way to cope. If the CD has
- ANY data tracks on it, it will be returned as a data CD.
- If it has any XA tracks, I will return it as that. Now I
- could simplify this interface by combining these returns with
- the above, but this more clearly demonstrates the problem
- with the current interface. Too bad this wasn't designed
- to use bitmasks... -Erik
-
- Well, now we have the option CDS_MIXED: a mixed-type CD.
- User level programmers might feel the ioctl is not very
- useful.
- ---david
-
-
-
-
-CDROM_CHANGER_NSLOTS Get number of slots
-
- usage:
-
- ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
-
- inputs: none
-
- outputs:
- The ioctl return value will be the number of slots in a
- CD changer. Typically 1 for non-multi-disk devices.
-
- error returns: none
-
-
-
-CDROM_LOCKDOOR lock or unlock door
-
- usage:
-
- int lock;
- ioctl(fd, CDROM_LOCKDOOR, lock);
-
- inputs:
- Door lock flag, 1=lock, 0=unlock
-
- outputs: none
-
- error returns:
- EDRIVE_CANT_DO_THIS Door lock function not supported.
- EBUSY Attempt to unlock when multiple users
- have the drive open and not CAP_SYS_ADMIN
-
- notes:
- As of 2.6.8.1, the lock flag is a global lock, meaning that
- all CD drives will be locked or unlocked together. This is
- probably a bug.
-
- The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
- and is currently (2.6.8.1) the same as EOPNOTSUPP
-
-
-
-CDROM_DEBUG Turn debug messages on/off
-
- usage:
-
- int debug;
- ioctl(fd, CDROM_DEBUG, debug);
-
- inputs:
- Cdrom debug flag, 0=disable, 1=enable
-
- outputs:
- The ioctl return value will be the new debug flag.
-
- error return:
- EACCES Access denied: requires CAP_SYS_ADMIN
-
-
-
-CDROM_GET_CAPABILITY get capabilities
-
- usage:
-
- ioctl(fd, CDROM_GET_CAPABILITY, 0);
-
- inputs: none
-
- outputs:
- The ioctl return value is the current device capability
- flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
-
-
-
-CDROMAUDIOBUFSIZ set the audio buffer size
-
- usage:
-
- int arg;
- ioctl(fd, CDROMAUDIOBUFSIZ, val);
-
- inputs:
- New audio buffer size
-
- outputs:
- The ioctl return value is the new audio buffer size, or -1
- on error.
-
- error return:
- ENOSYS Not supported by this driver.
-
- notes:
- Not supported by all drivers.
-
-
-
-DVD_READ_STRUCT Read structure
-
- usage:
-
- dvd_struct s;
- ioctl(fd, DVD_READ_STRUCT, &s);
-
- inputs:
- dvd_struct structure, containing:
- type specifies the information desired, one of
- DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
- DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,
- DVD_STRUCT_MANUFACT
- physical.layer_num desired layer, indexed from 0
- copyright.layer_num desired layer, indexed from 0
- disckey.agid
-
- outputs:
- dvd_struct structure, containing:
- physical for type == DVD_STRUCT_PHYSICAL
- copyright for type == DVD_STRUCT_COPYRIGHT
- disckey.value for type == DVD_STRUCT_DISCKEY
- bca.{len,value} for type == DVD_STRUCT_BCA
- manufact.{len,valu} for type == DVD_STRUCT_MANUFACT
-
- error returns:
- EINVAL physical.layer_num exceeds number of layers
- EIO Received invalid response from drive
-
-
-
-DVD_WRITE_STRUCT Write structure
-
- Not implemented, as of 2.6.8.1
-
-
-
-DVD_AUTH Authentication
-
- usage:
-
- dvd_authinfo ai;
- ioctl(fd, DVD_AUTH, &ai);
-
- inputs:
- dvd_authinfo structure. See <linux/cdrom.h>
-
- outputs:
- dvd_authinfo structure.
-
- error return:
- ENOTTY ai.type not recognized.
-
-
-
-CDROM_SEND_PACKET send a packet to the drive
-
- usage:
-
- struct cdrom_generic_command cgc;
- ioctl(fd, CDROM_SEND_PACKET, &cgc);
-
- inputs:
- cdrom_generic_command structure containing the packet to send.
-
- outputs: none
- cdrom_generic_command structure containing results.
-
- error return:
- EIO command failed.
- EPERM Operation not permitted, either because a
- write command was attempted on a drive which
- is opened read-only, or because the command
- requires CAP_SYS_RAWIO
- EINVAL cgc.data_direction not set
-
-
-
-CDROM_NEXT_WRITABLE get next writable block
-
- usage:
-
- long next;
- ioctl(fd, CDROM_NEXT_WRITABLE, &next);
-
- inputs: none
-
- outputs:
- The next writable block.
-
- notes:
- If the device does not support this ioctl directly, the
- ioctl will return CDROM_LAST_WRITTEN + 7.
-
-
-
-CDROM_LAST_WRITTEN get last block written on disc
-
- usage:
-
- long last;
- ioctl(fd, CDROM_LAST_WRITTEN, &last);
-
- inputs: none
-
- outputs:
- The last block written on disc
-
- notes:
- If the device does not support this ioctl directly, the
- result is derived from the disc's table of contents. If the
- table of contents can't be read, this ioctl returns an
- error.
diff --git a/Documentation/ioctl/hdio.txt b/Documentation/ioctl/hdio.rst
similarity index 54%
rename from Documentation/ioctl/hdio.txt
rename to Documentation/ioctl/hdio.rst
index 18eb98c44ffe..e822e3dff176 100644
--- a/Documentation/ioctl/hdio.txt
+++ b/Documentation/ioctl/hdio.rst
@@ -1,9 +1,10 @@
- Summary of HDIO_ ioctl calls.
- ============================
+==============================
+Summary of `HDIO_` ioctl calls
+==============================
- Edward A. Falk <efalk@google.com>
+- Edward A. Falk <efalk@google.com>
- November, 2004
+November, 2004
This document attempts to describe the ioctl(2) calls supported by
the HD/IDE layer. These are by-and-large implemented (as of Linux 2.6)
@@ -14,6 +15,7 @@ are as follows:
ioctls that pass argument pointers to user space:
+ ======================= =======================================
HDIO_GETGEO get device geometry
HDIO_GET_UNMASKINTR get current unmask setting
HDIO_GET_MULTCOUNT get current IDE blockmode setting
@@ -36,9 +38,11 @@ are as follows:
HDIO_DRIVE_TASK execute task and special drive command
HDIO_DRIVE_CMD execute a special drive command
HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK
+ ======================= =======================================
ioctls that pass non-pointer values:
+ ======================= =======================================
HDIO_SET_MULTCOUNT change IDE blockmode
HDIO_SET_UNMASKINTR permit other irqs during I/O
HDIO_SET_KEEPSETTINGS keep ioctl settings on reset
@@ -57,16 +61,13 @@ are as follows:
HDIO_SET_IDE_SCSI Set scsi emulation mode on/off
HDIO_SET_SCSI_IDE not implemented yet
+ ======================= =======================================
The information that follows was determined from reading kernel source
code. It is likely that some corrections will be made over time.
-
-
-
-
-
+------------------------------------------------------------------------------
General:
@@ -80,459 +81,610 @@ General:
Unless otherwise specified, all data structures and constants
are defined in <linux/hdreg.h>
+------------------------------------------------------------------------------
+HDIO_GETGEO
+ get device geometry
-HDIO_GETGEO get device geometry
- usage:
+ usage::
struct hd_geometry geom;
+
ioctl(fd, HDIO_GETGEO, &geom);
- inputs: none
+ inputs:
+ none
+
+
outputs:
+ hd_geometry structure containing:
- hd_geometry structure containing:
+ ========= ==================================
heads number of heads
sectors number of sectors/track
cylinders number of cylinders, mod 65536
start starting sector of this partition.
+ ========= ==================================
error returns:
- EINVAL if the device is not a disk drive or floppy drive,
- or if the user passes a null pointer
+ - EINVAL
+
+ if the device is not a disk drive or floppy drive,
+ or if the user passes a null pointer
notes:
+ Not particularly useful with modern disk drives, whose geometry
+ is a polite fiction anyway. Modern drives are addressed
+ purely by sector number nowadays (lba addressing), and the
+ drive geometry is an abstraction which is actually subject
+ to change. Currently (as of Nov 2004), the geometry values
+ are the "bios" values -- presumably the values the drive had
+ when Linux first booted.
- Not particularly useful with modern disk drives, whose geometry
- is a polite fiction anyway. Modern drives are addressed
- purely by sector number nowadays (lba addressing), and the
- drive geometry is an abstraction which is actually subject
- to change. Currently (as of Nov 2004), the geometry values
- are the "bios" values -- presumably the values the drive had
- when Linux first booted.
+ In addition, the cylinders field of the hd_geometry is an
+ unsigned short, meaning that on most architectures, this
+ ioctl will not return a meaningful value on drives with more
+ than 65535 tracks.
- In addition, the cylinders field of the hd_geometry is an
- unsigned short, meaning that on most architectures, this
- ioctl will not return a meaningful value on drives with more
- than 65535 tracks.
+ The start field is unsigned long, meaning that it will not
+ contain a meaningful value for disks over 219 Gb in size.
- The start field is unsigned long, meaning that it will not
- contain a meaningful value for disks over 219 Gb in size.
+HDIO_GET_UNMASKINTR
+ get current unmask setting
-HDIO_GET_UNMASKINTR get current unmask setting
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_GET_UNMASKINTR, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the drive's current unmask setting
+ The value of the drive's current unmask setting
-HDIO_SET_UNMASKINTR permit other irqs during I/O
- usage:
+
+HDIO_SET_UNMASKINTR
+ permit other irqs during I/O
+
+
+ usage::
unsigned long val;
+
ioctl(fd, HDIO_SET_UNMASKINTR, val);
inputs:
- New value for unmask flag
+ New value for unmask flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_GET_MULTCOUNT get current IDE blockmode setting
+HDIO_GET_MULTCOUNT
+ get current IDE blockmode setting
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_MULTCOUNT, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current IDE block mode setting. This
- controls how many sectors the drive will transfer per
- interrupt.
+ The value of the current IDE block mode setting. This
+ controls how many sectors the drive will transfer per
+ interrupt.
-HDIO_SET_MULTCOUNT change IDE blockmode
+HDIO_SET_MULTCOUNT
+ change IDE blockmode
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_MULTCOUNT, val);
inputs:
- New value for IDE block mode setting. This controls how many
- sectors the drive will transfer per interrupt.
+ New value for IDE block mode setting. This controls how many
+ sectors the drive will transfer per interrupt.
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range supported by disk.
- EBUSY Controller busy or blockmode already set.
- EIO Drive did not accept new block mode.
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range supported by disk.
+ - EBUSY Controller busy or blockmode already set.
+ - EIO Drive did not accept new block mode.
notes:
-
- Source code comments read:
+ Source code comments read::
This is tightly woven into the driver->do_special cannot
touch. DON'T do it again until a total personality rewrite
is committed.
If blockmode has already been set, this ioctl will fail with
- EBUSY
+ -EBUSY
-HDIO_GET_QDMA get use-qdma flag
+HDIO_GET_QDMA
+ get use-qdma flag
+
Not implemented, as of 2.6.8.1
-HDIO_SET_XFER set transfer rate via proc
+HDIO_SET_XFER
+ set transfer rate via proc
+
Not implemented, as of 2.6.8.1
-HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE
+HDIO_OBSOLETE_IDENTITY
+ OBSOLETE, DO NOT USE
+
Same as HDIO_GET_IDENTITY (see below), except that it only
returns the first 142 bytes of drive identity information.
-HDIO_GET_IDENTITY get IDE identification info
+HDIO_GET_IDENTITY
+ get IDE identification info
- usage:
+
+ usage::
unsigned char identity[512];
+
ioctl(fd, HDIO_GET_IDENTITY, identity);
- inputs: none
+ inputs:
+ none
+
+
outputs:
-
- ATA drive identity information. For full description, see
- the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
- the ATA specification.
+ ATA drive identity information. For full description, see
+ the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
+ the ATA specification.
error returns:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- ENOMSG IDENTIFY DEVICE information not available
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - ENOMSG IDENTIFY DEVICE information not available
notes:
+ Returns information that was obtained when the drive was
+ probed. Some of this information is subject to change, and
+ this ioctl does not re-probe the drive to update the
+ information.
- Returns information that was obtained when the drive was
- probed. Some of this information is subject to change, and
- this ioctl does not re-probe the drive to update the
- information.
+ This information is also available from /proc/ide/hdX/identify
- This information is also available from /proc/ide/hdX/identify
+HDIO_GET_KEEPSETTINGS
+ get keep-settings-on-reset flag
-HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current "keep settings" flag
+ The value of the current "keep settings" flag
+
+
notes:
+ When set, indicates that kernel should restore settings
+ after a drive reset.
- When set, indicates that kernel should restore settings
- after a drive reset.
+HDIO_SET_KEEPSETTINGS
+ keep ioctl settings on reset
-HDIO_SET_KEEPSETTINGS keep ioctl settings on reset
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
inputs:
- New value for keep_settings flag
+ New value for keep_settings flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_GET_32BIT get current io_32bit setting
+HDIO_GET_32BIT
+ get current io_32bit setting
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_32BIT, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current io_32bit setting
+ The value of the current io_32bit setting
+
+
notes:
+ 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
- 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
-HDIO_GET_NOWERR get ignore-write-error flag
- usage:
+HDIO_GET_NOWERR
+ get ignore-write-error flag
+
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_NOWERR, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current ignore-write-error flag
+ The value of the current ignore-write-error flag
-HDIO_GET_DMA get use-dma flag
- usage:
+
+HDIO_GET_DMA
+ get use-dma flag
+
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_DMA, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current use-dma flag
+ The value of the current use-dma flag
-HDIO_GET_NICE get nice flags
- usage:
+
+HDIO_GET_NICE
+ get nice flags
+
+
+ usage::
long nice;
+
ioctl(fd, HDIO_GET_NICE, &nice);
- inputs: none
+ inputs:
+ none
+
+
outputs:
+ The drive's "nice" values.
+
- The drive's "nice" values.
notes:
+ Per-drive flags which determine when the system will give more
+ bandwidth to other devices sharing the same IDE bus.
- Per-drive flags which determine when the system will give more
- bandwidth to other devices sharing the same IDE bus.
- See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
+ See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
-HDIO_SET_NICE set nice flags
+HDIO_SET_NICE
+ set nice flags
- usage:
+
+ usage::
unsigned long nice;
+
...
ioctl(fd, HDIO_SET_NICE, nice);
inputs:
- bitmask of nice flags.
+ bitmask of nice flags.
+
+
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_ADMIN
- EPERM Flags other than DSC_OVERLAP and NICE_1 set.
- EPERM DSC_OVERLAP specified but not supported by drive
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EPERM Flags other than DSC_OVERLAP and NICE_1 set.
+ - EPERM DSC_OVERLAP specified but not supported by drive
notes:
+ This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
+ provided by the user.
- This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
- provided by the user.
+ Nice flags are listed in <linux/hdreg.h>, starting with
+ IDE_NICE_DSC_OVERLAP. These values represent shifts.
- Nice flags are listed in <linux/hdreg.h>, starting with
- IDE_NICE_DSC_OVERLAP. These values represent shifts.
+HDIO_GET_WCACHE
+ get write cache mode on|off
-HDIO_GET_WCACHE get write cache mode on|off
- usage:
+ usage::
long val;
+
ioctl(fd, HDIO_GET_WCACHE, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current write cache mode
+ The value of the current write cache mode
-HDIO_GET_ACOUSTIC get acoustic value
- usage:
+
+HDIO_GET_ACOUSTIC
+ get acoustic value
+
+
+ usage::
long val;
+
ioctl(fd, HDIO_GET_ACOUSTIC, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current acoustic settings
+ The value of the current acoustic settings
+
+
notes:
+ See HDIO_SET_ACOUSTIC
+
- See HDIO_SET_ACOUSTIC
HDIO_GET_ADDRESS
+ usage::
- usage:
long val;
+
ioctl(fd, HDIO_GET_ADDRESS, &val);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- The value of the current addressing mode:
- 0 = 28-bit
- 1 = 48-bit
- 2 = 48-bit doing 28-bit
- 3 = 64-bit
+ The value of the current addressing mode:
+ = ===================
+ 0 28-bit
+ 1 48-bit
+ 2 48-bit doing 28-bit
+ 3 64-bit
+ = ===================
-HDIO_GET_BUSSTATE get the bus state of the hwif
- usage:
+HDIO_GET_BUSSTATE
+ get the bus state of the hwif
+
+
+ usage::
long state;
+
ioctl(fd, HDIO_SCAN_HWIF, &state);
- inputs: none
+ inputs:
+ none
+
+
outputs:
- Current power state of the IDE bus. One of BUSSTATE_OFF,
- BUSSTATE_ON, or BUSSTATE_TRISTATE
+ Current power state of the IDE bus. One of BUSSTATE_OFF,
+ BUSSTATE_ON, or BUSSTATE_TRISTATE
error returns:
- EACCES Access denied: requires CAP_SYS_ADMIN
+ - EACCES Access denied: requires CAP_SYS_ADMIN
-HDIO_SET_BUSSTATE set the bus state of the hwif
+HDIO_SET_BUSSTATE
+ set the bus state of the hwif
- usage:
+
+ usage::
int state;
+
...
ioctl(fd, HDIO_SCAN_HWIF, state);
inputs:
- Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON,
- or BUSSTATE_TRISTATE
+ Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON,
+ or BUSSTATE_TRISTATE
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- EOPNOTSUPP Hardware interface does not support bus power control
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - EOPNOTSUPP Hardware interface does not support bus power control
-HDIO_TRISTATE_HWIF execute a channel tristate
+HDIO_TRISTATE_HWIF
+ execute a channel tristate
+
Not implemented, as of 2.6.8.1. See HDIO_SET_BUSSTATE
-HDIO_DRIVE_RESET execute a device reset
+HDIO_DRIVE_RESET
+ execute a device reset
- usage:
+
+ usage::
int args[3]
+
...
ioctl(fd, HDIO_DRIVE_RESET, args);
- inputs: none
+ inputs:
+ none
+
+
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_ADMIN
- ENXIO No such device: phy dead or ctl_addr == 0
- EIO I/O error: reset timed out or hardware error
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - ENXIO No such device: phy dead or ctl_addr == 0
+ - EIO I/O error: reset timed out or hardware error
notes:
- Execute a reset on the device as soon as the current IO
- operation has completed.
+ - Execute a reset on the device as soon as the current IO
+ operation has completed.
- Executes an ATAPI soft reset if applicable, otherwise
- executes an ATA soft reset on the controller.
+ - Executes an ATAPI soft reset if applicable, otherwise
+ executes an ATA soft reset on the controller.
-HDIO_DRIVE_TASKFILE execute raw taskfile
+HDIO_DRIVE_TASKFILE
+ execute raw taskfile
- Note: If you don't have a copy of the ANSI ATA specification
- handy, you should probably ignore this ioctl.
- Execute an ATA disk command directly by writing the "taskfile"
- registers of the drive. Requires ADMIN and RAWIO access
- privileges.
+ Note:
+ If you don't have a copy of the ANSI ATA specification
+ handy, you should probably ignore this ioctl.
- usage:
+ - Execute an ATA disk command directly by writing the "taskfile"
+ registers of the drive. Requires ADMIN and RAWIO access
+ privileges.
+
+ usage::
struct {
+
ide_task_request_t req_task;
u8 outbuf[OUTPUT_SIZE];
u8 inbuf[INPUT_SIZE];
@@ -548,6 +700,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
(See below for details on memory area passed to ioctl.)
+ ============ ===================================================
io_ports[8] values to be written to taskfile registers
hob_ports[8] high-order bytes, for extended commands.
out_flags flags indicating which registers are valid
@@ -557,24 +710,29 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
out_size size of output buffer
outbuf buffer of data to be transmitted to disk
inbuf buffer of data to be received from disk (see [1])
+ ============ ===================================================
outputs:
+ =========== ====================================================
io_ports[] values returned in the taskfile registers
hob_ports[] high-order bytes, for extended commands.
out_flags flags indicating which registers are valid (see [2])
in_flags flags indicating which registers should be returned
outbuf buffer of data to be transmitted to disk (see [1])
inbuf buffer of data to be received from disk
+ =========== ====================================================
error returns:
- EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
- ENOMSG Device is not a disk drive.
- ENOMEM Unable to allocate memory for task
- EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
- EPERM req_cmd == TASKFILE_MULTI_OUT and drive
- multi-count not yet set.
- EIO Drive failed the command.
+ - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
+ - ENOMSG Device is not a disk drive.
+ - ENOMEM Unable to allocate memory for task
+ - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
+ - EPERM
+
+ req_cmd == TASKFILE_MULTI_OUT and drive
+ multi-count not yet set.
+ - EIO Drive failed the command.
notes:
@@ -615,22 +773,25 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
Command is passed to the disk drive via the ide_task_request_t
structure, which contains these fields:
+ ============ ===============================================
io_ports[8] values for the taskfile registers
hob_ports[8] high-order bytes, for extended commands
out_flags flags indicating which entries in the
- io_ports[] and hob_ports[] arrays
+ io_ports[] and hob_ports[] arrays
contain valid values. Type ide_reg_valid_t.
in_flags flags indicating which entries in the
- io_ports[] and hob_ports[] arrays
+ io_ports[] and hob_ports[] arrays
are expected to contain valid values
on return.
data_phase See below
req_cmd Command type, see below
out_size output (user->drive) buffer size, bytes
in_size input (drive->user) buffer size, bytes
+ ============ ===============================================
When out_flags is zero, the following registers are loaded.
+ ============ ===============================================
HOB_FEATURE If the drive supports LBA48
HOB_NSECTOR If the drive supports LBA48
HOB_SECTOR If the drive supports LBA48
@@ -644,9 +805,11 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
SELECT First, masked with 0xE0 if LBA48, 0xEF
otherwise; then, or'ed with the default
value of SELECT.
+ ============ ===============================================
If any bit in out_flags is set, the following registers are loaded.
+ ============ ===============================================
HOB_DATA If out_flags.b.data is set. HOB_DATA will
travel on DD8-DD15 on little endian machines
and on DD0-DD7 on big endian machines.
@@ -664,6 +827,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
HCYL If out_flags.b.hcyl is set
SELECT Or'ed with the default value of SELECT and
loaded regardless of out_flags.b.select.
+ ============ ===============================================
Taskfile registers are read back from the drive into
{io|hob}_ports[] after the command completes iff one of the
@@ -674,6 +838,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
2. One or more than one bits are set in out_flags.
3. The requested data_phase is TASKFILE_NO_DATA.
+ ============ ===============================================
HOB_DATA If in_flags.b.data is set. It will contain
DD8-DD15 on little endian machines and
DD0-DD7 on big endian machines.
@@ -689,10 +854,12 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
SECTOR
LCYL
HCYL
+ ============ ===============================================
The data_phase field describes the data transfer to be
performed. Value is one of:
+ =================== ========================================
TASKFILE_IN
TASKFILE_MULTI_IN
TASKFILE_OUT
@@ -708,15 +875,18 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
TASKFILE_P_OUT unimplemented
TASKFILE_P_OUT_DMA unimplemented
TASKFILE_P_OUT_DMAQ unimplemented
+ =================== ========================================
The req_cmd field classifies the command type. It may be
one of:
+ ======================== =======================================
IDE_DRIVE_TASK_NO_DATA
IDE_DRIVE_TASK_SET_XFER unimplemented
IDE_DRIVE_TASK_IN
IDE_DRIVE_TASK_OUT unimplemented
IDE_DRIVE_TASK_RAW_WRITE
+ ======================== =======================================
[6] Do not access {in|out}_flags->all except for resetting
all the bits. Always access individual bit fields. ->all
@@ -726,45 +896,57 @@ HDIO_DRIVE_TASKFILE execute raw taskfile
-HDIO_DRIVE_CMD execute a special drive command
+HDIO_DRIVE_CMD
+ execute a special drive command
+
Note: If you don't have a copy of the ANSI ATA specification
handy, you should probably ignore this ioctl.
- usage:
+ usage::
u8 args[4+XFER_SIZE];
+
...
ioctl(fd, HDIO_DRIVE_CMD, args);
inputs:
+ Commands other than WIN_SMART:
- Commands other than WIN_SMART
+ ======= =======
args[0] COMMAND
args[1] NSECTOR
args[2] FEATURE
args[3] NSECTOR
+ ======= =======
- WIN_SMART
+ WIN_SMART:
+
+ ======= =======
args[0] COMMAND
args[1] SECTOR
args[2] FEATURE
args[3] NSECTOR
+ ======= =======
outputs:
+ args[] buffer is filled with register values followed by any
+
- args[] buffer is filled with register values followed by any
data returned by the disk.
+
+ ======== ====================================================
args[0] status
args[1] error
args[2] NSECTOR
args[3] undefined
args[4+] NSECTOR * 512 bytes of data returned by the command.
+ ======== ====================================================
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- ENOMEM Unable to allocate memory for task
- EIO Drive reports error
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - ENOMEM Unable to allocate memory for task
+ - EIO Drive reports error
notes:
@@ -789,20 +971,24 @@ HDIO_DRIVE_CMD execute a special drive command
-HDIO_DRIVE_TASK execute task and special drive command
+HDIO_DRIVE_TASK
+ execute task and special drive command
+
Note: If you don't have a copy of the ANSI ATA specification
handy, you should probably ignore this ioctl.
- usage:
+ usage::
u8 args[7];
+
...
ioctl(fd, HDIO_DRIVE_TASK, args);
inputs:
+ Taskfile register values:
- Taskfile register values:
+ ======= =======
args[0] COMMAND
args[1] FEATURE
args[2] NSECTOR
@@ -810,10 +996,13 @@ HDIO_DRIVE_TASK execute task and special drive command
args[4] LCYL
args[5] HCYL
args[6] SELECT
+ ======= =======
outputs:
+ Taskfile register values:
- Taskfile register values:
+
+ ======= =======
args[0] status
args[1] error
args[2] NSECTOR
@@ -821,12 +1010,13 @@ HDIO_DRIVE_TASK execute task and special drive command
args[4] LCYL
args[5] HCYL
args[6] SELECT
+ ======= =======
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- ENOMEM Unable to allocate memory for task
- ENOMSG Device is not a disk drive.
- EIO Drive failed the command.
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - ENOMEM Unable to allocate memory for task
+ - ENOMSG Device is not a disk drive.
+ - EIO Drive failed the command.
notes:
@@ -836,236 +1026,317 @@ HDIO_DRIVE_TASK execute task and special drive command
-HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK
+HDIO_DRIVE_CMD_AEB
+ HDIO_DRIVE_TASK
+
Not implemented, as of 2.6.8.1
-HDIO_SET_32BIT change io_32bit flags
+HDIO_SET_32BIT
+ change io_32bit flags
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_32BIT, val);
inputs:
- New value for io_32bit flag
+ New value for io_32bit flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 3]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 3]
+ - EBUSY Controller busy
-HDIO_SET_NOWERR change ignore-write-error flag
+HDIO_SET_NOWERR
+ change ignore-write-error flag
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_NOWERR, val);
inputs:
- New value for ignore-write-error flag. Used for ignoring
+ New value for ignore-write-error flag. Used for ignoring
+
+
WRERR_STAT
- outputs: none
+ outputs:
+ none
+
+
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_SET_DMA change use-dma flag
+HDIO_SET_DMA
+ change use-dma flag
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_SET_DMA, val);
inputs:
- New value for use-dma flag
+ New value for use-dma flag
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_SET_PIO_MODE reconfig interface to new speed
+HDIO_SET_PIO_MODE
+ reconfig interface to new speed
- usage:
+
+ usage::
long val;
+
ioctl(fd, HDIO_SET_PIO_MODE, val);
inputs:
- New interface speed.
+ New interface speed.
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 255]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 255]
+ - EBUSY Controller busy
-HDIO_SCAN_HWIF register and (re)scan interface
+HDIO_SCAN_HWIF
+ register and (re)scan interface
- usage:
+
+ usage::
int args[3]
+
...
ioctl(fd, HDIO_SCAN_HWIF, args);
inputs:
+
+ ======= =========================
args[0] io address to probe
+
+
args[1] control address to probe
args[2] irq number
+ ======= =========================
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
- EIO Probe failed.
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - EIO Probe failed.
notes:
+ This ioctl initializes the addresses and irq for a disk
+ controller, probes for drives, and creates /proc/ide
+ interfaces as appropriate.
- This ioctl initializes the addresses and irq for a disk
- controller, probes for drives, and creates /proc/ide
- interfaces as appropriate.
+HDIO_UNREGISTER_HWIF
+ unregister interface
-HDIO_UNREGISTER_HWIF unregister interface
- usage:
+ usage::
int index;
+
ioctl(fd, HDIO_UNREGISTER_HWIF, index);
inputs:
- index index of hardware interface to unregister
+ index index of hardware interface to unregister
+
+
+
+ outputs:
+ none
+
- outputs: none
error returns:
- EACCES Access denied: requires CAP_SYS_RAWIO
+ - EACCES Access denied: requires CAP_SYS_RAWIO
notes:
+ This ioctl removes a hardware interface from the kernel.
- This ioctl removes a hardware interface from the kernel.
+ Currently (2.6.8) this ioctl silently fails if any drive on
+ the interface is busy.
- Currently (2.6.8) this ioctl silently fails if any drive on
- the interface is busy.
+HDIO_SET_WCACHE
+ change write cache enable-disable
-HDIO_SET_WCACHE change write cache enable-disable
- usage:
+ usage::
int val;
+
ioctl(fd, HDIO_SET_WCACHE, val);
inputs:
- New value for write cache enable
+ New value for write cache enable
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
-HDIO_SET_ACOUSTIC change acoustic behavior
+HDIO_SET_ACOUSTIC
+ change acoustic behavior
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_ACOUSTIC, val);
inputs:
- New value for drive acoustic settings
+ New value for drive acoustic settings
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 254]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 254]
+ - EBUSY Controller busy
-HDIO_SET_QDMA change use-qdma flag
+HDIO_SET_QDMA
+ change use-qdma flag
+
Not implemented, as of 2.6.8.1
-HDIO_SET_ADDRESS change lba addressing modes
+HDIO_SET_ADDRESS
+ change lba addressing modes
- usage:
+
+ usage::
int val;
+
ioctl(fd, HDIO_SET_ADDRESS, val);
inputs:
- New value for addressing mode
- 0 = 28-bit
- 1 = 48-bit
- 2 = 48-bit doing 28-bit
+ New value for addressing mode
+
+ = ===================
+ 0 28-bit
+ 1 48-bit
+ 2 48-bit doing 28-bit
+ = ===================
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 2]
- EBUSY Controller busy
- EIO Drive does not support lba48 mode.
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 2]
+ - EBUSY Controller busy
+ - EIO Drive does not support lba48 mode.
HDIO_SET_IDE_SCSI
+ usage::
- usage:
long val;
+
ioctl(fd, HDIO_SET_IDE_SCSI, val);
inputs:
- New value for scsi emulation mode (?)
+ New value for scsi emulation mode (?)
+
+
+
+ outputs:
+ none
+
- outputs: none
error return:
- EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- EACCES Access denied: requires CAP_SYS_ADMIN
- EINVAL value out of range [0 1]
- EBUSY Controller busy
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
HDIO_SET_SCSI_IDE
-
Not implemented, as of 2.6.8.1
-
-
diff --git a/Documentation/ioctl/index.rst b/Documentation/ioctl/index.rst
new file mode 100644
index 000000000000..1a6f437566e3
--- /dev/null
+++ b/Documentation/ioctl/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+======
+IOCTLs
+======
+
+.. toctree::
+ :maxdepth: 1
+
+ ioctl-number
+
+ botching-up-ioctls
+ ioctl-decoding
+
+ cdrom
+ hdio
diff --git a/Documentation/ioctl/ioctl-decoding.txt b/Documentation/ioctl/ioctl-decoding.rst
similarity index 54%
rename from Documentation/ioctl/ioctl-decoding.txt
rename to Documentation/ioctl/ioctl-decoding.rst
index e35efb0cec2e..380d6bb3e3ea 100644
--- a/Documentation/ioctl/ioctl-decoding.txt
+++ b/Documentation/ioctl/ioctl-decoding.rst
@@ -1,10 +1,16 @@
+==============================
+Decoding an IOCTL Magic Number
+==============================
+
To decode a hex IOCTL code:
Most architectures use this generic format, but check
include/ARCH/ioctl.h for specifics, e.g. powerpc
uses 3 bits to encode read/write and 13 bits for size.
- bits meaning
+ ====== ==================================
+ bits meaning
+ ====== ==================================
31-30 00 - no parameters: uses _IO macro
10 - read: _IOR
01 - write: _IOW
@@ -16,9 +22,10 @@ uses 3 bits to encode read/write and 13 bits for size.
unique to each driver
7-0 function #
+ ====== ==================================
So for example 0x82187201 is a read with arg length of 0x218,
-character 'r' function 1. Grepping the source reveals this is:
+character 'r' function 1. Grepping the source reveals this is::
-#define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2])
+ #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2])
diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c
index 9441a36a2469..bd810454d239 100644
--- a/drivers/gpu/drm/drm_ioctl.c
+++ b/drivers/gpu/drm/drm_ioctl.c
@@ -736,7 +736,7 @@ static const struct drm_ioctl_desc drm_ioctls[] = {
* };
*
* Please make sure that you follow all the best practices from
- * ``Documentation/ioctl/botching-up-ioctls.txt``. Note that drm_ioctl()
+ * ``Documentation/ioctl/botching-up-ioctls.rst``. Note that drm_ioctl()
* automatically zero-extends structures, hence make sure you can add more stuff
* at the end, i.e. don't put a variable sized array there.
*
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 35/43] docs: thermal: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (32 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 34/43] docs: ioctl: convert to ReST Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 36/43] docs: rapidio: " Mauro Carvalho Chehab
` (8 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Kukjin Kim, Krzysztof Kozlowski, Zhang Rui,
Eduardo Valentin, Daniel Lezcano, linux-arm-kernel,
linux-samsung-soc, linux-pm, Arjan van de Ven
Rename the thermal 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>
---
...pu-cooling-api.txt => cpu-cooling-api.rst} | 39 +-
.../{exynos_thermal => exynos_thermal.rst} | 47 +-
.../thermal/exynos_thermal_emulation | 53 --
.../thermal/exynos_thermal_emulation.rst | 61 +++
Documentation/thermal/index.rst | 18 +
...el_powerclamp.txt => intel_powerclamp.rst} | 177 +++----
.../{nouveau_thermal => nouveau_thermal.rst} | 54 +-
...ower_allocator.txt => power_allocator.rst} | 140 ++---
.../thermal/{sysfs-api.txt => sysfs-api.rst} | 490 ++++++++++++------
...hermal => x86_pkg_temperature_thermal.rst} | 28 +-
MAINTAINERS | 2 +-
include/linux/thermal.h | 4 +-
12 files changed, 689 insertions(+), 424 deletions(-)
rename Documentation/thermal/{cpu-cooling-api.txt => cpu-cooling-api.rst} (82%)
rename Documentation/thermal/{exynos_thermal => exynos_thermal.rst} (67%)
delete mode 100644 Documentation/thermal/exynos_thermal_emulation
create mode 100644 Documentation/thermal/exynos_thermal_emulation.rst
create mode 100644 Documentation/thermal/index.rst
rename Documentation/thermal/{intel_powerclamp.txt => intel_powerclamp.rst} (76%)
rename Documentation/thermal/{nouveau_thermal => nouveau_thermal.rst} (64%)
rename Documentation/thermal/{power_allocator.txt => power_allocator.rst} (74%)
rename Documentation/thermal/{sysfs-api.txt => sysfs-api.rst} (66%)
rename Documentation/thermal/{x86_pkg_temperature_thermal => x86_pkg_temperature_thermal.rst} (80%)
diff --git a/Documentation/thermal/cpu-cooling-api.txt b/Documentation/thermal/cpu-cooling-api.rst
similarity index 82%
rename from Documentation/thermal/cpu-cooling-api.txt
rename to Documentation/thermal/cpu-cooling-api.rst
index 7df567eaea1a..645d914c45a6 100644
--- a/Documentation/thermal/cpu-cooling-api.txt
+++ b/Documentation/thermal/cpu-cooling-api.rst
@@ -1,5 +1,6 @@
+=======================
CPU cooling APIs How To
-===================================
+=======================
Written by Amit Daniel Kachhap <amit.kachhap@linaro.org>
@@ -8,40 +9,54 @@ Updated: 6 Jan 2015
Copyright (c) 2012 Samsung Electronics Co., Ltd(http://www.samsung.com)
0. Introduction
+===============
The generic cpu cooling(freq clipping) provides registration/unregistration APIs
to the caller. The binding of the cooling devices to the trip point is left for
the user. The registration APIs returns the cooling device pointer.
1. cpu cooling APIs
+===================
1.1 cpufreq registration/unregistration APIs
-1.1.1 struct thermal_cooling_device *cpufreq_cooling_register(
- struct cpumask *clip_cpus)
+--------------------------------------------
+
+ ::
+
+ struct thermal_cooling_device
+ *cpufreq_cooling_register(struct cpumask *clip_cpus)
This interface function registers the cpufreq cooling device with the name
"thermal-cpufreq-%x". This api can support multiple instances of cpufreq
cooling devices.
- clip_cpus: cpumask of cpus where the frequency constraints will happen.
+ clip_cpus:
+ cpumask of cpus where the frequency constraints will happen.
-1.1.2 struct thermal_cooling_device *of_cpufreq_cooling_register(
- struct cpufreq_policy *policy)
+ ::
+
+ struct thermal_cooling_device
+ *of_cpufreq_cooling_register(struct cpufreq_policy *policy)
This interface function registers the cpufreq cooling device with
the name "thermal-cpufreq-%x" linking it with a device tree node, in
order to bind it via the thermal DT code. This api can support multiple
instances of cpufreq cooling devices.
- policy: CPUFreq policy.
+ policy:
+ CPUFreq policy.
-1.1.3 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev)
+
+ ::
+
+ void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev)
This interface function unregisters the "thermal-cpufreq-%x" cooling device.
cdev: Cooling device pointer which has to be unregistered.
2. Power models
+===============
The power API registration functions provide a simple power model for
CPUs. The current power is calculated as dynamic power (static power isn't
@@ -65,9 +80,9 @@ For a given processor implementation the primary factors are:
variation. In pathological cases this variation can be significant,
but typically it is of a much lesser impact than the factors above.
-A high level dynamic power consumption model may then be represented as:
+A high level dynamic power consumption model may then be represented as::
-Pdyn = f(run) * Voltage^2 * Frequency * Utilisation
+ Pdyn = f(run) * Voltage^2 * Frequency * Utilisation
f(run) here represents the described execution behaviour and its
result has a units of Watts/Hz/Volt^2 (this often expressed in
@@ -80,9 +95,9 @@ factors. Therefore, in initial implementation that contribution is
represented as a constant coefficient. This is a simplification
consistent with the relative contribution to overall power variation.
-In this simplified representation our model becomes:
+In this simplified representation our model becomes::
-Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation
+ Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation
Where `capacitance` is a constant that represents an indicative
running time dynamic power coefficient in fundamental units of
diff --git a/Documentation/thermal/exynos_thermal b/Documentation/thermal/exynos_thermal.rst
similarity index 67%
rename from Documentation/thermal/exynos_thermal
rename to Documentation/thermal/exynos_thermal.rst
index 9010c4416967..5bd556566c70 100644
--- a/Documentation/thermal/exynos_thermal
+++ b/Documentation/thermal/exynos_thermal.rst
@@ -1,8 +1,11 @@
+========================
Kernel driver exynos_tmu
-=================
+========================
Supported chips:
+
* ARM SAMSUNG EXYNOS4, EXYNOS5 series of SoC
+
Datasheet: Not publicly available
Authors: Donggeun Kim <dg77.kim@samsung.com>
@@ -19,32 +22,39 @@ Temperature can be taken from the temperature code.
There are three equations converting from temperature to temperature code.
The three equations are:
- 1. Two point trimming
+ 1. Two point trimming::
+
Tc = (T - 25) * (TI2 - TI1) / (85 - 25) + TI1
- 2. One point trimming
+ 2. One point trimming::
+
Tc = T + TI1 - 25
- 3. No trimming
+ 3. No trimming::
+
Tc = T + 50
- Tc: Temperature code, T: Temperature,
- TI1: Trimming info for 25 degree Celsius (stored at TRIMINFO register)
+ Tc:
+ Temperature code, T: Temperature,
+ TI1:
+ Trimming info for 25 degree Celsius (stored at TRIMINFO register)
Temperature code measured at 25 degree Celsius which is unchanged
- TI2: Trimming info for 85 degree Celsius (stored at TRIMINFO register)
+ TI2:
+ Trimming info for 85 degree Celsius (stored at TRIMINFO register)
Temperature code measured at 85 degree Celsius which is unchanged
TMU(Thermal Management Unit) in EXYNOS4/5 generates interrupt
when temperature exceeds pre-defined levels.
The maximum number of configurable threshold is five.
-The threshold levels are defined as follows:
+The threshold levels are defined as follows::
+
Level_0: current temperature > trigger_level_0 + threshold
Level_1: current temperature > trigger_level_1 + threshold
Level_2: current temperature > trigger_level_2 + threshold
Level_3: current temperature > trigger_level_3 + threshold
- The threshold and each trigger_level are set
- through the corresponding registers.
+The threshold and each trigger_level are set
+through the corresponding registers.
When an interrupt occurs, this driver notify kernel thermal framework
with the function exynos_report_trigger.
@@ -54,24 +64,27 @@ it can be used to synchronize the cooling action.
TMU driver description:
-----------------------
-The exynos thermal driver is structured as,
+The exynos thermal driver is structured as::
Kernel Core thermal framework
(thermal_core.c, step_wise.c, cpu_cooling.c)
^
|
|
-TMU configuration data -------> TMU Driver <------> Exynos Core thermal wrapper
-(exynos_tmu_data.c) (exynos_tmu.c) (exynos_thermal_common.c)
-(exynos_tmu_data.h) (exynos_tmu.h) (exynos_thermal_common.h)
+ TMU configuration data -----> TMU Driver <----> Exynos Core thermal wrapper
+ (exynos_tmu_data.c) (exynos_tmu.c) (exynos_thermal_common.c)
+ (exynos_tmu_data.h) (exynos_tmu.h) (exynos_thermal_common.h)
-a) TMU configuration data: This consist of TMU register offsets/bitfields
+a) TMU configuration data:
+ This consist of TMU register offsets/bitfields
described through structure exynos_tmu_registers. Also several
other platform data (struct exynos_tmu_platform_data) members
are used to configure the TMU.
-b) TMU driver: This component initialises the TMU controller and sets different
+b) TMU driver:
+ This component initialises the TMU controller and sets different
thresholds. It invokes core thermal implementation with the call
exynos_report_trigger.
-c) Exynos Core thermal wrapper: This provides 3 wrapper function to use the
+c) Exynos Core thermal wrapper:
+ This provides 3 wrapper function to use the
Kernel core thermal framework. They are exynos_unregister_thermal,
exynos_register_thermal and exynos_report_trigger.
diff --git a/Documentation/thermal/exynos_thermal_emulation b/Documentation/thermal/exynos_thermal_emulation
deleted file mode 100644
index b15efec6ca28..000000000000
--- a/Documentation/thermal/exynos_thermal_emulation
+++ /dev/null
@@ -1,53 +0,0 @@
-EXYNOS EMULATION MODE
-========================
-
-Copyright (C) 2012 Samsung Electronics
-
-Written by Jonghwa Lee <jonghwa3.lee@samsung.com>
-
-Description
------------
-
-Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for thermal management unit.
-Thermal emulation mode supports software debug for TMU's operation. User can set temperature
-manually with software code and TMU will read current temperature from user value not from
-sensor's value.
-
-Enabling CONFIG_THERMAL_EMULATION option will make this support available.
-When it's enabled, sysfs node will be created as
-/sys/devices/virtual/thermal/thermal_zone'zone id'/emul_temp.
-
-The sysfs node, 'emul_node', will contain value 0 for the initial state. When you input any
-temperature you want to update to sysfs node, it automatically enable emulation mode and
-current temperature will be changed into it.
-(Exynos also supports user changeable delay time which would be used to delay of
- changing temperature. However, this node only uses same delay of real sensing time, 938us.)
-
-Exynos emulation mode requires synchronous of value changing and enabling. It means when you
-want to update the any value of delay or next temperature, then you have to enable emulation
-mode at the same time. (Or you have to keep the mode enabling.) If you don't, it fails to
-change the value to updated one and just use last succeessful value repeatedly. That's why
-this node gives users the right to change termerpature only. Just one interface makes it more
-simply to use.
-
-Disabling emulation mode only requires writing value 0 to sysfs node.
-
-
-TEMP 120 |
- |
- 100 |
- |
- 80 |
- | +-----------
- 60 | | |
- | +-------------| |
- 40 | | | |
- | | | |
- 20 | | | +----------
- | | | | |
- 0 |______________|_____________|__________|__________|_________
- A A A A TIME
- |<----->| |<----->| |<----->| |
- | 938us | | | | | |
-emulation : 0 50 | 70 | 20 | 0
-current temp : sensor 50 70 20 sensor
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/thermal/exynos_thermal_emulation.rst
new file mode 100644
index 000000000000..c21d10838bc5
--- /dev/null
+++ b/Documentation/thermal/exynos_thermal_emulation.rst
@@ -0,0 +1,61 @@
+=====================
+Exynos Emulation Mode
+=====================
+
+Copyright (C) 2012 Samsung Electronics
+
+Written by Jonghwa Lee <jonghwa3.lee@samsung.com>
+
+Description
+-----------
+
+Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for thermal
+management unit. Thermal emulation mode supports software debug for
+TMU's operation. User can set temperature manually with software code
+and TMU will read current temperature from user value not from sensor's
+value.
+
+Enabling CONFIG_THERMAL_EMULATION option will make this support
+available. When it's enabled, sysfs node will be created as
+/sys/devices/virtual/thermal/thermal_zone'zone id'/emul_temp.
+
+The sysfs node, 'emul_node', will contain value 0 for the initial state.
+When you input any temperature you want to update to sysfs node, it
+automatically enable emulation mode and current temperature will be
+changed into it.
+
+(Exynos also supports user changeable delay time which would be used to
+delay of changing temperature. However, this node only uses same delay
+of real sensing time, 938us.)
+
+Exynos emulation mode requires synchronous of value changing and
+enabling. It means when you want to update the any value of delay or
+next temperature, then you have to enable emulation mode at the same
+time. (Or you have to keep the mode enabling.) If you don't, it fails to
+change the value to updated one and just use last succeessful value
+repeatedly. That's why this node gives users the right to change
+termerpature only. Just one interface makes it more simply to use.
+
+Disabling emulation mode only requires writing value 0 to sysfs node.
+
+::
+
+
+ TEMP 120 |
+ |
+ 100 |
+ |
+ 80 |
+ | +-----------
+ 60 | | |
+ | +-------------| |
+ 40 | | | |
+ | | | |
+ 20 | | | +----------
+ | | | | |
+ 0 |______________|_____________|__________|__________|_________
+ A A A A TIME
+ |<----->| |<----->| |<----->| |
+ | 938us | | | | | |
+ emulation : 0 50 | 70 | 20 | 0
+ current temp: sensor 50 70 20 sensor
diff --git a/Documentation/thermal/index.rst b/Documentation/thermal/index.rst
new file mode 100644
index 000000000000..8c1c00146cad
--- /dev/null
+++ b/Documentation/thermal/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=======
+Thermal
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ cpu-cooling-api
+ sysfs-api
+ power_allocator
+
+ exynos_thermal
+ exynos_thermal_emulation
+ intel_powerclamp
+ nouveau_thermal
+ x86_pkg_temperature_thermal
diff --git a/Documentation/thermal/intel_powerclamp.txt b/Documentation/thermal/intel_powerclamp.rst
similarity index 76%
rename from Documentation/thermal/intel_powerclamp.txt
rename to Documentation/thermal/intel_powerclamp.rst
index b5df21168fbc..3f6dfb0b3ea6 100644
--- a/Documentation/thermal/intel_powerclamp.txt
+++ b/Documentation/thermal/intel_powerclamp.rst
@@ -1,10 +1,13 @@
- =======================
- INTEL POWERCLAMP DRIVER
- =======================
-By: Arjan van de Ven <arjan@linux.intel.com>
- Jacob Pan <jacob.jun.pan@linux.intel.com>
+=======================
+Intel Powerclamp Driver
+=======================
+
+By:
+ - Arjan van de Ven <arjan@linux.intel.com>
+ - Jacob Pan <jacob.jun.pan@linux.intel.com>
+
+.. Contents:
-Contents:
(*) Introduction
- Goals and Objectives
@@ -23,7 +26,6 @@ Contents:
- Generic Thermal Layer (sysfs)
- Kernel APIs (TBD)
-============
INTRODUCTION
============
@@ -47,7 +49,6 @@ scalability, and user experience. In many cases, clear advantage is
shown over taking the CPU offline or modulating the CPU clock.
-===================
THEORY OF OPERATION
===================
@@ -57,11 +58,12 @@ Idle Injection
On modern Intel processors (Nehalem or later), package level C-state
residency is available in MSRs, thus also available to the kernel.
-These MSRs are:
- #define MSR_PKG_C2_RESIDENCY 0x60D
- #define MSR_PKG_C3_RESIDENCY 0x3F8
- #define MSR_PKG_C6_RESIDENCY 0x3F9
- #define MSR_PKG_C7_RESIDENCY 0x3FA
+These MSRs are::
+
+ #define MSR_PKG_C2_RESIDENCY 0x60D
+ #define MSR_PKG_C3_RESIDENCY 0x3F8
+ #define MSR_PKG_C6_RESIDENCY 0x3F9
+ #define MSR_PKG_C7_RESIDENCY 0x3FA
If the kernel can also inject idle time to the system, then a
closed-loop control system can be established that manages package
@@ -96,19 +98,21 @@ are not masked. Tests show that the extra wakeups from scheduler tick
have a dramatic impact on the effectiveness of the powerclamp driver
on large scale systems (Westmere system with 80 processors).
-CPU0
- ____________ ____________
-kidle_inject/0 | sleep | mwait | sleep |
- _________| |________| |_______
- duration
-CPU1
- ____________ ____________
-kidle_inject/1 | sleep | mwait | sleep |
- _________| |________| |_______
- ^
- |
- |
- roundup(jiffies, interval)
+::
+
+ CPU0
+ ____________ ____________
+ kidle_inject/0 | sleep | mwait | sleep |
+ _________| |________| |_______
+ duration
+ CPU1
+ ____________ ____________
+ kidle_inject/1 | sleep | mwait | sleep |
+ _________| |________| |_______
+ ^
+ |
+ |
+ roundup(jiffies, interval)
Only one CPU is allowed to collect statistics and update global
control parameters. This CPU is referred to as the controlling CPU in
@@ -148,7 +152,7 @@ b) determine the amount of compensation needed at each target ratio
Compensation to each target ratio consists of two parts:
- a) steady state error compensation
+ a) steady state error compensation
This is to offset the error occurring when the system can
enter idle without extra wakeups (such as external interrupts).
@@ -158,41 +162,42 @@ Compensation to each target ratio consists of two parts:
slowing down CPU activities.
A debugfs file is provided for the user to examine compensation
-progress and results, such as on a Westmere system.
-[jacob@nex01 ~]$ cat
-/sys/kernel/debug/intel_powerclamp/powerclamp_calib
-controlling cpu: 0
-pct confidence steady dynamic (compensation)
-0 0 0 0
-1 1 0 0
-2 1 1 0
-3 3 1 0
-4 3 1 0
-5 3 1 0
-6 3 1 0
-7 3 1 0
-8 3 1 0
-...
-30 3 2 0
-31 3 2 0
-32 3 1 0
-33 3 2 0
-34 3 1 0
-35 3 2 0
-36 3 1 0
-37 3 2 0
-38 3 1 0
-39 3 2 0
-40 3 3 0
-41 3 1 0
-42 3 2 0
-43 3 1 0
-44 3 1 0
-45 3 2 0
-46 3 3 0
-47 3 0 0
-48 3 2 0
-49 3 3 0
+progress and results, such as on a Westmere system::
+
+ [jacob@nex01 ~]$ cat
+ /sys/kernel/debug/intel_powerclamp/powerclamp_calib
+ controlling cpu: 0
+ pct confidence steady dynamic (compensation)
+ 0 0 0 0
+ 1 1 0 0
+ 2 1 1 0
+ 3 3 1 0
+ 4 3 1 0
+ 5 3 1 0
+ 6 3 1 0
+ 7 3 1 0
+ 8 3 1 0
+ ...
+ 30 3 2 0
+ 31 3 2 0
+ 32 3 1 0
+ 33 3 2 0
+ 34 3 1 0
+ 35 3 2 0
+ 36 3 1 0
+ 37 3 2 0
+ 38 3 1 0
+ 39 3 2 0
+ 40 3 3 0
+ 41 3 1 0
+ 42 3 2 0
+ 43 3 1 0
+ 44 3 1 0
+ 45 3 2 0
+ 46 3 3 0
+ 47 3 0 0
+ 48 3 2 0
+ 49 3 3 0
Calibration occurs during runtime. No offline method is available.
Steady state compensation is used only when confidence levels of all
@@ -217,9 +222,8 @@ keeps track of clamping kernel threads, even after they are migrated
to other CPUs, after a CPU offline event.
-=====================
Performance Analysis
-=====================
+====================
This section describes the general performance data collected on
multiple systems, including Westmere (80P) and Ivy Bridge (4P, 8P).
@@ -257,16 +261,15 @@ achieve up to 40% better performance per watt. (measured by a spin
counter summed over per CPU counting threads spawned for all running
CPUs).
-====================
Usage and Interfaces
====================
The powerclamp driver is registered to the generic thermal layer as a
-cooling device. Currently, it’s not bound to any thermal zones.
+cooling device. Currently, it’s not bound to any thermal zones::
-jacob@chromoly:/sys/class/thermal/cooling_device14$ grep . *
-cur_state:0
-max_state:50
-type:intel_powerclamp
+ jacob@chromoly:/sys/class/thermal/cooling_device14$ grep . *
+ cur_state:0
+ max_state:50
+ type:intel_powerclamp
cur_state allows user to set the desired idle percentage. Writing 0 to
cur_state will stop idle injection. Writing a value between 1 and
@@ -278,9 +281,9 @@ cur_state returns value -1 instead of 0 which is to avoid confusing
100% busy state with the disabled state.
Example usage:
-- To inject 25% idle time
-$ sudo sh -c "echo 25 > /sys/class/thermal/cooling_device80/cur_state
-"
+- To inject 25% idle time::
+
+ $ sudo sh -c "echo 25 > /sys/class/thermal/cooling_device80/cur_state
If the system is not busy and has more than 25% idle time already,
then the powerclamp driver will not start idle injection. Using Top
@@ -292,23 +295,23 @@ idle time is accounted as normal idle in that common code path is
taken as the idle task.
In this example, 24.1% idle is shown. This helps the system admin or
-user determine the cause of slowdown, when a powerclamp driver is in action.
+user determine the cause of slowdown, when a powerclamp driver is in action::
-Tasks: 197 total, 1 running, 196 sleeping, 0 stopped, 0 zombie
-Cpu(s): 71.2%us, 4.7%sy, 0.0%ni, 24.1%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st
-Mem: 3943228k total, 1689632k used, 2253596k free, 74960k buffers
-Swap: 4087804k total, 0k used, 4087804k free, 945336k cached
+ Tasks: 197 total, 1 running, 196 sleeping, 0 stopped, 0 zombie
+ Cpu(s): 71.2%us, 4.7%sy, 0.0%ni, 24.1%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st
+ Mem: 3943228k total, 1689632k used, 2253596k free, 74960k buffers
+ Swap: 4087804k total, 0k used, 4087804k free, 945336k cached
- PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
- 3352 jacob 20 0 262m 644 428 S 286 0.0 0:17.16 spin
- 3341 root -51 0 0 0 0 D 25 0.0 0:01.62 kidle_inject/0
- 3344 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/3
- 3342 root -51 0 0 0 0 D 25 0.0 0:01.61 kidle_inject/1
- 3343 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/2
- 2935 jacob 20 0 696m 125m 35m S 5 3.3 0:31.11 firefox
- 1546 root 20 0 158m 20m 6640 S 3 0.5 0:26.97 Xorg
- 2100 jacob 20 0 1223m 88m 30m S 3 2.3 0:23.68 compiz
+ PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
+ 3352 jacob 20 0 262m 644 428 S 286 0.0 0:17.16 spin
+ 3341 root -51 0 0 0 0 D 25 0.0 0:01.62 kidle_inject/0
+ 3344 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/3
+ 3342 root -51 0 0 0 0 D 25 0.0 0:01.61 kidle_inject/1
+ 3343 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/2
+ 2935 jacob 20 0 696m 125m 35m S 5 3.3 0:31.11 firefox
+ 1546 root 20 0 158m 20m 6640 S 3 0.5 0:26.97 Xorg
+ 2100 jacob 20 0 1223m 88m 30m S 3 2.3 0:23.68 compiz
Tests have shown that by using the powerclamp driver as a cooling
device, a PID based userspace thermal controller can manage to
diff --git a/Documentation/thermal/nouveau_thermal b/Documentation/thermal/nouveau_thermal.rst
similarity index 64%
rename from Documentation/thermal/nouveau_thermal
rename to Documentation/thermal/nouveau_thermal.rst
index 6e17a11efcb0..37255fd6735d 100644
--- a/Documentation/thermal/nouveau_thermal
+++ b/Documentation/thermal/nouveau_thermal.rst
@@ -1,13 +1,15 @@
+=====================
Kernel driver nouveau
-===================
+=====================
Supported chips:
+
* NV43+
Authors: Martin Peres (mupuf) <martin.peres@free.fr>
Description
----------
+-----------
This driver allows to read the GPU core temperature, drive the GPU fan and
set temperature alarms.
@@ -19,20 +21,25 @@ interface is likely not to work. This document may then not cover your situation
entirely.
Temperature management
---------------------
+----------------------
Temperature is exposed under as a read-only HWMON attribute temp1_input.
In order to protect the GPU from overheating, Nouveau supports 4 configurable
temperature thresholds:
- * Fan_boost: Fan speed is set to 100% when reaching this temperature;
- * Downclock: The GPU will be downclocked to reduce its power dissipation;
- * Critical: The GPU is put on hold to further lower power dissipation;
- * Shutdown: Shut the computer down to protect your GPU.
+ * Fan_boost:
+ Fan speed is set to 100% when reaching this temperature;
+ * Downclock:
+ The GPU will be downclocked to reduce its power dissipation;
+ * Critical:
+ The GPU is put on hold to further lower power dissipation;
+ * Shutdown:
+ Shut the computer down to protect your GPU.
-WARNING: Some of these thresholds may not be used by Nouveau depending
-on your chipset.
+WARNING:
+ Some of these thresholds may not be used by Nouveau depending
+ on your chipset.
The default value for these thresholds comes from the GPU's vbios. These
thresholds can be configured thanks to the following HWMON attributes:
@@ -46,19 +53,24 @@ NOTE: Remember that the values are stored as milli degrees Celsius. Don't forget
to multiply!
Fan management
-------------
+--------------
Not all cards have a drivable fan. If you do, then the following HWMON
attributes should be available:
- * pwm1_enable: Current fan management mode (NONE, MANUAL or AUTO);
- * pwm1: Current PWM value (power percentage);
- * pwm1_min: The minimum PWM speed allowed;
- * pwm1_max: The maximum PWM speed allowed (bypassed when hitting Fan_boost);
+ * pwm1_enable:
+ Current fan management mode (NONE, MANUAL or AUTO);
+ * pwm1:
+ Current PWM value (power percentage);
+ * pwm1_min:
+ The minimum PWM speed allowed;
+ * pwm1_max:
+ The maximum PWM speed allowed (bypassed when hitting Fan_boost);
You may also have the following attribute:
- * fan1_input: Speed in RPM of your fan.
+ * fan1_input:
+ Speed in RPM of your fan.
Your fan can be driven in different modes:
@@ -66,14 +78,16 @@ Your fan can be driven in different modes:
* 1: The fan can be driven in manual (use pwm1 to change the speed);
* 2; The fan is driven automatically depending on the temperature.
-NOTE: Be sure to use the manual mode if you want to drive the fan speed manually
+NOTE:
+ Be sure to use the manual mode if you want to drive the fan speed manually
-NOTE2: When operating in manual mode outside the vbios-defined
-[PWM_min, PWM_max] range, the reported fan speed (RPM) may not be accurate
-depending on your hardware.
+NOTE2:
+ When operating in manual mode outside the vbios-defined
+ [PWM_min, PWM_max] range, the reported fan speed (RPM) may not be accurate
+ depending on your hardware.
Bug reports
----------
+-----------
Thermal management on Nouveau is new and may not work on all cards. If you have
inquiries, please ping mupuf on IRC (#nouveau, freenode).
diff --git a/Documentation/thermal/power_allocator.txt b/Documentation/thermal/power_allocator.rst
similarity index 74%
rename from Documentation/thermal/power_allocator.txt
rename to Documentation/thermal/power_allocator.rst
index 9fb0ff06dca9..67b6a3297238 100644
--- a/Documentation/thermal/power_allocator.txt
+++ b/Documentation/thermal/power_allocator.rst
@@ -1,3 +1,4 @@
+=================================
Power allocator governor tunables
=================================
@@ -25,36 +26,36 @@ temperature as the control input and power as the controlled output:
P_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_power
where
- e = desired_temperature - current_temperature
- err_integral is the sum of previous errors
- diff_err = e - previous_error
+ - e = desired_temperature - current_temperature
+ - err_integral is the sum of previous errors
+ - diff_err = e - previous_error
-It is similar to the one depicted below:
+It is similar to the one depicted below::
- k_d
- |
-current_temp |
- | v
- | +----------+ +---+
- | +----->| diff_err |-->| X |------+
- | | +----------+ +---+ |
- | | | tdp actor
- | | k_i | | get_requested_power()
- | | | | | | |
- | | | | | | | ...
- v | v v v v v
- +---+ | +-------+ +---+ +---+ +---+ +----------+
- | S |-------+----->| sum e |----->| X |--->| S |-->| S |-->|power |
- +---+ | +-------+ +---+ +---+ +---+ |allocation|
- ^ | ^ +----------+
- | | | | |
- | | +---+ | | |
- | +------->| X |-------------------+ v v
- | +---+ granted performance
-desired_temperature ^
- |
- |
- k_po/k_pu
+ k_d
+ |
+ current_temp |
+ | v
+ | +----------+ +---+
+ | +----->| diff_err |-->| X |------+
+ | | +----------+ +---+ |
+ | | | tdp actor
+ | | k_i | | get_requested_power()
+ | | | | | | |
+ | | | | | | | ...
+ v | v v v v v
+ +---+ | +-------+ +---+ +---+ +---+ +----------+
+ | S |-----+----->| sum e |----->| X |--->| S |-->| S |-->|power |
+ +---+ | +-------+ +---+ +---+ +---+ |allocation|
+ ^ | ^ +----------+
+ | | | | |
+ | | +---+ | | |
+ | +------->| X |-------------------+ v v
+ | +---+ granted performance
+ desired_temperature ^
+ |
+ |
+ k_po/k_pu
Sustainable power
-----------------
@@ -73,7 +74,7 @@ is typically 2000mW, while on a 10" tablet is around 4500mW (may vary
depending on screen size).
If you are using device tree, do add it as a property of the
-thermal-zone. For example:
+thermal-zone. For example::
thermal-zones {
soc_thermal {
@@ -85,7 +86,7 @@ thermal-zone. For example:
Instead, if the thermal zone is registered from the platform code, pass a
`thermal_zone_params` that has a `sustainable_power`. If no
`thermal_zone_params` were being passed, then something like below
-will suffice:
+will suffice::
static const struct thermal_zone_params tz_params = {
.sustainable_power = 3500,
@@ -112,18 +113,18 @@ available capacity at a low temperature. On the other hand, a high
value of `k_pu` will result in the governor granting very high power
while temperature is low, and may lead to temperature overshooting.
-The default value for `k_pu` is:
+The default value for `k_pu` is::
2 * sustainable_power / (desired_temperature - switch_on_temp)
This means that at `switch_on_temp` the output of the controller's
proportional term will be 2 * `sustainable_power`. The default value
-for `k_po` is:
+for `k_po` is::
sustainable_power / (desired_temperature - switch_on_temp)
Focusing on the proportional and feed forward values of the PID
-controller equation we have:
+controller equation we have::
P_max = k_p * e + sustainable_power
@@ -134,21 +135,23 @@ is the desired one, then the proportional component is zero and
thermal equilibrium under constant load. `sustainable_power` is only
an estimate, which is the reason for closed-loop control such as this.
-Expanding `k_pu` we get:
+Expanding `k_pu` we get::
+
P_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) +
- sustainable_power
+ sustainable_power
-where
- T_set is the desired temperature
- T is the current temperature
- T_on is the switch on temperature
+where:
+
+ - T_set is the desired temperature
+ - T is the current temperature
+ - T_on is the switch on temperature
When the current temperature is the switch_on temperature, the above
-formula becomes:
+formula becomes::
P_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) +
- sustainable_power = 2 * sustainable_power + sustainable_power =
- 3 * sustainable_power
+ sustainable_power = 2 * sustainable_power + sustainable_power =
+ 3 * sustainable_power
Therefore, the proportional term alone linearly decreases power from
3 * `sustainable_power` to `sustainable_power` as the temperature
@@ -178,11 +181,18 @@ Cooling device power API
Cooling devices controlled by this governor must supply the additional
"power" API in their `cooling_device_ops`. It consists on three ops:
-1. int get_requested_power(struct thermal_cooling_device *cdev,
- struct thermal_zone_device *tz, u32 *power);
-@cdev: The `struct thermal_cooling_device` pointer
-@tz: thermal zone in which we are currently operating
-@power: pointer in which to store the calculated power
+1. ::
+
+ int get_requested_power(struct thermal_cooling_device *cdev,
+ struct thermal_zone_device *tz, u32 *power);
+
+
+@cdev:
+ The `struct thermal_cooling_device` pointer
+@tz:
+ thermal zone in which we are currently operating
+@power:
+ pointer in which to store the calculated power
`get_requested_power()` calculates the power requested by the device
in milliwatts and stores it in @power . It should return 0 on
@@ -190,23 +200,37 @@ success, -E* on failure. This is currently used by the power
allocator governor to calculate how much power to give to each cooling
device.
-2. int state2power(struct thermal_cooling_device *cdev, struct
- thermal_zone_device *tz, unsigned long state, u32 *power);
-@cdev: The `struct thermal_cooling_device` pointer
-@tz: thermal zone in which we are currently operating
-@state: A cooling device state
-@power: pointer in which to store the equivalent power
+2. ::
+
+ int state2power(struct thermal_cooling_device *cdev, struct
+ thermal_zone_device *tz, unsigned long state,
+ u32 *power);
+
+@cdev:
+ The `struct thermal_cooling_device` pointer
+@tz:
+ thermal zone in which we are currently operating
+@state:
+ A cooling device state
+@power:
+ pointer in which to store the equivalent power
Convert cooling device state @state into power consumption in
milliwatts and store it in @power. It should return 0 on success, -E*
on failure. This is currently used by thermal core to calculate the
maximum power that an actor can consume.
-3. int power2state(struct thermal_cooling_device *cdev, u32 power,
- unsigned long *state);
-@cdev: The `struct thermal_cooling_device` pointer
-@power: power in milliwatts
-@state: pointer in which to store the resulting state
+3. ::
+
+ int power2state(struct thermal_cooling_device *cdev, u32 power,
+ unsigned long *state);
+
+@cdev:
+ The `struct thermal_cooling_device` pointer
+@power:
+ power in milliwatts
+@state:
+ pointer in which to store the resulting state
Calculate a cooling device state that would make the device consume at
most @power mW and store it in @state. It should return 0 on success,
diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.rst
similarity index 66%
rename from Documentation/thermal/sysfs-api.txt
rename to Documentation/thermal/sysfs-api.rst
index c3fa500df92c..e4930761d3e5 100644
--- a/Documentation/thermal/sysfs-api.txt
+++ b/Documentation/thermal/sysfs-api.rst
@@ -1,3 +1,4 @@
+===================================
Generic Thermal Sysfs driver How To
===================================
@@ -9,6 +10,7 @@ Copyright (c) 2008 Intel Corporation
0. Introduction
+===============
The generic thermal sysfs provides a set of interfaces for thermal zone
devices (sensors) and thermal cooling devices (fan, processor...) to register
@@ -25,59 +27,90 @@ An intelligent thermal management application can make decisions based on
inputs from thermal zone attributes (the current temperature and trip point
temperature) and throttle appropriate devices.
-[0-*] denotes any positive number starting from 0
-[1-*] denotes any positive number starting from 1
+- `[0-*]` denotes any positive number starting from 0
+- `[1-*]` denotes any positive number starting from 1
1. thermal sysfs driver interface functions
+===========================================
1.1 thermal zone device interface
-1.1.1 struct thermal_zone_device *thermal_zone_device_register(char *type,
- int trips, int mask, void *devdata,
- struct thermal_zone_device_ops *ops,
- const struct thermal_zone_params *tzp,
- int passive_delay, int polling_delay))
+---------------------------------
+
+ ::
+
+ struct thermal_zone_device
+ *thermal_zone_device_register(char *type,
+ int trips, int mask, void *devdata,
+ struct thermal_zone_device_ops *ops,
+ const struct thermal_zone_params *tzp,
+ int passive_delay, int polling_delay))
This interface function adds a new thermal zone device (sensor) to
- /sys/class/thermal folder as thermal_zone[0-*]. It tries to bind all the
+ /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the
thermal cooling devices registered at the same time.
- type: the thermal zone type.
- trips: the total number of trip points this thermal zone supports.
- mask: Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
- devdata: device private data
- ops: thermal zone device call-backs.
- .bind: bind the thermal zone device with a thermal cooling device.
- .unbind: unbind the thermal zone device with a thermal cooling device.
- .get_temp: get the current temperature of the thermal zone.
- .set_trips: set the trip points window. Whenever the current temperature
+ type:
+ the thermal zone type.
+ trips:
+ the total number of trip points this thermal zone supports.
+ mask:
+ Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
+ devdata:
+ device private data
+ ops:
+ thermal zone device call-backs.
+
+ .bind:
+ bind the thermal zone device with a thermal cooling device.
+ .unbind:
+ unbind the thermal zone device with a thermal cooling device.
+ .get_temp:
+ get the current temperature of the thermal zone.
+ .set_trips:
+ set the trip points window. Whenever the current temperature
is updated, the trip points immediately below and above the
current temperature are found.
- .get_mode: get the current mode (enabled/disabled) of the thermal zone.
- - "enabled" means the kernel thermal management is enabled.
- - "disabled" will prevent kernel thermal driver action upon trip points
- so that user applications can take charge of thermal management.
- .set_mode: set the mode (enabled/disabled) of the thermal zone.
- .get_trip_type: get the type of certain trip point.
- .get_trip_temp: get the temperature above which the certain trip point
+ .get_mode:
+ get the current mode (enabled/disabled) of the thermal zone.
+
+ - "enabled" means the kernel thermal management is
+ enabled.
+ - "disabled" will prevent kernel thermal driver action
+ upon trip points so that user applications can take
+ charge of thermal management.
+ .set_mode:
+ set the mode (enabled/disabled) of the thermal zone.
+ .get_trip_type:
+ get the type of certain trip point.
+ .get_trip_temp:
+ get the temperature above which the certain trip point
will be fired.
- .set_emul_temp: set the emulation temperature which helps in debugging
+ .set_emul_temp:
+ set the emulation temperature which helps in debugging
different threshold temperature points.
- tzp: thermal zone platform parameters.
- passive_delay: number of milliseconds to wait between polls when
+ tzp:
+ thermal zone platform parameters.
+ passive_delay:
+ number of milliseconds to wait between polls when
performing passive cooling.
- polling_delay: number of milliseconds to wait between polls when checking
+ polling_delay:
+ number of milliseconds to wait between polls when checking
whether trip points have been crossed (0 for interrupt driven systems).
+ ::
-1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz)
+ void thermal_zone_device_unregister(struct thermal_zone_device *tz)
This interface function removes the thermal zone device.
It deletes the corresponding entry from /sys/class/thermal folder and
unbinds all the thermal cooling devices it uses.
-1.1.3 struct thermal_zone_device *thermal_zone_of_sensor_register(
- struct device *dev, int sensor_id, void *data,
- const struct thermal_zone_of_device_ops *ops)
+ ::
+
+ struct thermal_zone_device
+ *thermal_zone_of_sensor_register(struct device *dev, int sensor_id,
+ void *data,
+ const struct thermal_zone_of_device_ops *ops)
This interface adds a new sensor to a DT thermal zone.
This function will search the list of thermal zones described in
@@ -87,25 +120,33 @@ temperature) and throttle appropriate devices.
thermal zone device.
The parameters for this interface are:
- dev: Device node of sensor containing valid node pointer in
+
+ dev:
+ Device node of sensor containing valid node pointer in
dev->of_node.
- sensor_id: a sensor identifier, in case the sensor IP has more
+ sensor_id:
+ a sensor identifier, in case the sensor IP has more
than one sensors
- data: a private pointer (owned by the caller) that will be
+ data:
+ a private pointer (owned by the caller) that will be
passed back, when a temperature reading is needed.
- ops: struct thermal_zone_of_device_ops *.
+ ops:
+ `struct thermal_zone_of_device_ops *`.
- get_temp: a pointer to a function that reads the
+ ============== =======================================
+ get_temp a pointer to a function that reads the
sensor temperature. This is mandatory
callback provided by sensor driver.
- set_trips: a pointer to a function that sets a
+ set_trips a pointer to a function that sets a
temperature window. When this window is
left the driver must inform the thermal
core via thermal_zone_device_update.
- get_trend: a pointer to a function that reads the
+ get_trend a pointer to a function that reads the
sensor temperature trend.
- set_emul_temp: a pointer to a function that sets
+ set_emul_temp a pointer to a function that sets
sensor emulated temperature.
+ ============== =======================================
+
The thermal zone temperature is provided by the get_temp() function
pointer of thermal_zone_of_device_ops. When called, it will
have the private pointer @data back.
@@ -114,8 +155,10 @@ temperature) and throttle appropriate devices.
handle. Caller should check the return handle with IS_ERR() for finding
whether success or not.
-1.1.4 void thermal_zone_of_sensor_unregister(struct device *dev,
- struct thermal_zone_device *tzd)
+ ::
+
+ void thermal_zone_of_sensor_unregister(struct device *dev,
+ struct thermal_zone_device *tzd)
This interface unregisters a sensor from a DT thermal zone which was
successfully added by interface thermal_zone_of_sensor_register().
@@ -124,21 +167,29 @@ temperature) and throttle appropriate devices.
interface. It will also silent the zone by remove the .get_temp() and
get_trend() thermal zone device callbacks.
-1.1.5 struct thermal_zone_device *devm_thermal_zone_of_sensor_register(
- struct device *dev, int sensor_id,
- void *data, const struct thermal_zone_of_device_ops *ops)
+ ::
+
+ struct thermal_zone_device
+ *devm_thermal_zone_of_sensor_register(struct device *dev,
+ int sensor_id,
+ void *data,
+ const struct thermal_zone_of_device_ops *ops)
This interface is resource managed version of
thermal_zone_of_sensor_register().
+
All details of thermal_zone_of_sensor_register() described in
section 1.1.3 is applicable here.
+
The benefit of using this interface to register sensor is that it
is not require to explicitly call thermal_zone_of_sensor_unregister()
in error path or during driver unbinding as this is done by driver
resource manager.
-1.1.6 void devm_thermal_zone_of_sensor_unregister(struct device *dev,
- struct thermal_zone_device *tzd)
+ ::
+
+ void devm_thermal_zone_of_sensor_unregister(struct device *dev,
+ struct thermal_zone_device *tzd)
This interface is resource managed version of
thermal_zone_of_sensor_unregister().
@@ -147,123 +198,186 @@ temperature) and throttle appropriate devices.
Normally this function will not need to be called and the resource
management code will ensure that the resource is freed.
-1.1.7 int thermal_zone_get_slope(struct thermal_zone_device *tz)
+ ::
+
+ int thermal_zone_get_slope(struct thermal_zone_device *tz)
This interface is used to read the slope attribute value
for the thermal zone device, which might be useful for platform
drivers for temperature calculations.
-1.1.8 int thermal_zone_get_offset(struct thermal_zone_device *tz)
+ ::
+
+ int thermal_zone_get_offset(struct thermal_zone_device *tz)
This interface is used to read the offset attribute value
for the thermal zone device, which might be useful for platform
drivers for temperature calculations.
1.2 thermal cooling device interface
-1.2.1 struct thermal_cooling_device *thermal_cooling_device_register(char *name,
- void *devdata, struct thermal_cooling_device_ops *)
+------------------------------------
+
+
+ ::
+
+ struct thermal_cooling_device
+ *thermal_cooling_device_register(char *name,
+ void *devdata, struct thermal_cooling_device_ops *)
This interface function adds a new thermal cooling device (fan/processor/...)
- to /sys/class/thermal/ folder as cooling_device[0-*]. It tries to bind itself
+ to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself
to all the thermal zone devices registered at the same time.
- name: the cooling device name.
- devdata: device private data.
- ops: thermal cooling devices call-backs.
- .get_max_state: get the Maximum throttle state of the cooling device.
- .get_cur_state: get the Currently requested throttle state of the cooling device.
- .set_cur_state: set the Current throttle state of the cooling device.
-
-1.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
+
+ name:
+ the cooling device name.
+ devdata:
+ device private data.
+ ops:
+ thermal cooling devices call-backs.
+
+ .get_max_state:
+ get the Maximum throttle state of the cooling device.
+ .get_cur_state:
+ get the Currently requested throttle state of the
+ cooling device.
+ .set_cur_state:
+ set the Current throttle state of the cooling device.
+
+ ::
+
+ void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
This interface function removes the thermal cooling device.
It deletes the corresponding entry from /sys/class/thermal folder and
unbinds itself from all the thermal zone devices using it.
1.3 interface for binding a thermal zone device with a thermal cooling device
-1.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
- int trip, struct thermal_cooling_device *cdev,
- unsigned long upper, unsigned long lower, unsigned int weight);
+-----------------------------------------------------------------------------
+
+ ::
+
+ int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
+ int trip, struct thermal_cooling_device *cdev,
+ unsigned long upper, unsigned long lower, unsigned int weight);
This interface function binds a thermal cooling device to a particular trip
point of a thermal zone device.
+
This function is usually called in the thermal zone device .bind callback.
- tz: the thermal zone device
- cdev: thermal cooling device
- trip: indicates which trip point in this thermal zone the cooling device
- is associated with.
- upper:the Maximum cooling state for this trip point.
- THERMAL_NO_LIMIT means no upper limit,
+
+ tz:
+ the thermal zone device
+ cdev:
+ thermal cooling device
+ trip:
+ indicates which trip point in this thermal zone the cooling device
+ is associated with.
+ upper:
+ the Maximum cooling state for this trip point.
+ THERMAL_NO_LIMIT means no upper limit,
and the cooling device can be in max_state.
- lower:the Minimum cooling state can be used for this trip point.
- THERMAL_NO_LIMIT means no lower limit,
+ lower:
+ the Minimum cooling state can be used for this trip point.
+ THERMAL_NO_LIMIT means no lower limit,
and the cooling device can be in cooling state 0.
- weight: the influence of this cooling device in this thermal
- zone. See 1.4.1 below for more information.
+ weight:
+ the influence of this cooling device in this thermal
+ zone. See 1.4.1 below for more information.
-1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
- int trip, struct thermal_cooling_device *cdev);
+ ::
+
+ int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
+ int trip, struct thermal_cooling_device *cdev);
This interface function unbinds a thermal cooling device from a particular
trip point of a thermal zone device. This function is usually called in
the thermal zone device .unbind callback.
- tz: the thermal zone device
- cdev: thermal cooling device
- trip: indicates which trip point in this thermal zone the cooling device
- is associated with.
+
+ tz:
+ the thermal zone device
+ cdev:
+ thermal cooling device
+ trip:
+ indicates which trip point in this thermal zone the cooling device
+ is associated with.
1.4 Thermal Zone Parameters
-1.4.1 struct thermal_bind_params
+---------------------------
+
+ ::
+
+ struct thermal_bind_params
+
This structure defines the following parameters that are used to bind
a zone with a cooling device for a particular trip point.
- .cdev: The cooling device pointer
- .weight: The 'influence' of a particular cooling device on this
- zone. This is relative to the rest of the cooling
- devices. For example, if all cooling devices have a
- weight of 1, then they all contribute the same. You can
- use percentages if you want, but it's not mandatory. A
- weight of 0 means that this cooling device doesn't
- contribute to the cooling of this zone unless all cooling
- devices have a weight of 0. If all weights are 0, then
- they all contribute the same.
- .trip_mask:This is a bit mask that gives the binding relation between
- this thermal zone and cdev, for a particular trip point.
- If nth bit is set, then the cdev and thermal zone are bound
- for trip point n.
- .binding_limits: This is an array of cooling state limits. Must have
- exactly 2 * thermal_zone.number_of_trip_points. It is an
- array consisting of tuples <lower-state upper-state> of
- state limits. Each trip will be associated with one state
- limit tuple when binding. A NULL pointer means
- <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips.
- These limits are used when binding a cdev to a trip point.
- .match: This call back returns success(0) if the 'tz and cdev' need to
+
+ .cdev:
+ The cooling device pointer
+ .weight:
+ The 'influence' of a particular cooling device on this
+ zone. This is relative to the rest of the cooling
+ devices. For example, if all cooling devices have a
+ weight of 1, then they all contribute the same. You can
+ use percentages if you want, but it's not mandatory. A
+ weight of 0 means that this cooling device doesn't
+ contribute to the cooling of this zone unless all cooling
+ devices have a weight of 0. If all weights are 0, then
+ they all contribute the same.
+ .trip_mask:
+ This is a bit mask that gives the binding relation between
+ this thermal zone and cdev, for a particular trip point.
+ If nth bit is set, then the cdev and thermal zone are bound
+ for trip point n.
+ .binding_limits:
+ This is an array of cooling state limits. Must have
+ exactly 2 * thermal_zone.number_of_trip_points. It is an
+ array consisting of tuples <lower-state upper-state> of
+ state limits. Each trip will be associated with one state
+ limit tuple when binding. A NULL pointer means
+ <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips.
+ These limits are used when binding a cdev to a trip point.
+ .match:
+ This call back returns success(0) if the 'tz and cdev' need to
be bound, as per platform data.
-1.4.2 struct thermal_zone_params
+
+ ::
+
+ struct thermal_zone_params
+
This structure defines the platform level parameters for a thermal zone.
This data, for each thermal zone should come from the platform layer.
This is an optional feature where some platforms can choose not to
provide this data.
- .governor_name: Name of the thermal governor used for this zone
- .no_hwmon: a boolean to indicate if the thermal to hwmon sysfs interface
- is required. when no_hwmon == false, a hwmon sysfs interface
- will be created. when no_hwmon == true, nothing will be done.
- In case the thermal_zone_params is NULL, the hwmon interface
- will be created (for backward compatibility).
- .num_tbps: Number of thermal_bind_params entries for this zone
- .tbp: thermal_bind_params entries
+
+ .governor_name:
+ Name of the thermal governor used for this zone
+ .no_hwmon:
+ a boolean to indicate if the thermal to hwmon sysfs interface
+ is required. when no_hwmon == false, a hwmon sysfs interface
+ will be created. when no_hwmon == true, nothing will be done.
+ In case the thermal_zone_params is NULL, the hwmon interface
+ will be created (for backward compatibility).
+ .num_tbps:
+ Number of thermal_bind_params entries for this zone
+ .tbp:
+ thermal_bind_params entries
2. sysfs attributes structure
+=============================
+== ================
RO read only value
WO write only value
RW read/write value
+== ================
Thermal sysfs attributes will be represented under /sys/class/thermal.
Hwmon sysfs I/F extension is also available under /sys/class/hwmon
if hwmon is compiled in or built as a module.
-Thermal zone device sys I/F, created once it's registered:
-/sys/class/thermal/thermal_zone[0-*]:
+Thermal zone device sys I/F, created once it's registered::
+
+ /sys/class/thermal/thermal_zone[0-*]:
|---type: Type of the thermal zone
|---temp: Current temperature
|---mode: Working mode of the thermal zone
@@ -282,8 +396,9 @@ Thermal zone device sys I/F, created once it's registered:
|---slope: Slope constant applied as linear extrapolation
|---offset: Offset constant applied as linear extrapolation
-Thermal cooling device sys I/F, created once it's registered:
-/sys/class/thermal/cooling_device[0-*]:
+Thermal cooling device sys I/F, created once it's registered::
+
+ /sys/class/thermal/cooling_device[0-*]:
|---type: Type of the cooling device(processor/fan/...)
|---max_state: Maximum cooling state of the cooling device
|---cur_state: Current cooling state of the cooling device
@@ -299,11 +414,13 @@ the relationship between a thermal zone and its associated cooling device.
They are created/removed for each successful execution of
thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.
-/sys/class/thermal/thermal_zone[0-*]:
+::
+
+ /sys/class/thermal/thermal_zone[0-*]:
|---cdev[0-*]: [0-*]th cooling device in current thermal zone
|---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with
|---cdev[0-*]_weight: Influence of the cooling device in
- this thermal zone
+ this thermal zone
Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
the generic thermal driver also creates a hwmon sysfs I/F for each _type_
@@ -311,16 +428,17 @@ of thermal zone device. E.g. the generic thermal driver registers one hwmon
class device and build the associated hwmon sysfs I/F for all the registered
ACPI thermal zones.
-/sys/class/hwmon/hwmon[0-*]:
+::
+
+ /sys/class/hwmon/hwmon[0-*]:
|---name: The type of the thermal zone devices
|---temp[1-*]_input: The current temperature of thermal zone [1-*]
|---temp[1-*]_critical: The critical trip point of thermal zone [1-*]
Please read Documentation/hwmon/sysfs-interface.rst for additional information.
-***************************
-* Thermal zone attributes *
-***************************
+Thermal zone attributes
+-----------------------
type
Strings which represent the thermal zone type.
@@ -340,54 +458,67 @@ mode
This file gives information about the algorithm that is currently
managing the thermal zone. It can be either default kernel based
algorithm or user space application.
- enabled = enable Kernel Thermal management.
- disabled = Preventing kernel thermal zone driver actions upon
+
+ enabled
+ enable Kernel Thermal management.
+ disabled
+ Preventing kernel thermal zone driver actions upon
trip points so that user application can take full
charge of the thermal management.
+
RW, Optional
policy
One of the various thermal governors used for a particular zone.
+
RW, Required
available_policies
Available thermal governors which can be used for a particular zone.
+
RO, Required
-trip_point_[0-*]_temp
+`trip_point_[0-*]_temp`
The temperature above which trip point will be fired.
+
Unit: millidegree Celsius
+
RO, Optional
-trip_point_[0-*]_type
+`trip_point_[0-*]_type`
Strings which indicate the type of the trip point.
- E.g. it can be one of critical, hot, passive, active[0-*] for ACPI
+
+ E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI
thermal zone.
+
RO, Optional
-trip_point_[0-*]_hyst
+`trip_point_[0-*]_hyst`
The hysteresis value for a trip point, represented as an integer
Unit: Celsius
RW, Optional
-cdev[0-*]
+`cdev[0-*]`
Sysfs link to the thermal cooling device node where the sys I/F
for cooling device throttling control represents.
+
RO, Optional
-cdev[0-*]_trip_point
- The trip point in this thermal zone which cdev[0-*] is associated
+`cdev[0-*]_trip_point`
+ The trip point in this thermal zone which `cdev[0-*]` is associated
with; -1 means the cooling device is not associated with any trip
point.
+
RO, Optional
-cdev[0-*]_weight
- The influence of cdev[0-*] in this thermal zone. This value
- is relative to the rest of cooling devices in the thermal
- zone. For example, if a cooling device has a weight double
- than that of other, it's twice as effective in cooling the
- thermal zone.
- RW, Optional
+`cdev[0-*]_weight`
+ The influence of `cdev[0-*]` in this thermal zone. This value
+ is relative to the rest of cooling devices in the thermal
+ zone. For example, if a cooling device has a weight double
+ than that of other, it's twice as effective in cooling the
+ thermal zone.
+
+ RW, Optional
passive
Attribute is only present for zones in which the passive cooling
@@ -395,8 +526,11 @@ passive
and can be set to a temperature (in millidegrees) to enable a
passive trip point for the zone. Activation is done by polling with
an interval of 1 second.
+
Unit: millidegrees Celsius
+
Valid values: 0 (disabled) or greater than 1000
+
RW, Optional
emul_temp
@@ -407,17 +541,21 @@ emul_temp
threshold and its associated cooling action. This is write only node
and writing 0 on this node should disable emulation.
Unit: millidegree Celsius
+
WO, Optional
- WARNING: Be careful while enabling this option on production systems,
- because userland can easily disable the thermal policy by simply
- flooding this sysfs node with low temperature values.
+ WARNING:
+ Be careful while enabling this option on production systems,
+ because userland can easily disable the thermal policy by simply
+ flooding this sysfs node with low temperature values.
sustainable_power
An estimate of the sustained power that can be dissipated by
the thermal zone. Used by the power allocator governor. For
- more information see Documentation/thermal/power_allocator.txt
+ more information see Documentation/thermal/power_allocator.rst
+
Unit: milliwatts
+
RW, Optional
k_po
@@ -425,7 +563,8 @@ k_po
controller during temperature overshoot. Temperature overshoot
is when the current temperature is above the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
k_pu
@@ -433,20 +572,23 @@ k_pu
controller during temperature undershoot. Temperature undershoot
is when the current temperature is below the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
k_i
The integral term of the power allocator governor's PID
controller. This term allows the PID controller to compensate
for long term drift. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
k_d
The derivative term of the power allocator governor's PID
controller. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
RW, Optional
integral_cutoff
@@ -456,8 +598,10 @@ integral_cutoff
example, if integral_cutoff is 0, then the integral term only
accumulates error when temperature is above the desired
temperature trip point. For more information see
- Documentation/thermal/power_allocator.txt
+ Documentation/thermal/power_allocator.rst
+
Unit: millidegree Celsius
+
RW, Optional
slope
@@ -465,6 +609,7 @@ slope
to determine a hotspot temperature based off the sensor's
raw readings. It is up to the device driver to determine
the usage of these values.
+
RW, Optional
offset
@@ -472,28 +617,33 @@ offset
to determine a hotspot temperature based off the sensor's
raw readings. It is up to the device driver to determine
the usage of these values.
+
RW, Optional
-*****************************
-* Cooling device attributes *
-*****************************
+Cooling device attributes
+-------------------------
type
String which represents the type of device, e.g:
+
- for generic ACPI: should be "Fan", "Processor" or "LCD"
- for memory controller device on intel_menlow platform:
should be "Memory controller".
+
RO, Required
max_state
The maximum permissible cooling state of this cooling device.
+
RO, Required
cur_state
The current cooling state of this cooling device.
The value can any integer numbers between 0 and max_state:
+
- cur_state == 0 means no cooling
- cur_state == max_state means the maximum cooling.
+
RW, Required
stats/reset
@@ -508,9 +658,11 @@ stats/time_in_state_ms:
units here is 10mS (similar to other time exported in /proc).
RO, Required
+
stats/total_trans:
A single positive value showing the total number of times the state of a
cooling device is changed.
+
RO, Required
stats/trans_table:
@@ -522,6 +674,7 @@ stats/trans_table:
RO, Required
3. A simple implementation
+==========================
ACPI thermal zone may support multiple trip points like critical, hot,
passive, active. If an ACPI thermal zone supports critical, passive,
@@ -532,11 +685,10 @@ thermal_cooling_device. Both are considered to have the same
effectiveness in cooling the thermal zone.
If the processor is listed in _PSL method, and the fan is listed in _AL0
-method, the sys I/F structure will be built like this:
+method, the sys I/F structure will be built like this::
-/sys/class/thermal:
-
-|thermal_zone1:
+ /sys/class/thermal:
+ |thermal_zone1:
|---type: acpitz
|---temp: 37000
|---mode: enabled
@@ -557,24 +709,24 @@ method, the sys I/F structure will be built like this:
|---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/
|---cdev1_weight: 1024
-|cooling_device0:
+ |cooling_device0:
|---type: Processor
|---max_state: 8
|---cur_state: 0
-|cooling_device3:
+ |cooling_device3:
|---type: Fan
|---max_state: 2
|---cur_state: 0
-/sys/class/hwmon:
-
-|hwmon0:
+ /sys/class/hwmon:
+ |hwmon0:
|---name: acpitz
|---temp1_input: 37000
|---temp1_crit: 100000
4. Event Notification
+=====================
The framework includes a simple notification mechanism, in the form of a
netlink event. Netlink socket initialization is done during the _init_
@@ -587,21 +739,28 @@ event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
crosses any of the configured thresholds.
-5. Export Symbol APIs:
+5. Export Symbol APIs
+=====================
+
+5.1. get_tz_trend
+-----------------
-5.1: get_tz_trend:
This function returns the trend of a thermal zone, i.e the rate of change
of temperature of the thermal zone. Ideally, the thermal sensor drivers
are supposed to implement the callback. If they don't, the thermal
framework calculated the trend by comparing the previous and the current
temperature values.
-5.2:get_thermal_instance:
+5.2. get_thermal_instance
+-------------------------
+
This function returns the thermal_instance corresponding to a given
{thermal_zone, cooling_device, trip_point} combination. Returns NULL
if such an instance does not exist.
-5.3:thermal_notify_framework:
+5.3. thermal_notify_framework
+-----------------------------
+
This function handles the trip events from sensor drivers. It starts
throttling the cooling devices according to the policy configured.
For CRITICAL and HOT trip points, this notifies the respective drivers,
@@ -609,12 +768,15 @@ and does actual throttling for other trip points i.e ACTIVE and PASSIVE.
The throttling policy is based on the configured platform data; if no
platform data is provided, this uses the step_wise throttling policy.
-5.4:thermal_cdev_update:
+5.4. thermal_cdev_update
+------------------------
+
This function serves as an arbitrator to set the state of a cooling
device. It sets the cooling device to the deepest cooling state if
possible.
-6. thermal_emergency_poweroff:
+6. thermal_emergency_poweroff
+=============================
On an event of critical trip temperature crossing. Thermal framework
allows the system to shutdown gracefully by calling orderly_poweroff().
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal b/Documentation/thermal/x86_pkg_temperature_thermal.rst
similarity index 80%
rename from Documentation/thermal/x86_pkg_temperature_thermal
rename to Documentation/thermal/x86_pkg_temperature_thermal.rst
index 17a3a4c0a0ca..f134dbd3f5a9 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal
+++ b/Documentation/thermal/x86_pkg_temperature_thermal.rst
@@ -1,19 +1,23 @@
+===================================
Kernel driver: x86_pkg_temp_thermal
-===================
+===================================
Supported chips:
+
* x86: with package level thermal management
+
(Verify using: CPUID.06H:EAX[bit 6] =1)
Authors: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
Reference
----
+---------
+
Intel® 64 and IA-32 Architectures Software Developer’s Manual (Jan, 2013):
Chapter 14.6: PACKAGE LEVEL THERMAL MANAGEMENT
Description
----------
+-----------
This driver register CPU digital temperature package level sensor as a thermal
zone with maximum two user mode configurable trip points. Number of trip points
@@ -25,23 +29,27 @@ take any action to control temperature.
Threshold management
--------------------
Each package will register as a thermal zone under /sys/class/thermal.
-Example:
-/sys/class/thermal/thermal_zone1
+
+Example::
+
+ /sys/class/thermal/thermal_zone1
This contains two trip points:
+
- trip_point_0_temp
- trip_point_1_temp
User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.txt" for
+are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
thermal sys-fs details.
Any value other than 0 in these trip points, can trigger thermal notifications.
Setting 0, stops sending thermal notifications.
-Thermal notifications: To get kobject-uevent notifications, set the thermal zone
-policy to "user_space". For example: echo -n "user_space" > policy
-
-
+Thermal notifications:
+To get kobject-uevent notifications, set the thermal zone
+policy to "user_space".
+For example::
+ echo -n "user_space" > policy
diff --git a/MAINTAINERS b/MAINTAINERS
index 8aa3d0bd5b80..85648a944446 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15762,7 +15762,7 @@ M: Viresh Kumar <viresh.kumar@linaro.org>
M: Javi Merino <javi.merino@kernel.org>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/thermal/cpu-cooling-api.txt
+F: Documentation/thermal/cpu-cooling-api.rst
F: drivers/thermal/cpu_cooling.c
F: include/linux/cpu_cooling.h
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 15a4ca5d7099..681047f8cc05 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
* platform characterization. This value is relative to the
* rest of the weights so a cooling device whose weight is
* double that of another cooling device is twice as
- * effective. See Documentation/thermal/sysfs-api.txt for more
+ * effective. See Documentation/thermal/sysfs-api.rst for more
* information.
*/
int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
/*
* This is a bit mask that gives the binding relation between this
* thermal zone and cdev, for a particular trip point.
- * See Documentation/thermal/sysfs-api.txt for more information.
+ * See Documentation/thermal/sysfs-api.rst for more information.
*/
int trip_mask;
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 36/43] docs: rapidio: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (33 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 35/43] docs: thermal: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 37/43] docs: blockdev: " Mauro Carvalho Chehab
` (7 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Matt Porter, Alexandre Bounine
Rename the rapidio 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/rapidio/index.rst | 15 +++++
.../{mport_cdev.txt => mport_cdev.rst} | 47 ++++++-------
.../rapidio/{rapidio.txt => rapidio.rst} | 39 +++++++----
.../rapidio/{rio_cm.txt => rio_cm.rst} | 66 ++++++++++++-------
.../rapidio/{sysfs.txt => sysfs.rst} | 4 ++
.../rapidio/{tsi721.txt => tsi721.rst} | 45 ++++++++-----
drivers/rapidio/Kconfig | 2 +-
7 files changed, 141 insertions(+), 77 deletions(-)
create mode 100644 Documentation/rapidio/index.rst
rename Documentation/rapidio/{mport_cdev.txt => mport_cdev.rst} (84%)
rename Documentation/rapidio/{rapidio.txt => rapidio.rst} (97%)
rename Documentation/rapidio/{rio_cm.txt => rio_cm.rst} (76%)
rename Documentation/rapidio/{sysfs.txt => sysfs.rst} (75%)
rename Documentation/rapidio/{tsi721.txt => tsi721.rst} (79%)
diff --git a/Documentation/rapidio/index.rst b/Documentation/rapidio/index.rst
new file mode 100644
index 000000000000..ab7b5541b346
--- /dev/null
+++ b/Documentation/rapidio/index.rst
@@ -0,0 +1,15 @@
+:orphan:
+
+===========================
+The Linux RapidIO Subsystem
+===========================
+
+.. toctree::
+ :maxdepth: 1
+
+ rapidio
+ sysfs
+
+ tsi721
+ mport_cdev
+ rio_cm
diff --git a/Documentation/rapidio/mport_cdev.txt b/Documentation/rapidio/mport_cdev.rst
similarity index 84%
rename from Documentation/rapidio/mport_cdev.txt
rename to Documentation/rapidio/mport_cdev.rst
index a53f786ee2e9..df77a7f7be7d 100644
--- a/Documentation/rapidio/mport_cdev.txt
+++ b/Documentation/rapidio/mport_cdev.rst
@@ -1,13 +1,9 @@
+==================================================================
RapidIO subsystem mport character device driver (rio_mport_cdev.c)
==================================================================
-Version History:
-----------------
- 1.0.0 - Initial driver release.
-
-==================================================================
-
-I. Overview
+1. Overview
+===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Freescale,
@@ -29,40 +25,41 @@ Using available set of ioctl commands user-space applications can perform
following RapidIO bus and subsystem operations:
- Reads and writes from/to configuration registers of mport devices
- (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
+ (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
- Reads and writes from/to configuration registers of remote RapidIO devices.
This operations are defined as RapidIO Maintenance reads/writes in RIO spec.
- (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
+ (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
- Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET)
- Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET)
- Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET)
- Query capabilities and RapidIO link configuration of mport devices
- (RIO_MPORT_GET_PROPERTIES)
+ (RIO_MPORT_GET_PROPERTIES)
- Enable/Disable reporting of RapidIO doorbell events to user-space applications
- (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
+ (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
- Enable/Disable reporting of RIO port-write events to user-space applications
- (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
+ (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
- Query/Control type of events reported through this driver: doorbells,
port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK)
- Configure/Map mport's outbound requests window(s) for specific size,
RapidIO destination ID, hopcount and request type
- (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
+ (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
- Configure/Map mport's inbound requests window(s) for specific size,
RapidIO base address and local memory base address
- (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
+ (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
- Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers
to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA)
- Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER).
Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data
transfer modes.
- Check/Wait for completion of asynchronous DMA data transfer
- (RIO_WAIT_FOR_ASYNC)
+ (RIO_WAIT_FOR_ASYNC)
- Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL).
This allows implementation of various RapidIO fabric enumeration algorithms
as user-space applications while using remaining functionality provided by
kernel RapidIO subsystem.
-II. Hardware Compatibility
+2. Hardware Compatibility
+=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
@@ -78,29 +75,35 @@ functionality of their platform when planning to use this driver:
specific DMA engine support and therefore DMA data transfers mport_cdev driver
are not available.
-III. Module parameters
+3. Module parameters
+====================
-- 'dma_timeout' - DMA transfer completion timeout (in msec, default value 3000).
+- 'dma_timeout'
+ - DMA transfer completion timeout (in msec, default value 3000).
This parameter set a maximum completion wait time for SYNC mode DMA
transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.
-- 'dbg_level' - This parameter allows to control amount of debug information
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional blocks.
For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-IV. Known problems
+4. Known problems
+=================
None.
-V. User-space Applications and API
+5. User-space Applications and API
+==================================
API library and applications that use this device driver are available from
RapidIO.org.
-VI. TODO List
+6. TODO List
+============
- Add support for sending/receiving "raw" RapidIO messaging packets.
- Add memory mapped DMA data transfers as an option when RapidIO-specific DMA
diff --git a/Documentation/rapidio/rapidio.txt b/Documentation/rapidio/rapidio.rst
similarity index 97%
rename from Documentation/rapidio/rapidio.txt
rename to Documentation/rapidio/rapidio.rst
index 28fbd877f85a..fb8942d3ba85 100644
--- a/Documentation/rapidio/rapidio.txt
+++ b/Documentation/rapidio/rapidio.rst
@@ -1,6 +1,6 @@
- The Linux RapidIO Subsystem
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============
+Introduction
+============
The RapidIO standard is a packet-based fabric interconnect standard designed for
use in embedded systems. Development of the RapidIO standard is directed by the
@@ -11,7 +11,7 @@ This document describes the basics of the Linux RapidIO subsystem and provides
information on its major components.
1 Overview
-----------
+==========
Because the RapidIO subsystem follows the Linux device model it is integrated
into the kernel similarly to other buses by defining RapidIO-specific device and
@@ -22,7 +22,7 @@ architecture-specific interfaces that provide support for common RapidIO
subsystem operations.
2. Core Components
-------------------
+==================
A typical RapidIO network is a combination of endpoints and switches.
Each of these components is represented in the subsystem by an associated data
@@ -30,6 +30,7 @@ structure. The core logical components of the RapidIO subsystem are defined
in include/linux/rio.h file.
2.1 Master Port
+---------------
A master port (or mport) is a RapidIO interface controller that is local to the
processor executing the Linux code. A master port generates and receives RapidIO
@@ -46,6 +47,7 @@ includes rio_ops data structure which contains pointers to hardware specific
implementations of RapidIO functions.
2.2 Device
+----------
A RapidIO device is any endpoint (other than mport) or switch in the network.
All devices are presented in the RapidIO subsystem by corresponding rio_dev data
@@ -53,6 +55,7 @@ structure. Devices form one global device list and per-network device lists
(depending on number of available mports and networks).
2.3 Switch
+----------
A RapidIO switch is a special class of device that routes packets between its
ports towards their final destination. The packet destination port within a
@@ -66,6 +69,7 @@ specific switch drivers that are designed to provide hardware-specific
implementation of common switch management routines.
2.4 Network
+-----------
A RapidIO network is a combination of interconnected endpoint and switch devices.
Each RapidIO network known to the system is represented by corresponding rio_net
@@ -74,11 +78,13 @@ ports that form the same network. It also contains a pointer to the default
master port that is used to communicate with devices within the network.
2.5 Device Drivers
+------------------
RapidIO device-specific drivers follow Linux Kernel Driver Model and are
intended to support specific RapidIO devices attached to the RapidIO network.
2.6 Subsystem Interfaces
+------------------------
RapidIO interconnect specification defines features that may be used to provide
one or more common service layers for all participating RapidIO devices. These
@@ -90,7 +96,7 @@ subsystem interfaces. This allows to have multiple common services attached to
the same device without blocking attachment of a device-specific driver.
3. Subsystem Initialization
----------------------------
+===========================
In order to initialize the RapidIO subsystem, a platform must initialize and
register at least one master port within the RapidIO network. To register mport
@@ -105,7 +111,7 @@ RapidIO subsystem can be configured to be built as a statically linked or
modular component of the kernel (see details below).
4. Enumeration and Discovery
-----------------------------
+============================
4.1 Overview
------------
@@ -168,14 +174,16 @@ on RapidIO subsystem build configuration:
(b) If the RapidIO subsystem core is built as a loadable module, in addition
to the method shown above, the host destination ID(s) can be specified using
traditional methods of passing module parameter "hdid=" during its loading:
+
- from command line: "modprobe rapidio hdid=-1,7", or
- from modprobe configuration file using configuration command "options",
like in this example: "options rapidio hdid=-1,7". An example of modprobe
configuration file is provided in the section below.
- NOTES:
+NOTES:
(i) if "hdid=" parameter is omitted all available mport will be assigned
destination ID = -1;
+
(ii) the "hdid=" parameter in systems with multiple mports can have
destination ID assignments omitted from the end of list (default = -1).
@@ -317,8 +325,7 @@ must ensure that they are loaded before the enumeration/discovery starts.
This process can be automated by specifying pre- or post- dependencies in the
RapidIO-specific modprobe configuration file as shown in the example below.
- File /etc/modprobe.d/rapidio.conf:
- ----------------------------------
+File /etc/modprobe.d/rapidio.conf::
# Configure RapidIO subsystem modules
@@ -335,17 +342,21 @@ RapidIO-specific modprobe configuration file as shown in the example below.
--------------------------
-NOTE: In the example above, one of "softdep" commands must be removed or
-commented out to keep required module loading sequence.
+NOTE:
+ In the example above, one of "softdep" commands must be removed or
+ commented out to keep required module loading sequence.
-A. References
--------------
+5. References
+=============
[1] RapidIO Trade Association. RapidIO Interconnect Specifications.
http://www.rapidio.org.
+
[2] Rapidio TA. Technology Comparisons.
http://www.rapidio.org/education/technology_comparisons/
+
[3] RapidIO support for Linux.
http://lwn.net/Articles/139118/
+
[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005
http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf
diff --git a/Documentation/rapidio/rio_cm.txt b/Documentation/rapidio/rio_cm.rst
similarity index 76%
rename from Documentation/rapidio/rio_cm.txt
rename to Documentation/rapidio/rio_cm.rst
index 27aa401f1126..5294430a7a74 100644
--- a/Documentation/rapidio/rio_cm.txt
+++ b/Documentation/rapidio/rio_cm.rst
@@ -1,13 +1,10 @@
+==========================================================================
RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
==========================================================================
-Version History:
-----------------
- 1.0.0 - Initial driver release.
-==========================================================================
-
-I. Overview
+1. Overview
+===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Prodrive Technologies,
@@ -41,79 +38,98 @@ in /dev directory common for all registered RapidIO mport devices.
Following ioctl commands are available to user-space applications:
-- RIO_CM_MPORT_GET_LIST : Returns to caller list of local mport devices that
+- RIO_CM_MPORT_GET_LIST:
+ Returns to caller list of local mport devices that
support messaging operations (number of entries up to RIO_MAX_MPORTS).
Each list entry is combination of mport's index in the system and RapidIO
destination ID assigned to the port.
-- RIO_CM_EP_GET_LIST_SIZE : Returns number of messaging capable remote endpoints
+- RIO_CM_EP_GET_LIST_SIZE:
+ Returns number of messaging capable remote endpoints
in a RapidIO network associated with the specified mport device.
-- RIO_CM_EP_GET_LIST : Returns list of RapidIO destination IDs for messaging
+- RIO_CM_EP_GET_LIST:
+ Returns list of RapidIO destination IDs for messaging
capable remote endpoints (peers) available in a RapidIO network associated
with the specified mport device.
-- RIO_CM_CHAN_CREATE : Creates RapidIO message exchange channel data structure
+- RIO_CM_CHAN_CREATE:
+ Creates RapidIO message exchange channel data structure
with channel ID assigned automatically or as requested by a caller.
-- RIO_CM_CHAN_BIND : Binds the specified channel data structure to the specified
+- RIO_CM_CHAN_BIND:
+ Binds the specified channel data structure to the specified
mport device.
-- RIO_CM_CHAN_LISTEN : Enables listening for connection requests on the specified
+- RIO_CM_CHAN_LISTEN:
+ Enables listening for connection requests on the specified
channel.
-- RIO_CM_CHAN_ACCEPT : Accepts a connection request from peer on the specified
+- RIO_CM_CHAN_ACCEPT:
+ Accepts a connection request from peer on the specified
channel. If wait timeout for this request is specified by a caller it is
a blocking call. If timeout set to 0 this is non-blocking call - ioctl
handler checks for a pending connection request and if one is not available
exits with -EGAIN error status immediately.
-- RIO_CM_CHAN_CONNECT : Sends a connection request to a remote peer/channel.
-- RIO_CM_CHAN_SEND : Sends a data message through the specified channel.
+- RIO_CM_CHAN_CONNECT:
+ Sends a connection request to a remote peer/channel.
+- RIO_CM_CHAN_SEND:
+ Sends a data message through the specified channel.
The handler for this request assumes that message buffer specified by
a caller includes the reserved space for a packet header required by
this driver.
-- RIO_CM_CHAN_RECEIVE : Receives a data message through a connected channel.
+- RIO_CM_CHAN_RECEIVE:
+ Receives a data message through a connected channel.
If the channel does not have an incoming message ready to return this ioctl
handler will wait for new message until timeout specified by a caller
expires. If timeout value is set to 0, ioctl handler uses a default value
defined by MAX_SCHEDULE_TIMEOUT.
-- RIO_CM_CHAN_CLOSE : Closes a specified channel and frees associated buffers.
+- RIO_CM_CHAN_CLOSE:
+ Closes a specified channel and frees associated buffers.
If the specified channel is in the CONNECTED state, sends close notification
to the remote peer.
The ioctl command codes and corresponding data structures intended for use by
user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'.
-II. Hardware Compatibility
+2. Hardware Compatibility
+=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
subsystem with limitations set by available mport HW implementation of messaging
mailboxes.
-III. Module parameters
+3. Module parameters
+====================
-- 'dbg_level' - This parameter allows to control amount of debug information
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional block.
For mask definitions see 'drivers/rapidio/devices/rio_cm.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-- 'cmbox' - Number of RapidIO mailbox to use (default value is 1).
+- 'cmbox'
+ - Number of RapidIO mailbox to use (default value is 1).
This parameter allows to set messaging mailbox number that will be used
within entire RapidIO network. It can be used when default mailbox is
used by other device drivers or is not supported by some nodes in the
RapidIO network.
-- 'chstart' - Start channel number for dynamic assignment. Default value - 256.
+- 'chstart'
+ - Start channel number for dynamic assignment. Default value - 256.
Allows to exclude channel numbers below this parameter from dynamic
allocation to avoid conflicts with software components that use
reserved predefined channel numbers.
-IV. Known problems
+4. Known problems
+=================
None.
-V. User-space Applications and API Library
+5. User-space Applications and API Library
+==========================================
Messaging API library and applications that use this device driver are available
from RapidIO.org.
-VI. TODO List
+6. TODO List
+============
- Add support for system notification messages (reserved channel 0).
diff --git a/Documentation/rapidio/sysfs.txt b/Documentation/rapidio/sysfs.rst
similarity index 75%
rename from Documentation/rapidio/sysfs.txt
rename to Documentation/rapidio/sysfs.rst
index a1adac888e6e..540f72683496 100644
--- a/Documentation/rapidio/sysfs.txt
+++ b/Documentation/rapidio/sysfs.rst
@@ -1,3 +1,7 @@
+=============
+Sysfs entries
+=============
+
The RapidIO sysfs files have moved to:
Documentation/ABI/testing/sysfs-bus-rapidio and
Documentation/ABI/testing/sysfs-class-rapidio
diff --git a/Documentation/rapidio/tsi721.txt b/Documentation/rapidio/tsi721.rst
similarity index 79%
rename from Documentation/rapidio/tsi721.txt
rename to Documentation/rapidio/tsi721.rst
index cd2a2935d51d..42aea438cd20 100644
--- a/Documentation/rapidio/tsi721.txt
+++ b/Documentation/rapidio/tsi721.rst
@@ -1,7 +1,9 @@
+=========================================================================
RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
=========================================================================
-I. Overview
+1. Overview
+===========
This driver implements all currently defined RapidIO mport callback functions.
It supports maintenance read and write operations, inbound and outbound RapidIO
@@ -17,7 +19,9 @@ into the corresponding message queue. Messaging callbacks are implemented to be
fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
1. Module parameters:
-- 'dbg_level' - This parameter allows to control amount of debug information
+
+- 'dbg_level'
+ - This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
This parameter can be changed bit masks that correspond to the specific
functional block.
@@ -25,37 +29,44 @@ fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
-- 'dma_desc_per_channel' - This parameter defines number of hardware buffer
+- 'dma_desc_per_channel'
+ - This parameter defines number of hardware buffer
descriptors allocated for each registered Tsi721 DMA channel.
Its default value is 128.
-- 'dma_txqueue_sz' - DMA transactions queue size. Defines number of pending
+- 'dma_txqueue_sz'
+ - DMA transactions queue size. Defines number of pending
transaction requests that can be accepted by each DMA channel.
Default value is 16.
-- 'dma_sel' - DMA channel selection mask. Bitmask that defines which hardware
+- 'dma_sel'
+ - DMA channel selection mask. Bitmask that defines which hardware
DMA channels (0 ... 6) will be registered with DmaEngine core.
If bit is set to 1, the corresponding DMA channel will be registered.
DMA channels not selected by this mask will not be used by this device
driver. Default value is 0x7f (use all channels).
-- 'pcie_mrrs' - override value for PCIe Maximum Read Request Size (MRRS).
+- 'pcie_mrrs'
+ - override value for PCIe Maximum Read Request Size (MRRS).
This parameter gives an ability to override MRRS value set during PCIe
configuration process. Tsi721 supports read request sizes up to 4096B.
Value for this parameter must be set as defined by PCIe specification:
0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B.
Default value is '-1' (= keep platform setting).
-- 'mbox_sel' - RIO messaging MBOX selection mask. This is a bitmask that defines
+- 'mbox_sel'
+ - RIO messaging MBOX selection mask. This is a bitmask that defines
messaging MBOXes are managed by this device driver. Mask bits 0 - 3
correspond to MBOX0 - MBOX3. MBOX is under driver's control if the
corresponding bit is set to '1'. Default value is 0x0f (= all).
-II. Known problems
+2. Known problems
+=================
None.
-III. DMA Engine Support
+3. DMA Engine Support
+=====================
Tsi721 mport driver supports DMA data transfers between local system memory and
remote RapidIO devices. This functionality is implemented according to SLAVE
@@ -68,17 +79,21 @@ One BDMA channel is reserved for generation of maintenance read/write requests.
If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included,
this driver will accept DMA-specific module parameter:
- "dma_desc_per_channel" - defines number of hardware buffer descriptors used by
+
+ "dma_desc_per_channel"
+ - defines number of hardware buffer descriptors used by
each BDMA channel of Tsi721 (by default - 128).
-IV. Version History
+4. Version History
- 1.1.0 - DMA operations re-worked to support data scatter/gather lists larger
+ ===== ====================================================================
+ 1.1.0 DMA operations re-worked to support data scatter/gather lists larger
than hardware buffer descriptors ring.
- 1.0.0 - Initial driver release.
+ 1.0.0 Initial driver release.
+ ===== ====================================================================
-V. License
------------------------------------------------
+5. License
+===========
Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved.
diff --git a/drivers/rapidio/Kconfig b/drivers/rapidio/Kconfig
index fadafc64705f..467e8fa06904 100644
--- a/drivers/rapidio/Kconfig
+++ b/drivers/rapidio/Kconfig
@@ -86,7 +86,7 @@ config RAPIDIO_CHMAN
This option includes RapidIO channelized messaging driver which
provides socket-like interface to allow sharing of single RapidIO
messaging mailbox between multiple user-space applications.
- See "Documentation/rapidio/rio_cm.txt" for driver description.
+ See "Documentation/rapidio/rio_cm.rst" for driver description.
config RAPIDIO_MPORT_CDEV
tristate "RapidIO /dev mport device driver"
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 37/43] docs: blockdev: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (34 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 36/43] docs: rapidio: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 38/43] docs: perf: " Mauro Carvalho Chehab
` (6 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jens Axboe, Jiri Kosina, Minchan Kim,
Nitin Gupta, Sergey Senozhatsky, Shuah Khan, linux-block,
linux-kselftest
Rename the blockdev documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
The drbd sub-directory contains some graphs and data flows.
Add those too to the documentation.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../admin-guide/kernel-parameters.txt | 18 +-
...structure-v9.txt => data-structure-v9.rst} | 6 +-
Documentation/blockdev/drbd/figures.rst | 28 +++
.../blockdev/drbd/{README.txt => index.rst} | 15 +-
.../blockdev/{floppy.txt => floppy.rst} | 88 ++++----
Documentation/blockdev/index.rst | 16 ++
Documentation/blockdev/{nbd.txt => nbd.rst} | 2 +-
.../blockdev/{paride.txt => paride.rst} | 194 +++++++++--------
.../blockdev/{ramdisk.txt => ramdisk.rst} | 55 ++---
Documentation/blockdev/{zram.txt => zram.rst} | 195 ++++++++++++------
MAINTAINERS | 8 +-
drivers/block/Kconfig | 8 +-
drivers/block/floppy.c | 2 +-
drivers/block/zram/Kconfig | 6 +-
tools/testing/selftests/zram/README | 2 +-
15 files changed, 398 insertions(+), 245 deletions(-)
rename Documentation/blockdev/drbd/{data-structure-v9.txt => data-structure-v9.rst} (94%)
create mode 100644 Documentation/blockdev/drbd/figures.rst
rename Documentation/blockdev/drbd/{README.txt => index.rst} (55%)
rename Documentation/blockdev/{floppy.txt => floppy.rst} (81%)
create mode 100644 Documentation/blockdev/index.rst
rename Documentation/blockdev/{nbd.txt => nbd.rst} (96%)
rename Documentation/blockdev/{paride.txt => paride.rst} (81%)
rename Documentation/blockdev/{ramdisk.txt => ramdisk.rst} (84%)
rename Documentation/blockdev/{zram.txt => zram.rst} (76%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 92d335837c52..7ed94527a4a0 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1249,7 +1249,7 @@
See also Documentation/fault-injection/.
floppy= [HW]
- See Documentation/blockdev/floppy.txt.
+ See Documentation/blockdev/floppy.rst.
force_pal_cache_flush
[IA-64] Avoid check_sal_cache_flush which may hang on
@@ -2247,7 +2247,7 @@
memblock=debug [KNL] Enable memblock debug messages.
load_ramdisk= [RAM] List of ramdisks to load from floppy
- See Documentation/blockdev/ramdisk.txt.
+ See Documentation/blockdev/ramdisk.rst.
lockd.nlm_grace_period=P [NFS] Assign grace period.
Format: <integer>
@@ -3294,7 +3294,7 @@
pcd. [PARIDE]
See header of drivers/block/paride/pcd.c.
- See also Documentation/blockdev/paride.txt.
+ See also Documentation/blockdev/paride.rst.
pci=option[,option...] [PCI] various PCI subsystem options.
@@ -3538,7 +3538,7 @@
needed on a platform with proper driver support.
pd. [PARIDE]
- See Documentation/blockdev/paride.txt.
+ See Documentation/blockdev/paride.rst.
pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at
boot time.
@@ -3553,10 +3553,10 @@
and performance comparison.
pf. [PARIDE]
- See Documentation/blockdev/paride.txt.
+ See Documentation/blockdev/paride.rst.
pg. [PARIDE]
- See Documentation/blockdev/paride.txt.
+ See Documentation/blockdev/paride.rst.
pirq= [SMP,APIC] Manual mp-table setup
See Documentation/x86/i386/IO-APIC.rst.
@@ -3668,7 +3668,7 @@
prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk
before loading.
- See Documentation/blockdev/ramdisk.txt.
+ See Documentation/blockdev/ramdisk.rst.
psi= [KNL] Enable or disable pressure stall information
tracking.
@@ -3690,7 +3690,7 @@
pstore.backend= Specify the name of the pstore backend to use
pt. [PARIDE]
- See Documentation/blockdev/paride.txt.
+ See Documentation/blockdev/paride.rst.
pti= [X86_64] Control Page Table Isolation of user and
kernel address spaces. Disabling this feature
@@ -3719,7 +3719,7 @@
See Documentation/admin-guide/md.rst.
ramdisk_size= [RAM] Sizes of RAM disks in kilobytes
- See Documentation/blockdev/ramdisk.txt.
+ See Documentation/blockdev/ramdisk.rst.
random.trust_cpu={on,off}
[KNL] Enable or disable trusting the use of the
diff --git a/Documentation/blockdev/drbd/data-structure-v9.txt b/Documentation/blockdev/drbd/data-structure-v9.rst
similarity index 94%
rename from Documentation/blockdev/drbd/data-structure-v9.txt
rename to Documentation/blockdev/drbd/data-structure-v9.rst
index 1e52a0e32624..66036b901644 100644
--- a/Documentation/blockdev/drbd/data-structure-v9.txt
+++ b/Documentation/blockdev/drbd/data-structure-v9.rst
@@ -1,3 +1,7 @@
+================================
+kernel data structure for DRBD-9
+================================
+
This describes the in kernel data structure for DRBD-9. Starting with
Linux v3.14 we are reorganizing DRBD to use this data structure.
@@ -10,7 +14,7 @@ device is represented by a block device locally.
The DRBD objects are interconnected to form a matrix as depicted below; a
drbd_peer_device object sits at each intersection between a drbd_device and a
-drbd_connection:
+drbd_connection::
/--------------+---------------+.....+---------------\
| resource | device | | device |
diff --git a/Documentation/blockdev/drbd/figures.rst b/Documentation/blockdev/drbd/figures.rst
new file mode 100644
index 000000000000..3e3fd4b8a478
--- /dev/null
+++ b/Documentation/blockdev/drbd/figures.rst
@@ -0,0 +1,28 @@
+.. The here included files are intended to help understand the implementation
+
+Data flows that Relate some functions, and write packets
+========================================================
+
+.. kernel-figure:: DRBD-8.3-data-packets.svg
+ :alt: DRBD-8.3-data-packets.svg
+ :align: center
+
+.. kernel-figure:: DRBD-data-packets.svg
+ :alt: DRBD-data-packets.svg
+ :align: center
+
+
+Sub graphs of DRBD's state transitions
+======================================
+
+.. kernel-figure:: conn-states-8.dot
+ :alt: conn-states-8.dot
+ :align: center
+
+.. kernel-figure:: disk-states-8.dot
+ :alt: disk-states-8.dot
+ :align: center
+
+.. kernel-figure:: node-states-8.dot
+ :alt: node-states-8.dot
+ :align: center
diff --git a/Documentation/blockdev/drbd/README.txt b/Documentation/blockdev/drbd/index.rst
similarity index 55%
rename from Documentation/blockdev/drbd/README.txt
rename to Documentation/blockdev/drbd/index.rst
index 627b0a1bf35e..68ecd5c113e9 100644
--- a/Documentation/blockdev/drbd/README.txt
+++ b/Documentation/blockdev/drbd/index.rst
@@ -1,4 +1,9 @@
+==========================================
+Distributed Replicated Block Device - DRBD
+==========================================
+
Description
+===========
DRBD is a shared-nothing, synchronously replicated block device. It
is designed to serve as a building block for high availability
@@ -7,10 +12,8 @@ Description
Please visit http://www.drbd.org to find out more.
-The here included files are intended to help understand the implementation
+.. toctree::
+ :maxdepth: 1
-DRBD-8.3-data-packets.svg, DRBD-data-packets.svg
- relates some functions, and write packets.
-
-conn-states-8.dot, disk-states-8.dot, node-states-8.dot
- The sub graphs of DRBD's state transitions
+ data-structure-v9
+ figures
diff --git a/Documentation/blockdev/floppy.txt b/Documentation/blockdev/floppy.rst
similarity index 81%
rename from Documentation/blockdev/floppy.txt
rename to Documentation/blockdev/floppy.rst
index e2240f5ab64d..4a8f31cf4139 100644
--- a/Documentation/blockdev/floppy.txt
+++ b/Documentation/blockdev/floppy.rst
@@ -1,35 +1,37 @@
-This file describes the floppy driver.
+=============
+Floppy Driver
+=============
FAQ list:
=========
- A FAQ list may be found in the fdutils package (see below), and also
+A FAQ list may be found in the fdutils package (see below), and also
at <http://fdutils.linux.lu/faq.html>.
LILO configuration options (Thinkpad users, read this)
======================================================
- The floppy driver is configured using the 'floppy=' option in
+The floppy driver is configured using the 'floppy=' option in
lilo. This option can be typed at the boot prompt, or entered in the
lilo configuration file.
- Example: If your kernel is called linux-2.6.9, type the following line
-at the lilo boot prompt (if you have a thinkpad):
+Example: If your kernel is called linux-2.6.9, type the following line
+at the lilo boot prompt (if you have a thinkpad)::
linux-2.6.9 floppy=thinkpad
You may also enter the following line in /etc/lilo.conf, in the description
-of linux-2.6.9:
+of linux-2.6.9::
append = "floppy=thinkpad"
- Several floppy related options may be given, example:
+Several floppy related options may be given, example::
linux-2.6.9 floppy=daring floppy=two_fdc
append = "floppy=daring floppy=two_fdc"
- If you give options both in the lilo config file and on the boot
+If you give options both in the lilo config file and on the boot
prompt, the option strings of both places are concatenated, the boot
prompt options coming last. That's why there are also options to
restore the default behavior.
@@ -38,21 +40,23 @@ restore the default behavior.
Module configuration options
============================
- If you use the floppy driver as a module, use the following syntax:
-modprobe floppy floppy="<options>"
+If you use the floppy driver as a module, use the following syntax::
-Example:
- modprobe floppy floppy="omnibook messages"
+ modprobe floppy floppy="<options>"
- If you need certain options enabled every time you load the floppy driver,
-you can put:
+Example::
- options floppy floppy="omnibook messages"
+ modprobe floppy floppy="omnibook messages"
+
+If you need certain options enabled every time you load the floppy driver,
+you can put::
+
+ options floppy floppy="omnibook messages"
in a configuration file in /etc/modprobe.d/.
- The floppy driver related options are:
+The floppy driver related options are:
floppy=asus_pci
Sets the bit mask to allow only units 0 and 1. (default)
@@ -70,8 +74,7 @@ in a configuration file in /etc/modprobe.d/.
Tells the floppy driver that you have only one floppy controller.
(default)
- floppy=two_fdc
- floppy=<address>,two_fdc
+ floppy=two_fdc / floppy=<address>,two_fdc
Tells the floppy driver that you have two floppy controllers.
The second floppy controller is assumed to be at <address>.
This option is not needed if the second controller is at address
@@ -84,8 +87,7 @@ in a configuration file in /etc/modprobe.d/.
floppy=0,thinkpad
Tells the floppy driver that you don't have a Thinkpad.
- floppy=omnibook
- floppy=nodma
+ floppy=omnibook / floppy=nodma
Tells the floppy driver not to use Dma for data transfers.
This is needed on HP Omnibooks, which don't have a workable
DMA channel for the floppy driver. This option is also useful
@@ -144,14 +146,16 @@ in a configuration file in /etc/modprobe.d/.
described in the physical CMOS), or if your BIOS uses
non-standard CMOS types. The CMOS types are:
- 0 - Use the value of the physical CMOS
- 1 - 5 1/4 DD
- 2 - 5 1/4 HD
- 3 - 3 1/2 DD
- 4 - 3 1/2 HD
- 5 - 3 1/2 ED
- 6 - 3 1/2 ED
- 16 - unknown or not installed
+ == ==================================
+ 0 Use the value of the physical CMOS
+ 1 5 1/4 DD
+ 2 5 1/4 HD
+ 3 3 1/2 DD
+ 4 3 1/2 HD
+ 5 3 1/2 ED
+ 6 3 1/2 ED
+ 16 unknown or not installed
+ == ==================================
(Note: there are two valid types for ED drives. This is because 5 was
initially chosen to represent floppy *tapes*, and 6 for ED drives.
@@ -162,8 +166,7 @@ in a configuration file in /etc/modprobe.d/.
Print a warning message when an unexpected interrupt is received.
(default)
- floppy=no_unexpected_interrupts
- floppy=L40SX
+ floppy=no_unexpected_interrupts / floppy=L40SX
Don't print a message when an unexpected interrupt is received. This
is needed on IBM L40SX laptops in certain video modes. (There seems
to be an interaction between video and floppy. The unexpected
@@ -199,47 +202,54 @@ in a configuration file in /etc/modprobe.d/.
Sets the floppy DMA channel to <nr> instead of 2.
floppy=slow
- Use PS/2 stepping rate:
- " PS/2 floppies have much slower step rates than regular floppies.
+ Use PS/2 stepping rate::
+
+ PS/2 floppies have much slower step rates than regular floppies.
It's been recommended that take about 1/4 of the default speed
- in some more extreme cases."
+ in some more extreme cases.
Supporting utilities and additional documentation:
==================================================
- Additional parameters of the floppy driver can be configured at
+Additional parameters of the floppy driver can be configured at
runtime. Utilities which do this can be found in the fdutils package.
This package also contains a new version of mtools which allows to
access high capacity disks (up to 1992K on a high density 3 1/2 disk!).
It also contains additional documentation about the floppy driver.
The latest version can be found at fdutils homepage:
+
http://fdutils.linux.lu
The fdutils releases can be found at:
+
http://fdutils.linux.lu/download.html
+
http://www.tux.org/pub/knaff/fdutils/
+
ftp://metalab.unc.edu/pub/Linux/utils/disk-management/
Reporting problems about the floppy driver
==========================================
- If you have a question or a bug report about the floppy driver, mail
+If you have a question or a bug report about the floppy driver, mail
me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use
comp.os.linux.hardware. As the volume in these groups is rather high,
be sure to include the word "floppy" (or "FLOPPY") in the subject
line. If the reported problem happens when mounting floppy disks, be
sure to mention also the type of the filesystem in the subject line.
- Be sure to read the FAQ before mailing/posting any bug reports!
+Be sure to read the FAQ before mailing/posting any bug reports!
- Alain
+Alain
Changelog
=========
-10-30-2004 : Cleanup, updating, add reference to module configuration.
+10-30-2004 :
+ Cleanup, updating, add reference to module configuration.
James Nelson <james4765@gmail.com>
-6-3-2000 : Original Document
+6-3-2000 :
+ Original Document
diff --git a/Documentation/blockdev/index.rst b/Documentation/blockdev/index.rst
new file mode 100644
index 000000000000..a9af6ed8b4aa
--- /dev/null
+++ b/Documentation/blockdev/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+===========================
+The Linux RapidIO Subsystem
+===========================
+
+.. toctree::
+ :maxdepth: 1
+
+ floppy
+ nbd
+ paride
+ ramdisk
+ zram
+
+ drbd/index
diff --git a/Documentation/blockdev/nbd.txt b/Documentation/blockdev/nbd.rst
similarity index 96%
rename from Documentation/blockdev/nbd.txt
rename to Documentation/blockdev/nbd.rst
index db242ea2bce8..d78dfe559dcf 100644
--- a/Documentation/blockdev/nbd.txt
+++ b/Documentation/blockdev/nbd.rst
@@ -1,3 +1,4 @@
+==================================
Network Block Device (TCP version)
==================================
@@ -28,4 +29,3 @@ max_part
nbds_max
Number of block devices that should be initialized (default: 16).
-
diff --git a/Documentation/blockdev/paride.txt b/Documentation/blockdev/paride.rst
similarity index 81%
rename from Documentation/blockdev/paride.txt
rename to Documentation/blockdev/paride.rst
index ee6717e3771d..87b4278bf314 100644
--- a/Documentation/blockdev/paride.txt
+++ b/Documentation/blockdev/paride.rst
@@ -1,15 +1,17 @@
-
- Linux and parallel port IDE devices
+===================================
+Linux and parallel port IDE devices
+===================================
PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net>
1. Introduction
+===============
Owing to the simplicity and near universality of the parallel port interface
to personal computers, many external devices such as portable hard-disk,
CD-ROM, LS-120 and tape drives use the parallel port to connect to their
host computer. While some devices (notably scanners) use ad-hoc methods
-to pass commands and data through the parallel port interface, most
+to pass commands and data through the parallel port interface, most
external devices are actually identical to an internal model, but with
a parallel-port adapter chip added in. Some of the original parallel port
adapters were little more than mechanisms for multiplexing a SCSI bus.
@@ -28,47 +30,50 @@ were to open up a parallel port CD-ROM drive, for instance, one would
find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
that interconnected a standard PC parallel port cable and a standard
IDE cable. It is usually possible to exchange the CD-ROM device with
-any other device using the IDE interface.
+any other device using the IDE interface.
The document describes the support in Linux for parallel port IDE
devices. It does not cover parallel port SCSI devices, "ditto" tape
-drives or scanners. Many different devices are supported by the
+drives or scanners. Many different devices are supported by the
parallel port IDE subsystem, including:
- MicroSolutions backpack CD-ROM
- MicroSolutions backpack PD/CD
- MicroSolutions backpack hard-drives
- MicroSolutions backpack 8000t tape drive
- SyQuest EZ-135, EZ-230 & SparQ drives
- Avatar Shark
- Imation Superdisk LS-120
- Maxell Superdisk LS-120
- FreeCom Power CD
- Hewlett-Packard 5GB and 8GB tape drives
- Hewlett-Packard 7100 and 7200 CD-RW drives
+ - MicroSolutions backpack CD-ROM
+ - MicroSolutions backpack PD/CD
+ - MicroSolutions backpack hard-drives
+ - MicroSolutions backpack 8000t tape drive
+ - SyQuest EZ-135, EZ-230 & SparQ drives
+ - Avatar Shark
+ - Imation Superdisk LS-120
+ - Maxell Superdisk LS-120
+ - FreeCom Power CD
+ - Hewlett-Packard 5GB and 8GB tape drives
+ - Hewlett-Packard 7100 and 7200 CD-RW drives
as well as most of the clone and no-name products on the market.
To support such a wide range of devices, PARIDE, the parallel port IDE
subsystem, is actually structured in three parts. There is a base
paride module which provides a registry and some common methods for
-accessing the parallel ports. The second component is a set of
-high-level drivers for each of the different types of supported devices:
+accessing the parallel ports. The second component is a set of
+high-level drivers for each of the different types of supported devices:
+ === =============
pd IDE disk
pcd ATAPI CD-ROM
pf ATAPI disk
pt ATAPI tape
pg ATAPI generic
+ === =============
(Currently, the pg driver is only used with CD-R drives).
The high-level drivers function according to the relevant standards.
The third component of PARIDE is a set of low-level protocol drivers
for each of the parallel port IDE adapter chips. Thanks to the interest
-and encouragement of Linux users from many parts of the world,
+and encouragement of Linux users from many parts of the world,
support is available for almost all known adapter protocols:
+ ==== ====================================== ====
aten ATEN EH-100 (HK)
bpck Microsolutions backpack (US)
comm DataStor (old-type) "commuter" adapter (TW)
@@ -83,9 +88,11 @@ support is available for almost all known adapter protocols:
ktti KT Technology PHd adapter (SG)
on20 OnSpec 90c20 (US)
on26 OnSpec 90c26 (US)
+ ==== ====================================== ====
2. Using the PARIDE subsystem
+=============================
While configuring the Linux kernel, you may choose either to build
the PARIDE drivers into your kernel, or to build them as modules.
@@ -94,10 +101,10 @@ In either case, you will need to select "Parallel port IDE device support"
as well as at least one of the high-level drivers and at least one
of the parallel port communication protocols. If you do not know
what kind of parallel port adapter is used in your drive, you could
-begin by checking the file names and any text files on your DOS
+begin by checking the file names and any text files on your DOS
installation floppy. Alternatively, you can look at the markings on
the adapter chip itself. That's usually sufficient to identify the
-correct device.
+correct device.
You can actually select all the protocol modules, and allow the PARIDE
subsystem to try them all for you.
@@ -105,8 +112,9 @@ subsystem to try them all for you.
For the "brand-name" products listed above, here are the protocol
and high-level drivers that you would use:
+ ================ ============ ====== ========
Manufacturer Model Driver Protocol
-
+ ================ ============ ====== ========
MicroSolutions CD-ROM pcd bpck
MicroSolutions PD drive pf bpck
MicroSolutions hard-drive pd bpck
@@ -119,8 +127,10 @@ and high-level drivers that you would use:
Hewlett-Packard 5GB Tape pt epat
Hewlett-Packard 7200e (CD) pcd epat
Hewlett-Packard 7200e (CD-R) pg epat
+ ================ ============ ====== ========
2.1 Configuring built-in drivers
+---------------------------------
We recommend that you get to know how the drivers work and how to
configure them as loadable modules, before attempting to compile a
@@ -143,7 +153,7 @@ protocol identification number and, for some devices, the drive's
chain ID. While your system is booting, a number of messages are
displayed on the console. Like all such messages, they can be
reviewed with the 'dmesg' command. Among those messages will be
-some lines like:
+some lines like::
paride: bpck registered as protocol 0
paride: epat registered as protocol 1
@@ -158,10 +168,10 @@ the last two digits of the drive's serial number (but read MicroSolutions'
documentation about this).
As an example, let's assume that you have a MicroSolutions PD/CD drive
-with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
-EZ-135 connected to the chained port on the PD/CD drive and also an
-Imation Superdisk connected to port 0x278. You could give the following
-options on your boot command:
+with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
+EZ-135 connected to the chained port on the PD/CD drive and also an
+Imation Superdisk connected to port 0x278. You could give the following
+options on your boot command::
pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36
@@ -169,24 +179,27 @@ In the last option, pf.drive1 configures device /dev/pf1, the 0x378
is the parallel port base address, the 0 is the protocol registration
number and 36 is the chain ID.
-Please note: while PARIDE will work both with and without the
+Please note: while PARIDE will work both with and without the
PARPORT parallel port sharing system that is included by the
"Parallel port support" option, PARPORT must be included and enabled
if you want to use chains of devices on the same parallel port.
2.2 Loading and configuring PARIDE as modules
+----------------------------------------------
It is much faster and simpler to get to understand the PARIDE drivers
-if you use them as loadable kernel modules.
+if you use them as loadable kernel modules.
-Note 1: using these drivers with the "kerneld" automatic module loading
-system is not recommended for beginners, and is not documented here.
+Note 1:
+ using these drivers with the "kerneld" automatic module loading
+ system is not recommended for beginners, and is not documented here.
-Note 2: if you build PARPORT support as a loadable module, PARIDE must
-also be built as loadable modules, and PARPORT must be loaded before the
-PARIDE modules.
+Note 2:
+ if you build PARPORT support as a loadable module, PARIDE must
+ also be built as loadable modules, and PARPORT must be loaded before
+ the PARIDE modules.
-To use PARIDE, you must begin by
+To use PARIDE, you must begin by::
insmod paride
@@ -195,8 +208,8 @@ among other tasks.
Then, load as many of the protocol modules as you think you might need.
As you load each module, it will register the protocols that it supports,
-and print a log message to your kernel log file and your console. For
-example:
+and print a log message to your kernel log file and your console. For
+example::
# insmod epat
paride: epat registered as protocol 0
@@ -205,22 +218,22 @@ example:
paride: k971 registered as protocol 2
Finally, you can load high-level drivers for each kind of device that
-you have connected. By default, each driver will autoprobe for a single
+you have connected. By default, each driver will autoprobe for a single
device, but you can support up to four similar devices by giving their
individual co-ordinates when you load the driver.
For example, if you had two no-name CD-ROM drives both using the
KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
-you could give the following command:
+you could give the following command::
# insmod pcd drive0=0x378,1 drive1=0x3bc,1
For most adapters, giving a port address and protocol number is sufficient,
-but check the source files in linux/drivers/block/paride for more
+but check the source files in linux/drivers/block/paride for more
information. (Hopefully someone will write some man pages one day !).
As another example, here's what happens when PARPORT is installed, and
-a SyQuest EZ-135 is attached to port 0x378:
+a SyQuest EZ-135 is attached to port 0x378::
# insmod paride
paride: version 1.0 installed
@@ -237,46 +250,47 @@ Note that the last line is the output from the generic partition table
scanner - in this case it reports that it has found a disk with one partition.
2.3 Using a PARIDE device
+--------------------------
Once the drivers have been loaded, you can access PARIDE devices in the
same way as their traditional counterparts. You will probably need to
create the device "special files". Here is a simple script that you can
-cut to a file and execute:
+cut to a file and execute::
-#!/bin/bash
-#
-# mkd -- a script to create the device special files for the PARIDE subsystem
-#
-function mkdev {
- mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
-}
-#
-function pd {
- D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
- mkdev pd$D b 45 $[ $1 * 16 ]
- for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
- do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
- done
-}
-#
-cd /dev
-#
-for u in 0 1 2 3 ; do pd $u ; done
-for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done
-for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done
-for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done
-for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done
-for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done
-#
-# end of mkd
+ #!/bin/bash
+ #
+ # mkd -- a script to create the device special files for the PARIDE subsystem
+ #
+ function mkdev {
+ mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
+ }
+ #
+ function pd {
+ D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
+ mkdev pd$D b 45 $[ $1 * 16 ]
+ for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+ do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
+ done
+ }
+ #
+ cd /dev
+ #
+ for u in 0 1 2 3 ; do pd $u ; done
+ for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done
+ for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done
+ for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done
+ for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done
+ for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done
+ #
+ # end of mkd
With the device files and drivers in place, you can access PARIDE devices
-like any other Linux device. For example, to mount a CD-ROM in pcd0, use:
+like any other Linux device. For example, to mount a CD-ROM in pcd0, use::
mount /dev/pcd0 /cdrom
If you have a fresh Avatar Shark cartridge, and the drive is pda, you
-might do something like:
+might do something like::
fdisk /dev/pda -- make a new partition table with
partition 1 of type 83
@@ -289,41 +303,46 @@ might do something like:
Devices like the Imation superdisk work in the same way, except that
they do not have a partition table. For example to make a 120MB
-floppy that you could share with a DOS system:
+floppy that you could share with a DOS system::
mkdosfs /dev/pf0
mount /dev/pf0 /mnt
2.4 The pf driver
+------------------
The pf driver is intended for use with parallel port ATAPI disk
devices. The most common devices in this category are PD drives
and LS-120 drives. Traditionally, media for these devices are not
partitioned. Consequently, the pf driver does not support partitioned
-media. This may be changed in a future version of the driver.
+media. This may be changed in a future version of the driver.
2.5 Using the pt driver
+------------------------
The pt driver for parallel port ATAPI tape drives is a minimal driver.
-It does not yet support many of the standard tape ioctl operations.
+It does not yet support many of the standard tape ioctl operations.
For best performance, a block size of 32KB should be used. You will
probably want to set the parallel port delay to 0, if you can.
2.6 Using the pg driver
+------------------------
The pg driver can be used in conjunction with the cdrecord program
to create CD-ROMs. Please get cdrecord version 1.6.1 or later
-from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media
-your parallel port should ideally be set to EPP mode, and the "port delay"
-should be set to 0. With those settings it is possible to record at 2x
+from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media
+your parallel port should ideally be set to EPP mode, and the "port delay"
+should be set to 0. With those settings it is possible to record at 2x
speed without any buffer underruns. If you cannot get the driver to work
in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.
3. Troubleshooting
+==================
3.1 Use EPP mode if you can
+----------------------------
The most common problems that people report with the PARIDE drivers
concern the parallel port CMOS settings. At this time, none of the
@@ -332,6 +351,7 @@ If you are able to do so, please set your parallel port into EPP mode
using your CMOS setup procedure.
3.2 Check the port delay
+-------------------------
Some parallel ports cannot reliably transfer data at full speed. To
offset the errors, the PARIDE protocol modules introduce a "port
@@ -347,23 +367,25 @@ read the comments at the beginning of the driver source files in
linux/drivers/block/paride.
3.3 Some drives need a printer reset
+-------------------------------------
There appear to be a number of "noname" external drives on the market
that do not always power up correctly. We have noticed this with some
drives based on OnSpec and older Freecom adapters. In these rare cases,
the adapter can often be reinitialised by issuing a "printer reset" on
-the parallel port. As the reset operation is potentially disruptive in
-multiple device environments, the PARIDE drivers will not do it
-automatically. You can however, force a printer reset by doing:
+the parallel port. As the reset operation is potentially disruptive in
+multiple device environments, the PARIDE drivers will not do it
+automatically. You can however, force a printer reset by doing::
insmod lp reset=1
rmmod lp
If you have one of these marginal cases, you should probably build
your paride drivers as modules, and arrange to do the printer reset
-before loading the PARIDE drivers.
+before loading the PARIDE drivers.
3.4 Use the verbose option and dmesg if you need help
+------------------------------------------------------
While a lot of testing has gone into these drivers to make them work
as smoothly as possible, problems will arise. If you do have problems,
@@ -373,7 +395,7 @@ clues, then please make sure that only one drive is hooked to your system,
and that either (a) PARPORT is enabled or (b) no other device driver
is using your parallel port (check in /proc/ioports). Then, load the
appropriate drivers (you can load several protocol modules if you want)
-as in:
+as in::
# insmod paride
# insmod epat
@@ -394,12 +416,14 @@ by e-mail to grant@torque.net, or join the linux-parport mailing list
and post your report there.
3.5 For more information or help
+---------------------------------
You can join the linux-parport mailing list by sending a mail message
-to
+to:
+
linux-parport-request@torque.net
-with the single word
+with the single word::
subscribe
@@ -412,6 +436,4 @@ have in your mail headers, when sending mail to the list server.
You might also find some useful information on the linux-parport
web pages (although they are not always up to date) at
- http://web.archive.org/web/*/http://www.torque.net/parport/
-
-
+ http://web.archive.org/web/%2E/http://www.torque.net/parport/
diff --git a/Documentation/blockdev/ramdisk.txt b/Documentation/blockdev/ramdisk.rst
similarity index 84%
rename from Documentation/blockdev/ramdisk.txt
rename to Documentation/blockdev/ramdisk.rst
index 501e12e0323e..b7c2268f8dec 100644
--- a/Documentation/blockdev/ramdisk.txt
+++ b/Documentation/blockdev/ramdisk.rst
@@ -1,7 +1,8 @@
+==========================================
Using the RAM disk block device with Linux
-------------------------------------------
+==========================================
-Contents:
+.. Contents:
1) Overview
2) Kernel Command Line Parameters
@@ -42,7 +43,7 @@ rescue floppy disk.
2a) Kernel Command Line Parameters
ramdisk_size=N
- ==============
+ Size of the ramdisk.
This parameter tells the RAM disk driver to set up RAM disks of N k size. The
default is 4096 (4 MB).
@@ -50,16 +51,13 @@ default is 4096 (4 MB).
2b) Module parameters
rd_nr
- =====
- /dev/ramX devices created.
+ /dev/ramX devices created.
max_part
- ========
- Maximum partition number.
+ Maximum partition number.
rd_size
- =======
- See ramdisk_size.
+ See ramdisk_size.
3) Using "rdev -r"
------------------
@@ -71,11 +69,11 @@ to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit
prompt/wait sequence is to be given before trying to read the RAM disk. Since
the RAM disk dynamically grows as data is being written into it, a size field
is not required. Bits 11 to 13 are not currently used and may as well be zero.
-These numbers are no magical secrets, as seen below:
+These numbers are no magical secrets, as seen below::
-./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF
-./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000
-./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000
+ ./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF
+ ./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000
+ ./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000
Consider a typical two floppy disk setup, where you will have the
kernel on disk one, and have already put a RAM disk image onto disk #2.
@@ -92,20 +90,23 @@ sequence so that you have a chance to switch floppy disks.
The command line equivalent is: "prompt_ramdisk=1"
Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word.
-So to create disk one of the set, you would do:
+So to create disk one of the set, you would do::
/usr/src/linux# cat arch/x86/boot/zImage > /dev/fd0
/usr/src/linux# rdev /dev/fd0 /dev/fd0
/usr/src/linux# rdev -r /dev/fd0 49152
-If you make a boot disk that has LILO, then for the above, you would use:
+If you make a boot disk that has LILO, then for the above, you would use::
+
append = "ramdisk_start=0 load_ramdisk=1 prompt_ramdisk=1"
-Since the default start = 0 and the default prompt = 1, you could use:
+
+Since the default start = 0 and the default prompt = 1, you could use::
+
append = "load_ramdisk=1"
4) An Example of Creating a Compressed RAM Disk
-----------------------------------------------
+-----------------------------------------------
To create a RAM disk image, you will need a spare block device to
construct it on. This can be the RAM disk device itself, or an
@@ -120,11 +121,11 @@ a) Decide on the RAM disk size that you want. Say 2 MB for this example.
Create it by writing to the RAM disk device. (This step is not currently
required, but may be in the future.) It is wise to zero out the
area (esp. for disks) so that maximal compression is achieved for
- the unused blocks of the image that you are about to create.
+ the unused blocks of the image that you are about to create::
dd if=/dev/zero of=/dev/ram0 bs=1k count=2048
-b) Make a filesystem on it. Say ext2fs for this example.
+b) Make a filesystem on it. Say ext2fs for this example::
mke2fs -vm0 /dev/ram0 2048
@@ -133,11 +134,11 @@ c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...)
d) Compress the contents of the RAM disk. The level of compression
will be approximately 50% of the space used by the files. Unused
- space on the RAM disk will compress to almost nothing.
+ space on the RAM disk will compress to almost nothing::
dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz
-e) Put the kernel onto the floppy
+e) Put the kernel onto the floppy::
dd if=zImage of=/dev/fd0 bs=1k
@@ -146,13 +147,13 @@ f) Put the RAM disk image onto the floppy, after the kernel. Use an offset
(possibly larger) kernel onto the same floppy later without overlapping
the RAM disk image. An offset of 400 kB for kernels about 350 kB in
size would be reasonable. Make sure offset+size of ram_image.gz is
- not larger than the total space on your floppy (usually 1440 kB).
+ not larger than the total space on your floppy (usually 1440 kB)::
dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400
g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
For prompt_ramdisk=1, load_ramdisk=1, ramdisk_start=400, one would
- have 2^15 + 2^14 + 400 = 49552.
+ have 2^15 + 2^14 + 400 = 49552::
rdev /dev/fd0 /dev/fd0
rdev -r /dev/fd0 49552
@@ -160,15 +161,17 @@ g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
That is it. You now have your boot/root compressed RAM disk floppy. Some
users may wish to combine steps (d) and (f) by using a pipe.
---------------------------------------------------------------------------
+
Paul Gortmaker 12/95
Changelog:
----------
-10-22-04 : Updated to reflect changes in command line options, remove
+10-22-04 :
+ Updated to reflect changes in command line options, remove
obsolete references, general cleanup.
James Nelson (james4765@gmail.com)
-12-95 : Original Document
+12-95 :
+ Original Document
diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.rst
similarity index 76%
rename from Documentation/blockdev/zram.txt
rename to Documentation/blockdev/zram.rst
index 4df0ce271085..2111231c9c0f 100644
--- a/Documentation/blockdev/zram.txt
+++ b/Documentation/blockdev/zram.rst
@@ -1,7 +1,9 @@
+========================================
zram: Compressed RAM based block devices
-----------------------------------------
+========================================
-* Introduction
+Introduction
+============
The zram module creates RAM based block devices named /dev/zram<id>
(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
@@ -12,9 +14,11 @@ use as swap disks, various caches under /var and maybe many more :)
Statistics for individual zram devices are exported through sysfs nodes at
/sys/block/zram<id>/
-* Usage
+Usage
+=====
There are several ways to configure and manage zram device(-s):
+
a) using zram and zram_control sysfs attributes
b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
@@ -22,7 +26,7 @@ In this document we will describe only 'manual' zram configuration steps,
IOW, zram and zram_control sysfs attributes.
In order to get a better idea about zramctl please consult util-linux
-documentation, zramctl man-page or `zramctl --help'. Please be informed
+documentation, zramctl man-page or `zramctl --help`. Please be informed
that zram maintainers do not develop/maintain util-linux or zramctl, should
you have any questions please contact util-linux@vger.kernel.org
@@ -30,19 +34,23 @@ Following shows a typical sequence of steps for using zram.
WARNING
=======
+
For the sake of simplicity we skip error checking parts in most of the
examples below. However, it is your sole responsibility to handle errors.
zram sysfs attributes always return negative values in case of errors.
The list of possible return codes:
--EBUSY -- an attempt to modify an attribute that cannot be changed once
-the device has been initialised. Please reset device first;
--ENOMEM -- zram was not able to allocate enough memory to fulfil your
-needs;
--EINVAL -- invalid input has been provided.
+
+======== =============================================================
+-EBUSY an attempt to modify an attribute that cannot be changed once
+ the device has been initialised. Please reset device first;
+-ENOMEM zram was not able to allocate enough memory to fulfil your
+ needs;
+-EINVAL invalid input has been provided.
+======== =============================================================
If you use 'echo', the returned value that is changed by 'echo' utility,
-and, in general case, something like:
+and, in general case, something like::
echo 3 > /sys/block/zram0/max_comp_streams
if [ $? -ne 0 ];
@@ -51,7 +59,11 @@ and, in general case, something like:
should suffice.
-1) Load Module:
+1) Load Module
+==============
+
+::
+
modprobe zram num_devices=4
This creates 4 devices: /dev/zram{0,1,2,3}
@@ -59,6 +71,8 @@ num_devices parameter is optional and tells zram how many devices should be
pre-created. Default: 1.
2) Set max number of compression streams
+========================================
+
Regardless the value passed to this attribute, ZRAM will always
allocate multiple compression streams - one per online CPUs - thus
allowing several concurrent compression operations. The number of
@@ -66,16 +80,20 @@ allocated compression streams goes down when some of the CPUs
become offline. There is no single-compression-stream mode anymore,
unless you are running a UP system or has only 1 CPU online.
-To find out how many streams are currently available:
+To find out how many streams are currently available::
+
cat /sys/block/zram0/max_comp_streams
3) Select compression algorithm
+===============================
+
Using comp_algorithm device attribute one can see available and
currently selected (shown in square brackets) compression algorithms,
change selected compression algorithm (once the device is initialised
there is no way to change compression algorithm).
-Examples:
+Examples::
+
#show supported compression algorithms
cat /sys/block/zram0/comp_algorithm
lzo [lz4]
@@ -83,20 +101,23 @@ Examples:
#select lzo compression algorithm
echo lzo > /sys/block/zram0/comp_algorithm
-For the time being, the `comp_algorithm' content does not necessarily
+For the time being, the `comp_algorithm` content does not necessarily
show every compression algorithm supported by the kernel. We keep this
list primarily to simplify device configuration and one can configure
a new device with a compression algorithm that is not listed in
-`comp_algorithm'. The thing is that, internally, ZRAM uses Crypto API
+`comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API
and, if some of the algorithms were built as modules, it's impossible
to list all of them using, for instance, /proc/crypto or any other
method. This, however, has an advantage of permitting the usage of
custom crypto compression modules (implementing S/W or H/W compression).
4) Set Disksize
+===============
+
Set disk size by writing the value to sysfs node 'disksize'.
The value can be either in bytes or you can use mem suffixes.
-Examples:
+Examples::
+
# Initialize /dev/zram0 with 50MB disksize
echo $((50*1024*1024)) > /sys/block/zram0/disksize
@@ -111,10 +132,13 @@ since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
size of the disk when not in use so a huge zram is wasteful.
5) Set memory limit: Optional
+=============================
+
Set memory limit by writing the value to sysfs node 'mem_limit'.
The value can be either in bytes or you can use mem suffixes.
In addition, you could change the value in runtime.
-Examples:
+Examples::
+
# limit /dev/zram0 with 50MB memory
echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
@@ -126,7 +150,11 @@ Examples:
# To disable memory limit
echo 0 > /sys/block/zram0/mem_limit
-6) Activate:
+6) Activate
+===========
+
+::
+
mkswap /dev/zram0
swapon /dev/zram0
@@ -134,6 +162,7 @@ Examples:
mount /dev/zram1 /tmp
7) Add/remove zram devices
+==========================
zram provides a control interface, which enables dynamic (on-demand) device
addition and removal.
@@ -142,37 +171,44 @@ In order to add a new /dev/zramX device, perform read operation on hot_add
attribute. This will return either new device's device id (meaning that you
can use /dev/zram<id>) or error code.
-Example:
+Example::
+
cat /sys/class/zram-control/hot_add
1
To remove the existing /dev/zramX device (where X is a device id)
-execute
+execute::
+
echo X > /sys/class/zram-control/hot_remove
-8) Stats:
+8) Stats
+========
+
Per-device statistics are exported as various nodes under /sys/block/zram<id>/
A brief description of exported device attributes. For more details please
read Documentation/ABI/testing/sysfs-block-zram.
+====================== ====== ===============================================
Name access description
----- ------ -----------
+====================== ====== ===============================================
disksize RW show and set the device's disk size
initstate RO shows the initialization state of the device
reset WO trigger device reset
-mem_used_max WO reset the `mem_used_max' counter (see later)
-mem_limit WO specifies the maximum amount of memory ZRAM can use
- to store the compressed data
-writeback_limit WO specifies the maximum amount of write IO zram can
- write out to backing device as 4KB unit
+mem_used_max WO reset the `mem_used_max` counter (see later)
+mem_limit WO specifies the maximum amount of memory ZRAM can
+ use to store the compressed data
+writeback_limit WO specifies the maximum amount of write IO zram
+ can write out to backing device as 4KB unit
writeback_limit_enable RW show and set writeback_limit feature
-max_comp_streams RW the number of possible concurrent compress operations
+max_comp_streams RW the number of possible concurrent compress
+ operations
comp_algorithm RW show and change the compression algorithm
compact WO trigger memory compaction
debug_stat RO this file is used for zram debugging purposes
backing_dev RW set up backend storage for zram to write out
idle WO mark allocated slot as idle
+====================== ====== ===============================================
User space is advised to use the following files to read the device statistics.
@@ -188,23 +224,31 @@ The stat file represents device's I/O statistics not accounted by block
layer and, thus, not available in zram<id>/stat file. It consists of a
single line of text and contains the following stats separated by
whitespace:
- failed_reads the number of failed reads
- failed_writes the number of failed writes
- invalid_io the number of non-page-size-aligned I/O requests
+
+ ============= =============================================================
+ failed_reads The number of failed reads
+ failed_writes The number of failed writes
+ invalid_io The number of non-page-size-aligned I/O requests
notify_free Depending on device usage scenario it may account
+
a) the number of pages freed because of swap slot free
- notifications or b) the number of pages freed because of
- REQ_OP_DISCARD requests sent by bio. The former ones are
- sent to a swap block device when a swap slot is freed,
- which implies that this disk is being used as a swap disk.
+ notifications
+ b) the number of pages freed because of
+ REQ_OP_DISCARD requests sent by bio. The former ones are
+ sent to a swap block device when a swap slot is freed,
+ which implies that this disk is being used as a swap disk.
+
The latter ones are sent by filesystem mounted with
discard option, whenever some data blocks are getting
discarded.
+ ============= =============================================================
File /sys/block/zram<id>/mm_stat
The stat file represents device's mm statistics. It consists of a single
line of text and contains the following stats separated by whitespace:
+
+ ================ =============================================================
orig_data_size uncompressed size of data stored in this disk.
This excludes same-element-filled pages (same_pages) since
no memory is allocated for them.
@@ -223,58 +267,71 @@ line of text and contains the following stats separated by whitespace:
No memory is allocated for such pages.
pages_compacted the number of pages freed during compaction
huge_pages the number of incompressible pages
+ ================ =============================================================
File /sys/block/zram<id>/bd_stat
The stat file represents device's backing device statistics. It consists of
a single line of text and contains the following stats separated by whitespace:
+
+ ============== =============================================================
bd_count size of data written in backing device.
Unit: 4K bytes
bd_reads the number of reads from backing device
Unit: 4K bytes
bd_writes the number of writes to backing device
Unit: 4K bytes
+ ============== =============================================================
+
+9) Deactivate
+=============
+
+::
-9) Deactivate:
swapoff /dev/zram0
umount /dev/zram1
-10) Reset:
- Write any positive value to 'reset' sysfs node
- echo 1 > /sys/block/zram0/reset
- echo 1 > /sys/block/zram1/reset
+10) Reset
+=========
+
+ Write any positive value to 'reset' sysfs node::
+
+ echo 1 > /sys/block/zram0/reset
+ echo 1 > /sys/block/zram1/reset
This frees all the memory allocated for the given device and
resets the disksize to zero. You must set the disksize again
before reusing the device.
-* Optional Feature
+Optional Feature
+================
-= writeback
+writeback
+---------
With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
to backing storage rather than keeping it in memory.
-To use the feature, admin should set up backing device via
+To use the feature, admin should set up backing device via::
- "echo /dev/sda5 > /sys/block/zramX/backing_dev"
+ echo /dev/sda5 > /sys/block/zramX/backing_dev
before disksize setting. It supports only partition at this moment.
-If admin want to use incompressible page writeback, they could do via
+If admin want to use incompressible page writeback, they could do via::
- "echo huge > /sys/block/zramX/write"
+ echo huge > /sys/block/zramX/write
To use idle page writeback, first, user need to declare zram pages
-as idle.
+as idle::
- "echo all > /sys/block/zramX/idle"
+ echo all > /sys/block/zramX/idle
From now on, any pages on zram are idle pages. The idle mark
will be removed until someone request access of the block.
IOW, unless there is access request, those pages are still idle pages.
-Admin can request writeback of those idle pages at right timing via
+Admin can request writeback of those idle pages at right timing via::
- "echo idle > /sys/block/zramX/writeback"
+ echo idle > /sys/block/zramX/writeback
With the command, zram writeback idle pages from memory to the storage.
@@ -285,7 +342,7 @@ to guarantee storage health for entire product life.
To overcome the concern, zram supports "writeback_limit" feature.
The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
any writeback. IOW, if admin want to apply writeback budget, he should
-enable writeback_limit_enable via
+enable writeback_limit_enable via::
$ echo 1 > /sys/block/zramX/writeback_limit_enable
@@ -296,7 +353,7 @@ until admin set the budget via /sys/block/zramX/writeback_limit.
assigned via /sys/block/zramX/writeback_limit is meaninless.)
If admin want to limit writeback as per-day 400M, he could do it
-like below.
+like below::
$ MB_SHIFT=20
$ 4K_SHIFT=12
@@ -305,16 +362,16 @@ like below.
$ echo 1 > /sys/block/zram0/writeback_limit_enable
If admin want to allow further write again once the bugdet is exausted,
-he could do it like below
+he could do it like below::
$ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
/sys/block/zram0/writeback_limit
-If admin want to see remaining writeback budget since he set,
+If admin want to see remaining writeback budget since he set::
$ cat /sys/block/zramX/writeback_limit
-If admin want to disable writeback limit, he could do
+If admin want to disable writeback limit, he could do::
$ echo 0 > /sys/block/zramX/writeback_limit_enable
@@ -326,25 +383,35 @@ budget in next setting is user's job.
If admin want to measure writeback count in a certain period, he could
know it via /sys/block/zram0/bd_stat's 3rd column.
-= memory tracking
+memory tracking
+===============
With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
zram block. It could be useful to catch cold or incompressible
pages of the process with*pagemap.
+
If you enable the feature, you could see block state via
-/sys/kernel/debug/zram/zram0/block_state". The output is as follows,
+/sys/kernel/debug/zram/zram0/block_state". The output is as follows::
300 75.033841 .wh.
301 63.806904 s...
302 63.806919 ..hi
-First column is zram's block index.
-Second column is access time since the system was booted
-Third column is state of the block.
-(s: same page
-w: written page to backing store
-h: huge page
-i: idle page)
+First column
+ zram's block index.
+Second column
+ access time since the system was booted
+Third column
+ state of the block:
+
+ s:
+ same page
+ w:
+ written page to backing store
+ h:
+ huge page
+ i:
+ idle page
First line of above example says 300th block is accessed at 75.033841sec
and the block's state is huge so it is written back to the backing
diff --git a/MAINTAINERS b/MAINTAINERS
index 85648a944446..808f65e06ad8 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11024,7 +11024,7 @@ M: Josef Bacik <josef@toxicpanda.com>
S: Maintained
L: linux-block@vger.kernel.org
L: nbd@other.debian.org
-F: Documentation/blockdev/nbd.txt
+F: Documentation/blockdev/nbd.rst
F: drivers/block/nbd.c
F: include/trace/events/nbd.h
F: include/uapi/linux/nbd.h
@@ -12028,7 +12028,7 @@ PARIDE DRIVERS FOR PARALLEL PORT IDE DEVICES
M: Tim Waugh <tim@cyberelk.net>
L: linux-parport@lists.infradead.org (subscribers-only)
S: Maintained
-F: Documentation/blockdev/paride.txt
+F: Documentation/blockdev/paride.rst
F: drivers/block/paride/
PARISC ARCHITECTURE
@@ -13310,7 +13310,7 @@ F: drivers/net/wireless/ralink/rt2x00/
RAMDISK RAM BLOCK DEVICE DRIVER
M: Jens Axboe <axboe@kernel.dk>
S: Maintained
-F: Documentation/blockdev/ramdisk.txt
+F: Documentation/blockdev/ramdisk.rst
F: drivers/block/brd.c
RANCHU VIRTUAL BOARD FOR MIPS
@@ -17672,7 +17672,7 @@ R: Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>
L: linux-kernel@vger.kernel.org
S: Maintained
F: drivers/block/zram/
-F: Documentation/blockdev/zram.txt
+F: Documentation/blockdev/zram.rst
ZS DECSTATION Z85C30 SERIAL DRIVER
M: "Maciej W. Rozycki" <macro@linux-mips.org>
diff --git a/drivers/block/Kconfig b/drivers/block/Kconfig
index 96ec7e0fc1ea..c43690b973d8 100644
--- a/drivers/block/Kconfig
+++ b/drivers/block/Kconfig
@@ -31,7 +31,7 @@ config BLK_DEV_FD
If you want to use the floppy disk drive(s) of your PC under Linux,
say Y. Information about this driver, especially important for IBM
Thinkpad users, is contained in
- <file:Documentation/blockdev/floppy.txt>.
+ <file:Documentation/blockdev/floppy.rst>.
That file also contains the location of the Floppy driver FAQ as
well as location of the fdutils package used to configure additional
parameters of the driver at run time.
@@ -96,7 +96,7 @@ config PARIDE
your computer's parallel port. Most of them are actually IDE devices
using a parallel port IDE adapter. This option enables the PARIDE
subsystem which contains drivers for many of these external drives.
- Read <file:Documentation/blockdev/paride.txt> for more information.
+ Read <file:Documentation/blockdev/paride.rst> for more information.
If you have said Y to the "Parallel-port support" configuration
option, you may share a single port between your printer and other
@@ -261,7 +261,7 @@ config BLK_DEV_NBD
userland (making server and client physically the same computer,
communicating using the loopback network device).
- Read <file:Documentation/blockdev/nbd.txt> for more information,
+ Read <file:Documentation/blockdev/nbd.rst> for more information,
especially about where to find the server code, which runs in user
space and does not need special kernel support.
@@ -303,7 +303,7 @@ config BLK_DEV_RAM
during the initial install of Linux.
Note that the kernel command line option "ramdisk=XX" is now obsolete.
- For details, read <file:Documentation/blockdev/ramdisk.txt>.
+ For details, read <file:Documentation/blockdev/ramdisk.rst>.
To compile this driver as a module, choose M here: the
module will be called brd. An alias "rd" has been defined
diff --git a/drivers/block/floppy.c b/drivers/block/floppy.c
index b933a7eea52b..5c99e52f9dc1 100644
--- a/drivers/block/floppy.c
+++ b/drivers/block/floppy.c
@@ -4424,7 +4424,7 @@ static int __init floppy_setup(char *str)
pr_cont("\n");
} else
DPRINT("botched floppy option\n");
- DPRINT("Read Documentation/blockdev/floppy.txt\n");
+ DPRINT("Read Documentation/blockdev/floppy.rst\n");
return 0;
}
diff --git a/drivers/block/zram/Kconfig b/drivers/block/zram/Kconfig
index 1ffc64770643..e06b99d54816 100644
--- a/drivers/block/zram/Kconfig
+++ b/drivers/block/zram/Kconfig
@@ -12,7 +12,7 @@ config ZRAM
It has several use cases, for example: /tmp storage, use as swap
disks and maybe many more.
- See Documentation/blockdev/zram.txt for more information.
+ See Documentation/blockdev/zram.rst for more information.
config ZRAM_WRITEBACK
bool "Write back incompressible or idle page to backing device"
@@ -26,7 +26,7 @@ config ZRAM_WRITEBACK
With /sys/block/zramX/{idle,writeback}, application could ask
idle page's writeback to the backing device to save in memory.
- See Documentation/blockdev/zram.txt for more information.
+ See Documentation/blockdev/zram.rst for more information.
config ZRAM_MEMORY_TRACKING
bool "Track zRam block status"
@@ -36,4 +36,4 @@ config ZRAM_MEMORY_TRACKING
of zRAM. Admin could see the information via
/sys/kernel/debug/zram/zramX/block_state.
- See Documentation/blockdev/zram.txt for more information.
+ See Documentation/blockdev/zram.rst for more information.
diff --git a/tools/testing/selftests/zram/README b/tools/testing/selftests/zram/README
index 7972cc512408..5fa378391d3b 100644
--- a/tools/testing/selftests/zram/README
+++ b/tools/testing/selftests/zram/README
@@ -37,4 +37,4 @@ Commands required for testing:
- mkfs/ mkfs.ext4
For more information please refer:
-kernel-source-tree/Documentation/blockdev/zram.txt
+kernel-source-tree/Documentation/blockdev/zram.rst
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 38/43] docs: perf: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (35 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 37/43] docs: blockdev: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 39/43] docs: sysctl: " Mauro Carvalho Chehab
` (5 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Andy Gross, Will Deacon, Mark Rutland,
linux-arm-msm, linux-arm-kernel
Rename the perf 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>
---
.../perf/{arm-ccn.txt => arm-ccn.rst} | 18 +++++-----
.../perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} | 5 +--
.../perf/{hisi-pmu.txt => hisi-pmu.rst} | 35 +++++++++++--------
Documentation/perf/index.rst | 16 +++++++++
.../perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} | 3 +-
.../perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} | 3 +-
.../{thunderx2-pmu.txt => thunderx2-pmu.rst} | 25 ++++++-------
.../perf/{xgene-pmu.txt => xgene-pmu.rst} | 3 +-
MAINTAINERS | 4 +--
drivers/perf/qcom_l3_pmu.c | 2 +-
10 files changed, 72 insertions(+), 42 deletions(-)
rename Documentation/perf/{arm-ccn.txt => arm-ccn.rst} (86%)
rename Documentation/perf/{arm_dsu_pmu.txt => arm_dsu_pmu.rst} (92%)
rename Documentation/perf/{hisi-pmu.txt => hisi-pmu.rst} (73%)
create mode 100644 Documentation/perf/index.rst
rename Documentation/perf/{qcom_l2_pmu.txt => qcom_l2_pmu.rst} (94%)
rename Documentation/perf/{qcom_l3_pmu.txt => qcom_l3_pmu.rst} (93%)
rename Documentation/perf/{thunderx2-pmu.txt => thunderx2-pmu.rst} (73%)
rename Documentation/perf/{xgene-pmu.txt => xgene-pmu.rst} (96%)
diff --git a/Documentation/perf/arm-ccn.txt b/Documentation/perf/arm-ccn.rst
similarity index 86%
rename from Documentation/perf/arm-ccn.txt
rename to Documentation/perf/arm-ccn.rst
index 15cdb7bc57c3..832b0c64023a 100644
--- a/Documentation/perf/arm-ccn.txt
+++ b/Documentation/perf/arm-ccn.rst
@@ -1,3 +1,4 @@
+==========================
ARM Cache Coherent Network
==========================
@@ -29,6 +30,7 @@ Crosspoint watchpoint-based events (special "event" value 0xfe)
require "xp" and "vc" as as above plus "port" (device port index),
"dir" (transmit/receive direction), comparator values ("cmp_l"
and "cmp_h") and "mask", being index of the comparator mask.
+
Masks are defined separately from the event description
(due to limited number of the config values) in the "cmp_mask"
directory, with first 8 configurable by user and additional
@@ -44,16 +46,16 @@ request the events on this processor (if not, the perf_event->cpu value
will be overwritten anyway). In case of this processor being offlined,
the events are migrated to another one and the attribute is updated.
-Example of perf tool use:
+Example of perf tool use::
-/ # perf list | grep ccn
- ccn/cycles/ [Kernel PMU event]
-<...>
- ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event]
-<...>
+ / # perf list | grep ccn
+ ccn/cycles/ [Kernel PMU event]
+ <...>
+ ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event]
+ <...>
-/ # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \
- sleep 1
+ / # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \
+ sleep 1
The driver does not support sampling, therefore "perf record" will
not work. Per-task (without "-a") perf sessions are not supported.
diff --git a/Documentation/perf/arm_dsu_pmu.txt b/Documentation/perf/arm_dsu_pmu.rst
similarity index 92%
rename from Documentation/perf/arm_dsu_pmu.txt
rename to Documentation/perf/arm_dsu_pmu.rst
index d611e15f5add..7fd34db75d13 100644
--- a/Documentation/perf/arm_dsu_pmu.txt
+++ b/Documentation/perf/arm_dsu_pmu.rst
@@ -1,3 +1,4 @@
+==================================
ARM DynamIQ Shared Unit (DSU) PMU
==================================
@@ -13,7 +14,7 @@ PMU doesn't support process specific events and cannot be used in sampling mode.
The DSU provides a bitmap for a subset of implemented events via hardware
registers. There is no way for the driver to determine if the other events
are available or not. Hence the driver exposes only those events advertised
-by the DSU, in "events" directory under :
+by the DSU, in "events" directory under::
/sys/bus/event_sources/devices/arm_dsu_<N>/
@@ -23,6 +24,6 @@ and use the raw event code for the unlisted events.
The driver also exposes the CPUs connected to the DSU instance in "associated_cpus".
-e.g usage :
+e.g usage::
perf stat -a -e arm_dsu_0/cycles/
diff --git a/Documentation/perf/hisi-pmu.txt b/Documentation/perf/hisi-pmu.rst
similarity index 73%
rename from Documentation/perf/hisi-pmu.txt
rename to Documentation/perf/hisi-pmu.rst
index 267a028b2741..404a5c3d9d00 100644
--- a/Documentation/perf/hisi-pmu.txt
+++ b/Documentation/perf/hisi-pmu.rst
@@ -1,5 +1,7 @@
+======================================================
HiSilicon SoC uncore Performance Monitoring Unit (PMU)
======================================================
+
The HiSilicon SoC chip includes various independent system device PMUs
such as L3 cache (L3C), Hydra Home Agent (HHA) and DDRC. These PMUs are
independent and have hardware logic to gather statistics and performance
@@ -11,11 +13,13 @@ called Super CPU cluster (SCCL) and is made up of 6 CCLs. Each SCCL has
two HHAs (0 - 1) and four DDRCs (0 - 3), respectively.
HiSilicon SoC uncore PMU driver
----------------------------------------
+-------------------------------
+
Each device PMU has separate registers for event counting, control and
interrupt, and the PMU driver shall register perf PMU drivers like L3C,
HHA and DDRC etc. The available events and configuration options shall
-be described in the sysfs, see :
+be described in the sysfs, see:
+
/sys/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>/, or
/sys/bus/event_source/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>.
The "perf list" command shall list the available events from sysfs.
@@ -24,27 +28,30 @@ Each L3C, HHA and DDRC is registered as a separate PMU with perf. The PMU
name will appear in event listing as hisi_sccl<sccl-id>_module<index-id>.
where "sccl-id" is the identifier of the SCCL and "index-id" is the index of
module.
+
e.g. hisi_sccl3_l3c0/rd_hit_cpipe is READ_HIT_CPIPE event of L3C index #0 in
SCCL ID #3.
+
e.g. hisi_sccl1_hha0/rx_operations is RX_OPERATIONS event of HHA index #0 in
SCCL ID #1.
The driver also provides a "cpumask" sysfs attribute, which shows the CPU core
ID used to count the uncore PMU event.
-Example usage of perf:
-$# perf list
-hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event]
-------------------------------------------
-hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event]
-------------------------------------------
-hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event]
-------------------------------------------
-hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event]
-------------------------------------------
+Example usage of perf::
-$# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5
-$# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5
+ $# perf list
+ hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+ hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+ hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+ hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event]
+ ------------------------------------------
+
+ $# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5
+ $# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5
The current driver does not support sampling. So "perf record" is unsupported.
Also attach to a task is unsupported as the events are all uncore.
diff --git a/Documentation/perf/index.rst b/Documentation/perf/index.rst
new file mode 100644
index 000000000000..4bf848e27f26
--- /dev/null
+++ b/Documentation/perf/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+===========================
+Performance monitor support
+===========================
+
+.. toctree::
+ :maxdepth: 1
+
+ hisi-pmu
+ qcom_l2_pmu
+ qcom_l3_pmu
+ arm-ccn
+ xgene-pmu
+ arm_dsu_pmu
+ thunderx2-pmu
diff --git a/Documentation/perf/qcom_l2_pmu.txt b/Documentation/perf/qcom_l2_pmu.rst
similarity index 94%
rename from Documentation/perf/qcom_l2_pmu.txt
rename to Documentation/perf/qcom_l2_pmu.rst
index b25b97659ab9..c130178a4a55 100644
--- a/Documentation/perf/qcom_l2_pmu.txt
+++ b/Documentation/perf/qcom_l2_pmu.rst
@@ -1,3 +1,4 @@
+=====================================================================
Qualcomm Technologies Level-2 Cache Performance Monitoring Unit (PMU)
=====================================================================
@@ -28,7 +29,7 @@ The driver provides a "cpumask" sysfs attribute which contains a mask
consisting of one CPU per cluster which will be used to handle all the PMU
events on that cluster.
-Examples for use with perf:
+Examples for use with perf::
perf stat -e l2cache_0/config=0x001/,l2cache_0/config=0x042/ -a sleep 1
diff --git a/Documentation/perf/qcom_l3_pmu.txt b/Documentation/perf/qcom_l3_pmu.rst
similarity index 93%
rename from Documentation/perf/qcom_l3_pmu.txt
rename to Documentation/perf/qcom_l3_pmu.rst
index 96b3a9444a0d..a3d014a46bfd 100644
--- a/Documentation/perf/qcom_l3_pmu.txt
+++ b/Documentation/perf/qcom_l3_pmu.rst
@@ -1,3 +1,4 @@
+===========================================================================
Qualcomm Datacenter Technologies L3 Cache Performance Monitoring Unit (PMU)
===========================================================================
@@ -17,7 +18,7 @@ The hardware implements 32bit event counters and has a flat 8bit event space
exposed via the "event" format attribute. In addition to the 32bit physical
counters the driver supports virtual 64bit hardware counters by using hardware
counter chaining. This feature is exposed via the "lc" (long counter) format
-flag. E.g.:
+flag. E.g.::
perf stat -e l3cache_0_0/read-miss,lc/
diff --git a/Documentation/perf/thunderx2-pmu.txt b/Documentation/perf/thunderx2-pmu.rst
similarity index 73%
rename from Documentation/perf/thunderx2-pmu.txt
rename to Documentation/perf/thunderx2-pmu.rst
index dffc57143736..08e33675853a 100644
--- a/Documentation/perf/thunderx2-pmu.txt
+++ b/Documentation/perf/thunderx2-pmu.rst
@@ -1,3 +1,4 @@
+=============================================================
Cavium ThunderX2 SoC Performance Monitoring Unit (PMU UNCORE)
=============================================================
@@ -24,18 +25,18 @@ and configuration options under sysfs, see
The driver does not support sampling, therefore "perf record" will not
work. Per-task perf sessions are also not supported.
-Examples:
+Examples::
-# perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1
+ # perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1
-# perf stat -a -e \
-uncore_dmc_0/cnt_cycles/,\
-uncore_dmc_0/data_transfers/,\
-uncore_dmc_0/read_txns/,\
-uncore_dmc_0/write_txns/ sleep 1
+ # perf stat -a -e \
+ uncore_dmc_0/cnt_cycles/,\
+ uncore_dmc_0/data_transfers/,\
+ uncore_dmc_0/read_txns/,\
+ uncore_dmc_0/write_txns/ sleep 1
-# perf stat -a -e \
-uncore_l3c_0/read_request/,\
-uncore_l3c_0/read_hit/,\
-uncore_l3c_0/inv_request/,\
-uncore_l3c_0/inv_hit/ sleep 1
+ # perf stat -a -e \
+ uncore_l3c_0/read_request/,\
+ uncore_l3c_0/read_hit/,\
+ uncore_l3c_0/inv_request/,\
+ uncore_l3c_0/inv_hit/ sleep 1
diff --git a/Documentation/perf/xgene-pmu.txt b/Documentation/perf/xgene-pmu.rst
similarity index 96%
rename from Documentation/perf/xgene-pmu.txt
rename to Documentation/perf/xgene-pmu.rst
index d7cff4454e5b..644f8ed89152 100644
--- a/Documentation/perf/xgene-pmu.txt
+++ b/Documentation/perf/xgene-pmu.rst
@@ -1,3 +1,4 @@
+================================================
APM X-Gene SoC Performance Monitoring Unit (PMU)
================================================
@@ -33,7 +34,7 @@ each PMU, please refer to APM X-Gene User Manual.
Each perf driver also provides a "cpumask" sysfs attribute, which contains a
single CPU ID of the processor which will be used to handle all the PMU events.
-Example for perf tool use:
+Example for perf tool use::
/ # perf list | grep -e l3c -e iob -e mcb -e mc
l3c0/ackq-full/ [Kernel PMU event]
diff --git a/MAINTAINERS b/MAINTAINERS
index 808f65e06ad8..f5a2121294b3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1139,7 +1139,7 @@ APPLIED MICRO (APM) X-GENE SOC PMU
M: Khuong Dinh <khuong@os.amperecomputing.com>
S: Supported
F: drivers/perf/xgene_pmu.c
-F: Documentation/perf/xgene-pmu.txt
+F: Documentation/perf/xgene-pmu.rst
F: Documentation/devicetree/bindings/perf/apm-xgene-pmu.txt
APTINA CAMERA SENSOR PLL
@@ -7207,7 +7207,7 @@ M: Shaokun Zhang <zhangshaokun@hisilicon.com>
W: http://www.hisilicon.com
S: Supported
F: drivers/perf/hisilicon
-F: Documentation/perf/hisi-pmu.txt
+F: Documentation/perf/hisi-pmu.rst
HISILICON ROCE DRIVER
M: Lijun Ou <oulijun@huawei.com>
diff --git a/drivers/perf/qcom_l3_pmu.c b/drivers/perf/qcom_l3_pmu.c
index 15b8c10c2b2b..90f88ce5192b 100644
--- a/drivers/perf/qcom_l3_pmu.c
+++ b/drivers/perf/qcom_l3_pmu.c
@@ -8,7 +8,7 @@
* the slices. User space needs to aggregate to individual counts to provide
* a global picture.
*
- * See Documentation/perf/qcom_l3_pmu.txt for more details.
+ * See Documentation/perf/qcom_l3_pmu.rst for more details.
*
* Copyright (c) 2015-2017, The Linux Foundation. All rights reserved.
*/
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 39/43] docs: sysctl: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (36 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 38/43] docs: perf: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 40/43] docs: block: " Mauro Carvalho Chehab
` (4 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David S. Miller, netdev, linux-mm
Rename the /proc/sys/ documentation files to ReST, using the
README file as a template for an index.rst, adding the other
files there via TOC markup.
Despite being written on different times with different
styles, try to make them somewhat coherent with a similar
look and feel, ensuring that they'll look nice as both
raw text file and as via the html output produced by 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>
---
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/admin-guide/mm/index.rst | 2 +-
Documentation/admin-guide/mm/ksm.rst | 2 +-
Documentation/core-api/printk-formats.rst | 2 +-
Documentation/networking/ip-sysctl.txt | 2 +-
Documentation/sysctl/abi.rst | 67 ++++
Documentation/sysctl/abi.txt | 54 ---
Documentation/sysctl/{fs.txt => fs.rst} | 142 +++----
Documentation/sysctl/{README => index.rst} | 36 +-
.../sysctl/{kernel.txt => kernel.rst} | 372 ++++++++++--------
Documentation/sysctl/{net.txt => net.rst} | 141 ++++---
.../sysctl/{sunrpc.txt => sunrpc.rst} | 13 +-
Documentation/sysctl/{user.txt => user.rst} | 32 +-
Documentation/sysctl/{vm.txt => vm.rst} | 258 ++++++------
Documentation/vm/unevictable-lru.rst | 2 +-
kernel/panic.c | 2 +-
mm/swap.c | 2 +-
17 files changed, 650 insertions(+), 481 deletions(-)
create mode 100644 Documentation/sysctl/abi.rst
delete mode 100644 Documentation/sysctl/abi.txt
rename Documentation/sysctl/{fs.txt => fs.rst} (77%)
rename Documentation/sysctl/{README => index.rst} (78%)
rename Documentation/sysctl/{kernel.txt => kernel.rst} (79%)
rename Documentation/sysctl/{net.txt => net.rst} (85%)
rename Documentation/sysctl/{sunrpc.txt => sunrpc.rst} (62%)
rename Documentation/sysctl/{user.txt => user.rst} (77%)
rename Documentation/sysctl/{vm.txt => vm.rst} (85%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 7ed94527a4a0..61abadd70a86 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3170,7 +3170,7 @@
numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA.
'node', 'default' can be specified
This can be set from sysctl after boot.
- See Documentation/sysctl/vm.txt for details.
+ See Documentation/sysctl/vm.rst for details.
ohci1394_dma=early [HW] enable debugging via the ohci1394 driver.
See Documentation/debugging-via-ohci1394.txt for more
diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst
index ddf8d8d33377..f5e92f33f96e 100644
--- a/Documentation/admin-guide/mm/index.rst
+++ b/Documentation/admin-guide/mm/index.rst
@@ -11,7 +11,7 @@ processes address space and many other cool things.
Linux memory management is a complex system with many configurable
settings. Most of these settings are available via ``/proc``
filesystem and can be quired and adjusted using ``sysctl``. These APIs
-are described in Documentation/sysctl/vm.txt and in `man 5 proc`_.
+are described in Documentation/sysctl/vm.rst and in `man 5 proc`_.
.. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html
diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst
index 9303786632d1..7b2b8767c0b4 100644
--- a/Documentation/admin-guide/mm/ksm.rst
+++ b/Documentation/admin-guide/mm/ksm.rst
@@ -59,7 +59,7 @@ MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE.
If a region of memory must be split into at least one new MADV_MERGEABLE
or MADV_UNMERGEABLE region, the madvise may return ENOMEM if the process
-will exceed ``vm.max_map_count`` (see Documentation/sysctl/vm.txt).
+will exceed ``vm.max_map_count`` (see Documentation/sysctl/vm.rst).
Like other madvise calls, they are intended for use on mapped areas of
the user address space: they will report ENOMEM if the specified range
diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index 75d2bbe9813f..1d8e748f909f 100644
--- a/Documentation/core-api/printk-formats.rst
+++ b/Documentation/core-api/printk-formats.rst
@@ -119,7 +119,7 @@ Kernel Pointers
For printing kernel pointers which should be hidden from unprivileged
users. The behaviour of %pK depends on the kptr_restrict sysctl - see
-Documentation/sysctl/kernel.txt for more details.
+Documentation/sysctl/kernel.rst for more details.
Unmodified Addresses
--------------------
diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt
index e0d8a96e2c67..0f8e1c544e1e 100644
--- a/Documentation/networking/ip-sysctl.txt
+++ b/Documentation/networking/ip-sysctl.txt
@@ -2284,7 +2284,7 @@ addr_scope_policy - INTEGER
/proc/sys/net/core/*
- Please see: Documentation/sysctl/net.txt for descriptions of these entries.
+ Please see: Documentation/sysctl/net.rst for descriptions of these entries.
/proc/sys/net/unix/*
diff --git a/Documentation/sysctl/abi.rst b/Documentation/sysctl/abi.rst
new file mode 100644
index 000000000000..599bcde7f0b7
--- /dev/null
+++ b/Documentation/sysctl/abi.rst
@@ -0,0 +1,67 @@
+================================
+Documentation for /proc/sys/abi/
+================================
+
+kernel version 2.6.0.test2
+
+Copyright (c) 2003, Fabian Frederick <ffrederick@users.sourceforge.net>
+
+For general info: index.rst.
+
+------------------------------------------------------------------------------
+
+This path is binary emulation relevant aka personality types aka abi.
+When a process is executed, it's linked to an exec_domain whose
+personality is defined using values available from /proc/sys/abi.
+You can find further details about abi in include/linux/personality.h.
+
+Here are the files featuring in 2.6 kernel:
+
+- defhandler_coff
+- defhandler_elf
+- defhandler_lcall7
+- defhandler_libcso
+- fake_utsname
+- trace
+
+defhandler_coff
+---------------
+
+defined value:
+ PER_SCOSVR3::
+
+ 0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS | SHORT_INODE
+
+defhandler_elf
+--------------
+
+defined value:
+ PER_LINUX::
+
+ 0
+
+defhandler_lcall7
+-----------------
+
+defined value :
+ PER_SVR4::
+
+ 0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+
+defhandler_libsco
+-----------------
+
+defined value:
+ PER_SVR4::
+
+ 0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+
+fake_utsname
+------------
+
+Unused
+
+trace
+-----
+
+Unused
diff --git a/Documentation/sysctl/abi.txt b/Documentation/sysctl/abi.txt
deleted file mode 100644
index 63f4ebcf652c..000000000000
--- a/Documentation/sysctl/abi.txt
+++ /dev/null
@@ -1,54 +0,0 @@
-Documentation for /proc/sys/abi/* kernel version 2.6.0.test2
- (c) 2003, Fabian Frederick <ffrederick@users.sourceforge.net>
-
-For general info : README.
-
-==============================================================
-
-This path is binary emulation relevant aka personality types aka abi.
-When a process is executed, it's linked to an exec_domain whose
-personality is defined using values available from /proc/sys/abi.
-You can find further details about abi in include/linux/personality.h.
-
-Here are the files featuring in 2.6 kernel :
-
-- defhandler_coff
-- defhandler_elf
-- defhandler_lcall7
-- defhandler_libcso
-- fake_utsname
-- trace
-
-===========================================================
-defhandler_coff:
-defined value :
-PER_SCOSVR3
-0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS | SHORT_INODE
-
-===========================================================
-defhandler_elf:
-defined value :
-PER_LINUX
-0
-
-===========================================================
-defhandler_lcall7:
-defined value :
-PER_SVR4
-0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
-
-===========================================================
-defhandler_libsco:
-defined value:
-PER_SVR4
-0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
-
-===========================================================
-fake_utsname:
-Unused
-
-===========================================================
-trace:
-Unused
-
-===========================================================
diff --git a/Documentation/sysctl/fs.txt b/Documentation/sysctl/fs.rst
similarity index 77%
rename from Documentation/sysctl/fs.txt
rename to Documentation/sysctl/fs.rst
index ebc679bcb2dc..2a45119e3331 100644
--- a/Documentation/sysctl/fs.txt
+++ b/Documentation/sysctl/fs.rst
@@ -1,10 +1,16 @@
-Documentation for /proc/sys/fs/* kernel version 2.2.10
- (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
- (c) 2009, Shen Feng<shen@cn.fujitsu.com>
+===============================
+Documentation for /proc/sys/fs/
+===============================
-For general info and legal blurb, please look in README.
+kernel version 2.2.10
-==============================================================
+Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
+
+Copyright (c) 2009, Shen Feng<shen@cn.fujitsu.com>
+
+For general info and legal blurb, please look in intro.rst.
+
+------------------------------------------------------------------------------
This file contains documentation for the sysctl files in
/proc/sys/fs/ and is valid for Linux kernel version 2.2.
@@ -16,9 +22,10 @@ system, it is advisable to read both documentation and source
before actually making adjustments.
1. /proc/sys/fs
-----------------------------------------------------------
+===============
Currently, these files are in /proc/sys/fs:
+
- aio-max-nr
- aio-nr
- dentry-state
@@ -42,9 +49,9 @@ Currently, these files are in /proc/sys/fs:
- super-max
- super-nr
-==============================================================
-aio-nr & aio-max-nr:
+aio-nr & aio-max-nr
+-------------------
aio-nr is the running total of the number of events specified on the
io_setup system call for all currently active aio contexts. If aio-nr
@@ -52,21 +59,20 @@ reaches aio-max-nr then io_setup will fail with EAGAIN. Note that
raising aio-max-nr does not result in the pre-allocation or re-sizing
of any kernel data structures.
-==============================================================
-dentry-state:
+dentry-state
+------------
-From linux/include/linux/dcache.h:
---------------------------------------------------------------
-struct dentry_stat_t dentry_stat {
+From linux/include/linux/dcache.h::
+
+ struct dentry_stat_t dentry_stat {
int nr_dentry;
int nr_unused;
int age_limit; /* age in seconds */
int want_pages; /* pages requested by system */
int nr_negative; /* # of unused negative dentries */
int dummy; /* Reserved for future use */
-};
---------------------------------------------------------------
+ };
Dentries are dynamically allocated and deallocated.
@@ -84,9 +90,9 @@ negative dentries which do not map to any files. Instead,
they help speeding up rejection of non-existing files provided
by the users.
-==============================================================
-dquot-max & dquot-nr:
+dquot-max & dquot-nr
+--------------------
The file dquot-max shows the maximum number of cached disk
quota entries.
@@ -98,9 +104,9 @@ If the number of free cached disk quotas is very low and
you have some awesome number of simultaneous system users,
you might want to raise the limit.
-==============================================================
-file-max & file-nr:
+file-max & file-nr
+------------------
The value in file-max denotes the maximum number of file-
handles that the Linux kernel will allocate. When you get lots
@@ -119,18 +125,19 @@ used file handles.
Attempts to allocate more file descriptors than file-max are
reported with printk, look for "VFS: file-max limit <number>
reached".
-==============================================================
-nr_open:
+
+nr_open
+-------
This denotes the maximum number of file-handles a process can
allocate. Default value is 1024*1024 (1048576) which should be
enough for most machines. Actual limit depends on RLIMIT_NOFILE
resource limit.
-==============================================================
-inode-max, inode-nr & inode-state:
+inode-max, inode-nr & inode-state
+---------------------------------
As with file handles, the kernel allocates the inode structures
dynamically, but can't free them yet.
@@ -157,9 +164,9 @@ preshrink is nonzero when the nr_inodes > inode-max and the
system needs to prune the inode list instead of allocating
more.
-==============================================================
-overflowgid & overflowuid:
+overflowgid & overflowuid
+-------------------------
Some filesystems only support 16-bit UIDs and GIDs, although in Linux
UIDs and GIDs are 32 bits. When one of these filesystems is mounted
@@ -169,18 +176,18 @@ to a fixed value before being written to disk.
These sysctls allow you to change the value of the fixed UID and GID.
The default is 65534.
-==============================================================
-pipe-user-pages-hard:
+pipe-user-pages-hard
+--------------------
Maximum total number of pages a non-privileged user may allocate for pipes.
Once this limit is reached, no new pipes may be allocated until usage goes
below the limit again. When set to 0, no limit is applied, which is the default
setting.
-==============================================================
-pipe-user-pages-soft:
+pipe-user-pages-soft
+--------------------
Maximum total number of pages a non-privileged user may allocate for pipes
before the pipe size gets limited to a single page. Once this limit is reached,
@@ -190,9 +197,9 @@ denied until usage goes below the limit again. The default value allows to
allocate up to 1024 pipes at their default size. When set to 0, no limit is
applied.
-==============================================================
-protected_fifos:
+protected_fifos
+---------------
The intent of this protection is to avoid unintentional writes to
an attacker-controlled FIFO, where a program expected to create a regular
@@ -208,9 +215,9 @@ When set to "2" it also applies to group writable sticky directories.
This protection is based on the restrictions in Openwall.
-==============================================================
-protected_hardlinks:
+protected_hardlinks
+--------------------
A long-standing class of security issues is the hardlink-based
time-of-check-time-of-use race, most commonly seen in world-writable
@@ -228,9 +235,9 @@ already own the source file, or do not have read/write access to it.
This protection is based on the restrictions in Openwall and grsecurity.
-==============================================================
-protected_regular:
+protected_regular
+-----------------
This protection is similar to protected_fifos, but it
avoids writes to an attacker-controlled regular file, where a program
@@ -244,9 +251,9 @@ owned by the owner of the directory.
When set to "2" it also applies to group writable sticky directories.
-==============================================================
-protected_symlinks:
+protected_symlinks
+------------------
A long-standing class of security issues is the symlink-based
time-of-check-time-of-use race, most commonly seen in world-writable
@@ -264,34 +271,38 @@ follower match, or when the directory owner matches the symlink's owner.
This protection is based on the restrictions in Openwall and grsecurity.
-==============================================================
suid_dumpable:
+--------------
This value can be used to query and set the core dump mode for setuid
or otherwise protected/tainted binaries. The modes are
-0 - (default) - traditional behaviour. Any process which has changed
- privilege levels or is execute only will not be dumped.
-1 - (debug) - all processes dump core when possible. The core dump is
- owned by the current user and no security is applied. This is
- intended for system debugging situations only. Ptrace is unchecked.
- This is insecure as it allows regular users to examine the memory
- contents of privileged processes.
-2 - (suidsafe) - any binary which normally would not be dumped is dumped
- anyway, but only if the "core_pattern" kernel sysctl is set to
- either a pipe handler or a fully qualified path. (For more details
- on this limitation, see CVE-2006-2451.) This mode is appropriate
- when administrators are attempting to debug problems in a normal
- environment, and either have a core dump pipe handler that knows
- to treat privileged core dumps with care, or specific directory
- defined for catching core dumps. If a core dump happens without
- a pipe handler or fully qualifid path, a message will be emitted
- to syslog warning about the lack of a correct setting.
+= ========== ===============================================================
+0 (default) traditional behaviour. Any process which has changed
+ privilege levels or is execute only will not be dumped.
+1 (debug) all processes dump core when possible. The core dump is
+ owned by the current user and no security is applied. This is
+ intended for system debugging situations only.
+ Ptrace is unchecked.
+ This is insecure as it allows regular users to examine the
+ memory contents of privileged processes.
+2 (suidsafe) any binary which normally would not be dumped is dumped
+ anyway, but only if the "core_pattern" kernel sysctl is set to
+ either a pipe handler or a fully qualified path. (For more
+ details on this limitation, see CVE-2006-2451.) This mode is
+ appropriate when administrators are attempting to debug
+ problems in a normal environment, and either have a core dump
+ pipe handler that knows to treat privileged core dumps with
+ care, or specific directory defined for catching core dumps.
+ If a core dump happens without a pipe handler or fully
+ qualified path, a message will be emitted to syslog warning
+ about the lack of a correct setting.
+= ========== ===============================================================
-==============================================================
-super-max & super-nr:
+super-max & super-nr
+--------------------
These numbers control the maximum number of superblocks, and
thus the maximum number of mounted filesystems the kernel
@@ -299,33 +310,33 @@ can have. You only need to increase super-max if you need to
mount more filesystems than the current value in super-max
allows you to.
-==============================================================
-aio-nr & aio-max-nr:
+aio-nr & aio-max-nr
+-------------------
aio-nr shows the current system-wide number of asynchronous io
requests. aio-max-nr allows you to change the maximum value
aio-nr can grow to.
-==============================================================
-mount-max:
+mount-max
+---------
This denotes the maximum number of mounts that may exist
in a mount namespace.
-==============================================================
2. /proc/sys/fs/binfmt_misc
-----------------------------------------------------------
+===========================
Documentation for the files in /proc/sys/fs/binfmt_misc is
in Documentation/admin-guide/binfmt-misc.rst.
3. /proc/sys/fs/mqueue - POSIX message queues filesystem
-----------------------------------------------------------
+========================================================
+
The "mqueue" filesystem provides the necessary kernel features to enable the
creation of a user space library that implements the POSIX message queues
@@ -356,7 +367,7 @@ the default message size value if attr parameter of mq_open(2) is NULL. If it
exceed msgsize_max, the default value is initialized msgsize_max.
4. /proc/sys/fs/epoll - Configuration options for the epoll interface
---------------------------------------------------------
+=====================================================================
This directory contains configuration options for the epoll(7) interface.
@@ -371,4 +382,3 @@ Each "watch" costs roughly 90 bytes on a 32bit kernel, and roughly 160 bytes
on a 64bit one.
The current default value for max_user_watches is the 1/32 of the available
low memory, divided for the "watch" cost in bytes.
-
diff --git a/Documentation/sysctl/README b/Documentation/sysctl/index.rst
similarity index 78%
rename from Documentation/sysctl/README
rename to Documentation/sysctl/index.rst
index d5f24ab0ecc3..efbcde8c1c9c 100644
--- a/Documentation/sysctl/README
+++ b/Documentation/sysctl/index.rst
@@ -1,5 +1,12 @@
-Documentation for /proc/sys/ kernel version 2.2.10
- (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
+:orphan:
+
+===========================
+Documentation for /proc/sys
+===========================
+
+Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
+
+------------------------------------------------------------------------------
'Why', I hear you ask, 'would anyone even _want_ documentation
for them sysctl files? If anybody really needs it, it's all in
@@ -12,11 +19,12 @@ have the time or knowledge to read the source code.
Furthermore, the programmers who built sysctl have built it to
be actually used, not just for the fun of programming it :-)
-==============================================================
+------------------------------------------------------------------------------
Legal blurb:
As usual, there are two main things to consider:
+
1. you get what you pay for
2. it's free
@@ -35,15 +43,17 @@ stories to: <riel@nl.linux.org>
Rik van Riel.
-==============================================================
+--------------------------------------------------------------
-Introduction:
+Introduction
+============
Sysctl is a means of configuring certain aspects of the kernel
at run-time, and the /proc/sys/ directory is there so that you
don't even need special tools to do it!
In fact, there are only four things needed to use these config
facilities:
+
- a running Linux system
- root access
- common sense (this is especially hard to come by these days)
@@ -54,7 +64,9 @@ several (arch-dependent?) subdirs. Each subdir is mainly about
one part of the kernel, so you can do configuration on a piece
by piece basis, or just some 'thematic frobbing'.
-The subdirs are about:
+This documentation is about:
+
+=============== ===============================================================
abi/ execution domains & personalities
debug/ <empty>
dev/ device specific information (eg dev/cdrom/info)
@@ -70,7 +82,19 @@ sunrpc/ SUN Remote Procedure Call (NFS)
vm/ memory management tuning
buffer and cache management
user/ Per user per user namespace limits
+=============== ===============================================================
These are the subdirs I have on my system. There might be more
or other subdirs in another setup. If you see another dir, I'd
really like to hear about it :-)
+
+.. toctree::
+ :maxdepth: 1
+
+ abi
+ fs
+ kernel
+ net
+ sunrpc
+ user
+ vm
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.rst
similarity index 79%
rename from Documentation/sysctl/kernel.txt
rename to Documentation/sysctl/kernel.rst
index 1b2fe17cd2fa..a0c1d4ce403a 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.rst
@@ -1,10 +1,16 @@
-Documentation for /proc/sys/kernel/* kernel version 2.2.10
- (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
- (c) 2009, Shen Feng<shen@cn.fujitsu.com>
+===================================
+Documentation for /proc/sys/kernel/
+===================================
-For general info and legal blurb, please look in README.
+kernel version 2.2.10
-==============================================================
+Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
+
+Copyright (c) 2009, Shen Feng<shen@cn.fujitsu.com>
+
+For general info and legal blurb, please look in index.rst.
+
+------------------------------------------------------------------------------
This file contains documentation for the sysctl files in
/proc/sys/kernel/ and is valid for Linux kernel version 2.2.
@@ -101,9 +107,9 @@ show up in /proc/sys/kernel:
- watchdog_thresh
- version
-==============================================================
acct:
+=====
highwater lowwater frequency
@@ -118,18 +124,18 @@ That is, suspend accounting if there left <= 2% free; resume it
if we got >=4%; consider information about amount of free space
valid for 30 seconds.
-==============================================================
acpi_video_flags:
+=================
flags
See Doc*/kernel/power/video.txt, it allows mode of video boot to be
set during run time.
-==============================================================
auto_msgmni:
+============
This variable has no effect and may be removed in future kernel
releases. Reading it always returns 0.
@@ -139,9 +145,8 @@ Echoing "1" into this file enabled msgmni automatic recomputing.
Echoing "0" turned it off. auto_msgmni default value was 1.
-==============================================================
-
bootloader_type:
+================
x86 bootloader identification
@@ -156,9 +161,9 @@ the value 340 = 0x154.
See the type_of_loader and ext_loader_type fields in
Documentation/x86/boot.rst for additional information.
-==============================================================
bootloader_version:
+===================
x86 bootloader version
@@ -168,27 +173,31 @@ file will contain the value 564 = 0x234.
See the type_of_loader and ext_loader_ver fields in
Documentation/x86/boot.rst for additional information.
-==============================================================
-cap_last_cap
+cap_last_cap:
+=============
Highest valid capability of the running kernel. Exports
CAP_LAST_CAP from the kernel.
-==============================================================
core_pattern:
+=============
core_pattern is used to specify a core dumpfile pattern name.
-. max length 127 characters; default value is "core"
-. core_pattern is used as a pattern template for the output filename;
+
+* max length 127 characters; default value is "core"
+* core_pattern is used as a pattern template for the output filename;
certain string patterns (beginning with '%') are substituted with
their actual values.
-. backward compatibility with core_uses_pid:
+* backward compatibility with core_uses_pid:
+
If core_pattern does not include "%p" (default does not)
and core_uses_pid is set, then .PID will be appended to
the filename.
-. corename format specifiers:
+
+* corename format specifiers::
+
%<NUL> '%' is dropped
%% output one '%'
%p pid
@@ -205,13 +214,14 @@ core_pattern is used to specify a core dumpfile pattern name.
%e executable filename (may be shortened)
%E executable path
%<OTHER> both are dropped
-. If the first character of the pattern is a '|', the kernel will treat
+
+* If the first character of the pattern is a '|', the kernel will treat
the rest of the pattern as a command to run. The core dump will be
written to the standard input of that program instead of to a file.
-==============================================================
core_pipe_limit:
+================
This sysctl is only applicable when core_pattern is configured to pipe
core files to a user space helper (when the first character of
@@ -232,9 +242,9 @@ parallel, but that no waiting will take place (i.e. the collecting
process is not guaranteed access to /proc/<crashing pid>/). This
value defaults to 0.
-==============================================================
core_uses_pid:
+==============
The default coredump filename is "core". By setting
core_uses_pid to 1, the coredump filename becomes core.PID.
@@ -242,9 +252,9 @@ If core_pattern does not include "%p" (default does not)
and core_uses_pid is set, then .PID will be appended to
the filename.
-==============================================================
ctrl-alt-del:
+=============
When the value in this file is 0, ctrl-alt-del is trapped and
sent to the init(1) program to handle a graceful restart.
@@ -252,14 +262,15 @@ When, however, the value is > 0, Linux's reaction to a Vulcan
Nerve Pinch (tm) will be an immediate reboot, without even
syncing its dirty buffers.
-Note: when a program (like dosemu) has the keyboard in 'raw'
-mode, the ctrl-alt-del is intercepted by the program before it
-ever reaches the kernel tty layer, and it's up to the program
-to decide what to do with it.
+Note:
+ when a program (like dosemu) has the keyboard in 'raw'
+ mode, the ctrl-alt-del is intercepted by the program before it
+ ever reaches the kernel tty layer, and it's up to the program
+ to decide what to do with it.
-==============================================================
dmesg_restrict:
+===============
This toggle indicates whether unprivileged users are prevented
from using dmesg(8) to view messages from the kernel's log buffer.
@@ -270,18 +281,21 @@ dmesg(8).
The kernel config option CONFIG_SECURITY_DMESG_RESTRICT sets the
default value of dmesg_restrict.
-==============================================================
domainname & hostname:
+======================
These files can be used to set the NIS/YP domainname and the
hostname of your box in exactly the same way as the commands
-domainname and hostname, i.e.:
-# echo "darkstar" > /proc/sys/kernel/hostname
-# echo "mydomain" > /proc/sys/kernel/domainname
-has the same effect as
-# hostname "darkstar"
-# domainname "mydomain"
+domainname and hostname, i.e.::
+
+ # echo "darkstar" > /proc/sys/kernel/hostname
+ # echo "mydomain" > /proc/sys/kernel/domainname
+
+has the same effect as::
+
+ # hostname "darkstar"
+ # domainname "mydomain"
Note, however, that the classic darkstar.frop.org has the
hostname "darkstar" and DNS (Internet Domain Name Server)
@@ -290,8 +304,9 @@ Information Service) or YP (Yellow Pages) domainname. These two
domain names are in general different. For a detailed discussion
see the hostname(1) man page.
-==============================================================
+
hardlockup_all_cpu_backtrace:
+=============================
This value controls the hard lockup detector behavior when a hard
lockup condition is detected as to whether or not to gather further
@@ -301,9 +316,10 @@ will be initiated.
0: do nothing. This is the default behavior.
1: on detection capture more debug information.
-==============================================================
+
hardlockup_panic:
+=================
This parameter can be used to control whether the kernel panics
when a hard lockup is detected.
@@ -314,16 +330,16 @@ when a hard lockup is detected.
See Documentation/lockup-watchdogs.txt for more information. This can
also be set using the nmi_watchdog kernel parameter.
-==============================================================
hotplug:
+========
Path for the hotplug policy agent.
Default value is "/sbin/hotplug".
-==============================================================
hung_task_panic:
+================
Controls the kernel's behavior when a hung task is detected.
This file shows up if CONFIG_DETECT_HUNG_TASK is enabled.
@@ -332,27 +348,28 @@ This file shows up if CONFIG_DETECT_HUNG_TASK is enabled.
1: panic immediately.
-==============================================================
hung_task_check_count:
+======================
The upper bound on the number of tasks that are checked.
This file shows up if CONFIG_DETECT_HUNG_TASK is enabled.
-==============================================================
hung_task_timeout_secs:
+=======================
When a task in D state did not get scheduled
for more than this value report a warning.
This file shows up if CONFIG_DETECT_HUNG_TASK is enabled.
0: means infinite timeout - no checking done.
+
Possible values to set are in range {0..LONG_MAX/HZ}.
-==============================================================
hung_task_check_interval_secs:
+==============================
Hung task check interval. If hung task checking is enabled
(see hung_task_timeout_secs), the check is done every
@@ -362,9 +379,9 @@ This file shows up if CONFIG_DETECT_HUNG_TASK is enabled.
0 (default): means use hung_task_timeout_secs as checking interval.
Possible values to set are in range {0..LONG_MAX/HZ}.
-==============================================================
hung_task_warnings:
+===================
The maximum number of warnings to report. During a check interval
if a hung task is detected, this value is decreased by 1.
@@ -373,9 +390,9 @@ This file shows up if CONFIG_DETECT_HUNG_TASK is enabled.
-1: report an infinite number of warnings.
-==============================================================
hyperv_record_panic_msg:
+========================
Controls whether the panic kmsg data should be reported to Hyper-V.
@@ -383,9 +400,9 @@ Controls whether the panic kmsg data should be reported to Hyper-V.
1: report the panic kmsg data. This is the default behavior.
-==============================================================
kexec_load_disabled:
+====================
A toggle indicating if the kexec_load syscall has been disabled. This
value defaults to 0 (false: kexec_load enabled), but can be set to 1
@@ -395,9 +412,9 @@ loaded before disabling the syscall, allowing a system to set up (and
later use) an image without it being altered. Generally used together
with the "modules_disabled" sysctl.
-==============================================================
kptr_restrict:
+==============
This toggle indicates whether restrictions are placed on
exposing kernel addresses via /proc and other interfaces.
@@ -420,16 +437,16 @@ values to unprivileged users is a concern.
When kptr_restrict is set to (2), kernel pointers printed using
%pK will be replaced with 0's regardless of privileges.
-==============================================================
l2cr: (PPC only)
+================
This flag controls the L2 cache of G3 processor boards. If
0, the cache is disabled. Enabled if nonzero.
-==============================================================
modules_disabled:
+=================
A toggle value indicating if modules are allowed to be loaded
in an otherwise modular kernel. This toggle defaults to off
@@ -437,9 +454,9 @@ in an otherwise modular kernel. This toggle defaults to off
neither loaded nor unloaded, and the toggle cannot be set back
to false. Generally used with the "kexec_load_disabled" toggle.
-==============================================================
msg_next_id, sem_next_id, and shm_next_id:
+==========================================
These three toggles allows to specify desired id for next allocated IPC
object: message, semaphore or shared memory respectively.
@@ -448,21 +465,22 @@ By default they are equal to -1, which means generic allocation logic.
Possible values to set are in range {0..INT_MAX}.
Notes:
-1) kernel doesn't guarantee, that new object will have desired id. So,
-it's up to userspace, how to handle an object with "wrong" id.
-2) Toggle with non-default value will be set back to -1 by kernel after
-successful IPC object allocation. If an IPC object allocation syscall
-fails, it is undefined if the value remains unmodified or is reset to -1.
+ 1) kernel doesn't guarantee, that new object will have desired id. So,
+ it's up to userspace, how to handle an object with "wrong" id.
+ 2) Toggle with non-default value will be set back to -1 by kernel after
+ successful IPC object allocation. If an IPC object allocation syscall
+ fails, it is undefined if the value remains unmodified or is reset to -1.
-==============================================================
nmi_watchdog:
+=============
This parameter can be used to control the NMI watchdog
(i.e. the hard lockup detector) on x86 systems.
- 0 - disable the hard lockup detector
- 1 - enable the hard lockup detector
+0 - disable the hard lockup detector
+
+1 - enable the hard lockup detector
The hard lockup detector monitors each CPU for its ability to respond to
timer interrupts. The mechanism utilizes CPU performance counter registers
@@ -470,15 +488,15 @@ that are programmed to generate Non-Maskable Interrupts (NMIs) periodically
while a CPU is busy. Hence, the alternative name 'NMI watchdog'.
The NMI watchdog is disabled by default if the kernel is running as a guest
-in a KVM virtual machine. This default can be overridden by adding
+in a KVM virtual machine. This default can be overridden by adding::
nmi_watchdog=1
to the guest kernel command line (see Documentation/admin-guide/kernel-parameters.rst).
-==============================================================
-numa_balancing
+numa_balancing:
+===============
Enables/disables automatic page fault based NUMA memory
balancing. Memory is moved automatically to nodes
@@ -500,10 +518,9 @@ faults may be controlled by the numa_balancing_scan_period_min_ms,
numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms,
numa_balancing_scan_size_mb, and numa_balancing_settle_count sysctls.
-==============================================================
+numa_balancing_scan_period_min_ms, numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms, numa_balancing_scan_size_mb
+===============================================================================================================================
-numa_balancing_scan_period_min_ms, numa_balancing_scan_delay_ms,
-numa_balancing_scan_period_max_ms, numa_balancing_scan_size_mb
Automatic NUMA balancing scans tasks address space and unmaps pages to
detect if pages are properly placed or if the data should be migrated to a
@@ -539,16 +556,18 @@ rate for each task.
numa_balancing_scan_size_mb is how many megabytes worth of pages are
scanned for a given scan.
-==============================================================
osrelease, ostype & version:
+============================
-# cat osrelease
-2.1.88
-# cat ostype
-Linux
-# cat version
-#5 Wed Feb 25 21:49:24 MET 1998
+::
+
+ # cat osrelease
+ 2.1.88
+ # cat ostype
+ Linux
+ # cat version
+ #5 Wed Feb 25 21:49:24 MET 1998
The files osrelease and ostype should be clear enough. Version
needs a little more clarification however. The '#5' means that
@@ -556,9 +575,9 @@ this is the fifth kernel built from this source base and the
date behind it indicates the time the kernel was built.
The only way to tune these values is to rebuild the kernel :-)
-==============================================================
overflowgid & overflowuid:
+==========================
if your architecture did not always support 32-bit UIDs (i.e. arm,
i386, m68k, sh, and sparc32), a fixed UID and GID will be returned to
@@ -568,17 +587,17 @@ actual UID or GID would exceed 65535.
These sysctls allow you to change the value of the fixed UID and GID.
The default is 65534.
-==============================================================
panic:
+======
The value in this file represents the number of seconds the kernel
waits before rebooting on a panic. When you use the software watchdog,
the recommended setting is 60.
-==============================================================
panic_on_io_nmi:
+================
Controls the kernel's behavior when a CPU receives an NMI caused by
an IO error.
@@ -591,20 +610,20 @@ an IO error.
servers issue this sort of NMI when the dump button is pushed,
and you can use this option to take a crash dump.
-==============================================================
panic_on_oops:
+==============
Controls the kernel's behaviour when an oops or BUG is encountered.
0: try to continue operation
-1: panic immediately. If the `panic' sysctl is also non-zero then the
+1: panic immediately. If the `panic` sysctl is also non-zero then the
machine will be rebooted.
-==============================================================
panic_on_stackoverflow:
+=======================
Controls the kernel's behavior when detecting the overflows of
kernel, IRQ and exception stacks except a user stack.
@@ -614,9 +633,9 @@ This file shows up if CONFIG_DEBUG_STACKOVERFLOW is enabled.
1: panic immediately.
-==============================================================
panic_on_unrecovered_nmi:
+=========================
The default Linux behaviour on an NMI of either memory or unknown is
to continue operation. For many environments such as scientific
@@ -627,9 +646,9 @@ A small number of systems do generate NMI's for bizarre random reasons
such as power management so the default is off. That sysctl works like
the existing panic controls already in that directory.
-==============================================================
panic_on_warn:
+==============
Calls panic() in the WARN() path when set to 1. This is useful to avoid
a kernel rebuild when attempting to kdump at the location of a WARN().
@@ -638,25 +657,28 @@ a kernel rebuild when attempting to kdump at the location of a WARN().
1: call panic() after printing out WARN() location.
-==============================================================
panic_print:
+============
Bitmask for printing system info when panic happens. User can chose
combination of the following bits:
-bit 0: print all tasks info
-bit 1: print system memory info
-bit 2: print timer info
-bit 3: print locks info if CONFIG_LOCKDEP is on
-bit 4: print ftrace buffer
+===== ========================================
+bit 0 print all tasks info
+bit 1 print system memory info
+bit 2 print timer info
+bit 3 print locks info if CONFIG_LOCKDEP is on
+bit 4 print ftrace buffer
+===== ========================================
+
+So for example to print tasks and memory info on panic, user can::
-So for example to print tasks and memory info on panic, user can:
echo 3 > /proc/sys/kernel/panic_print
-==============================================================
panic_on_rcu_stall:
+===================
When set to 1, calls panic() after RCU stall detection messages. This
is useful to define the root cause of RCU stalls using a vmcore.
@@ -665,9 +687,9 @@ is useful to define the root cause of RCU stalls using a vmcore.
1: panic() after printing RCU stall messages.
-==============================================================
perf_cpu_time_max_percent:
+==========================
Hints to the kernel how much CPU time it should be allowed to
use to handle perf sampling events. If the perf subsystem
@@ -680,10 +702,12 @@ unexpectedly take too long to execute, the NMIs can become
stacked up next to each other so much that nothing else is
allowed to execute.
-0: disable the mechanism. Do not monitor or correct perf's
+0:
+ disable the mechanism. Do not monitor or correct perf's
sampling rate no matter how CPU time it takes.
-1-100: attempt to throttle perf's sample rate to this
+1-100:
+ attempt to throttle perf's sample rate to this
percentage of CPU. Note: the kernel calculates an
"expected" length of each sample event. 100 here means
100% of that expected length. Even if this is set to
@@ -691,23 +715,30 @@ allowed to execute.
length is exceeded. Set to 0 if you truly do not care
how much CPU is consumed.
-==============================================================
perf_event_paranoid:
+====================
Controls use of the performance events system by unprivileged
users (without CAP_SYS_ADMIN). The default value is 2.
- -1: Allow use of (almost) all events by all users
+=== ==================================================================
+ -1 Allow use of (almost) all events by all users
+
Ignore mlock limit after perf_event_mlock_kb without CAP_IPC_LOCK
->=0: Disallow ftrace function tracepoint by users without CAP_SYS_ADMIN
+
+>=0 Disallow ftrace function tracepoint by users without CAP_SYS_ADMIN
+
Disallow raw tracepoint access by users without CAP_SYS_ADMIN
->=1: Disallow CPU event access by users without CAP_SYS_ADMIN
->=2: Disallow kernel profiling by users without CAP_SYS_ADMIN
-==============================================================
+>=1 Disallow CPU event access by users without CAP_SYS_ADMIN
+
+>=2 Disallow kernel profiling by users without CAP_SYS_ADMIN
+=== ==================================================================
+
perf_event_max_stack:
+=====================
Controls maximum number of stack frames to copy for (attr.sample_type &
PERF_SAMPLE_CALLCHAIN) configured events, for instance, when using
@@ -718,17 +749,17 @@ enabled, otherwise writing to this file will return -EBUSY.
The default value is 127.
-==============================================================
perf_event_mlock_kb:
+====================
Control size of per-cpu ring buffer not counted agains mlock limit.
The default value is 512 + 1 page
-==============================================================
perf_event_max_contexts_per_stack:
+==================================
Controls maximum number of stack frame context entries for
(attr.sample_type & PERF_SAMPLE_CALLCHAIN) configured events, for
@@ -739,25 +770,25 @@ enabled, otherwise writing to this file will return -EBUSY.
The default value is 8.
-==============================================================
pid_max:
+========
PID allocation wrap value. When the kernel's next PID value
reaches this value, it wraps back to a minimum PID value.
PIDs of value pid_max or larger are not allocated.
-==============================================================
ns_last_pid:
+============
The last pid allocated in the current (the one task using this sysctl
lives in) pid namespace. When selecting a pid for a next task on fork
kernel tries to allocate a number starting from this one.
-==============================================================
powersave-nap: (PPC only)
+=========================
If set, Linux-PPC will use the 'nap' mode of powersaving,
otherwise the 'doze' mode will be used.
@@ -765,6 +796,7 @@ otherwise the 'doze' mode will be used.
==============================================================
printk:
+=======
The four values in printk denote: console_loglevel,
default_message_loglevel, minimum_console_loglevel and
@@ -774,25 +806,29 @@ These values influence printk() behavior when printing or
logging error messages. See 'man 2 syslog' for more info on
the different loglevels.
-- console_loglevel: messages with a higher priority than
- this will be printed to the console
-- default_message_loglevel: messages without an explicit priority
- will be printed with this priority
-- minimum_console_loglevel: minimum (highest) value to which
- console_loglevel can be set
-- default_console_loglevel: default value for console_loglevel
+- console_loglevel:
+ messages with a higher priority than
+ this will be printed to the console
+- default_message_loglevel:
+ messages without an explicit priority
+ will be printed with this priority
+- minimum_console_loglevel:
+ minimum (highest) value to which
+ console_loglevel can be set
+- default_console_loglevel:
+ default value for console_loglevel
-==============================================================
printk_delay:
+=============
Delay each printk message in printk_delay milliseconds
Value from 0 - 10000 is allowed.
-==============================================================
printk_ratelimit:
+=================
Some warning messages are rate limited. printk_ratelimit specifies
the minimum length of time between these messages (in jiffies), by
@@ -800,48 +836,52 @@ default we allow one every 5 seconds.
A value of 0 will disable rate limiting.
-==============================================================
printk_ratelimit_burst:
+=======================
While long term we enforce one message per printk_ratelimit
seconds, we do allow a burst of messages to pass through.
printk_ratelimit_burst specifies the number of messages we can
send before ratelimiting kicks in.
-==============================================================
printk_devkmsg:
+===============
Control the logging to /dev/kmsg from userspace:
-ratelimit: default, ratelimited
+ratelimit:
+ default, ratelimited
+
on: unlimited logging to /dev/kmsg from userspace
+
off: logging to /dev/kmsg disabled
The kernel command line parameter printk.devkmsg= overrides this and is
a one-time setting until next reboot: once set, it cannot be changed by
this sysctl interface anymore.
-==============================================================
randomize_va_space:
+===================
This option can be used to select the type of process address
space randomization that is used in the system, for architectures
that support this feature.
-0 - Turn the process address space randomization off. This is the
+== ===========================================================================
+0 Turn the process address space randomization off. This is the
default for architectures that do not support this feature anyways,
and kernels that are booted with the "norandmaps" parameter.
-1 - Make the addresses of mmap base, stack and VDSO page randomized.
+1 Make the addresses of mmap base, stack and VDSO page randomized.
This, among other things, implies that shared libraries will be
loaded to random addresses. Also for PIE-linked binaries, the
location of code start is randomized. This is the default if the
CONFIG_COMPAT_BRK option is enabled.
-2 - Additionally enable heap randomization. This is the default if
+2 Additionally enable heap randomization. This is the default if
CONFIG_COMPAT_BRK is disabled.
There are a few legacy applications out there (such as some ancient
@@ -854,18 +894,19 @@ that support this feature.
Systems with ancient and/or broken binaries should be configured
with CONFIG_COMPAT_BRK enabled, which excludes the heap from process
address space randomization.
+== ===========================================================================
-==============================================================
reboot-cmd: (Sparc only)
+========================
??? This seems to be a way to give an argument to the Sparc
ROM/Flash boot loader. Maybe to tell it what to do after
rebooting. ???
-==============================================================
rtsig-max & rtsig-nr:
+=====================
The file rtsig-max can be used to tune the maximum number
of POSIX realtime (queued) signals that can be outstanding
@@ -873,9 +914,9 @@ in the system.
rtsig-nr shows the number of RT signals currently queued.
-==============================================================
sched_energy_aware:
+===================
Enables/disables Energy Aware Scheduling (EAS). EAS starts
automatically on platforms where it can run (that is,
@@ -884,17 +925,17 @@ Model available). If your platform happens to meet the
requirements for EAS but you do not want to use it, change
this value to 0.
-==============================================================
sched_schedstats:
+=================
Enables/disables scheduler statistics. Enabling this feature
incurs a small amount of overhead in the scheduler but is
useful for debugging and performance tuning.
-==============================================================
sg-big-buff:
+============
This file shows the size of the generic SCSI (sg) buffer.
You can't tune it just yet, but you could change it on
@@ -905,9 +946,9 @@ There shouldn't be any reason to change this value. If
you can come up with one, you probably know what you
are doing anyway :)
-==============================================================
shmall:
+=======
This parameter sets the total amount of shared memory pages that
can be used system wide. Hence, SHMALL should always be at least
@@ -916,20 +957,20 @@ ceil(shmmax/PAGE_SIZE).
If you are not sure what the default PAGE_SIZE is on your Linux
system, you can run the following command:
-# getconf PAGE_SIZE
+ # getconf PAGE_SIZE
-==============================================================
shmmax:
+=======
This value can be used to query and set the run time limit
on the maximum shared memory segment size that can be created.
Shared memory segments up to 1Gb are now supported in the
kernel. This value defaults to SHMMAX.
-==============================================================
shm_rmid_forced:
+================
Linux lets you set resource limits, including how much memory one
process can consume, via setrlimit(2). Unfortunately, shared memory
@@ -948,28 +989,30 @@ need this.
Note that if you change this from 0 to 1, already created segments
without users and with a dead originative process will be destroyed.
-==============================================================
sysctl_writes_strict:
+=====================
Control how file position affects the behavior of updating sysctl values
via the /proc/sys interface:
- -1 - Legacy per-write sysctl value handling, with no printk warnings.
+ == ======================================================================
+ -1 Legacy per-write sysctl value handling, with no printk warnings.
Each write syscall must fully contain the sysctl value to be
written, and multiple writes on the same sysctl file descriptor
will rewrite the sysctl value, regardless of file position.
- 0 - Same behavior as above, but warn about processes that perform writes
+ 0 Same behavior as above, but warn about processes that perform writes
to a sysctl file descriptor when the file position is not 0.
- 1 - (default) Respect file position when writing sysctl strings. Multiple
+ 1 (default) Respect file position when writing sysctl strings. Multiple
writes will append to the sysctl value buffer. Anything past the max
length of the sysctl value buffer will be ignored. Writes to numeric
sysctl entries must always be at file position 0 and the value must
be fully contained in the buffer sent in the write syscall.
+ == ======================================================================
-==============================================================
softlockup_all_cpu_backtrace:
+=============================
This value controls the soft lockup detector thread's behavior
when a soft lockup condition is detected as to whether or not
@@ -983,13 +1026,14 @@ NMI.
1: on detection capture more debug information.
-==============================================================
-soft_watchdog
+soft_watchdog:
+==============
This parameter can be used to control the soft lockup detector.
0 - disable the soft lockup detector
+
1 - enable the soft lockup detector
The soft lockup detector monitors CPUs for threads that are hogging the CPUs
@@ -999,9 +1043,9 @@ interrupts which are needed for the 'watchdog/N' threads to be woken up by
the watchdog timer function, otherwise the NMI watchdog - if enabled - can
detect a hard lockup condition.
-==============================================================
-stack_erasing
+stack_erasing:
+==============
This parameter can be used to control kernel stack erasing at the end
of syscalls for kernels built with CONFIG_GCC_PLUGIN_STACKLEAK.
@@ -1015,37 +1059,40 @@ compilation sees a 1% slowdown, other systems and workloads may vary.
1: kernel stack erasing is enabled (default), it is performed before
returning to the userspace at the end of syscalls.
-==============================================================
+
tainted
+=======
Non-zero if the kernel has been tainted. Numeric values, which can be
ORed together. The letters are seen in "Tainted" line of Oops reports.
- 1 (P): proprietary module was loaded
- 2 (F): module was force loaded
- 4 (S): SMP kernel oops on an officially SMP incapable processor
- 8 (R): module was force unloaded
- 16 (M): processor reported a Machine Check Exception (MCE)
- 32 (B): bad page referenced or some unexpected page flags
- 64 (U): taint requested by userspace application
- 128 (D): kernel died recently, i.e. there was an OOPS or BUG
- 256 (A): an ACPI table was overridden by user
- 512 (W): kernel issued warning
- 1024 (C): staging driver was loaded
- 2048 (I): workaround for bug in platform firmware applied
- 4096 (O): externally-built ("out-of-tree") module was loaded
- 8192 (E): unsigned module was loaded
- 16384 (L): soft lockup occurred
- 32768 (K): kernel has been live patched
- 65536 (X): Auxiliary taint, defined and used by for distros
-131072 (T): The kernel was built with the struct randomization plugin
+====== ===== ==============================================================
+ 1 `(P)` proprietary module was loaded
+ 2 `(F)` module was force loaded
+ 4 `(S)` SMP kernel oops on an officially SMP incapable processor
+ 8 `(R)` module was force unloaded
+ 16 `(M)` processor reported a Machine Check Exception (MCE)
+ 32 `(B)` bad page referenced or some unexpected page flags
+ 64 `(U)` taint requested by userspace application
+ 128 `(D)` kernel died recently, i.e. there was an OOPS or BUG
+ 256 `(A)` an ACPI table was overridden by user
+ 512 `(W)` kernel issued warning
+ 1024 `(C)` staging driver was loaded
+ 2048 `(I)` workaround for bug in platform firmware applied
+ 4096 `(O)` externally-built ("out-of-tree") module was loaded
+ 8192 `(E)` unsigned module was loaded
+ 16384 `(L)` soft lockup occurred
+ 32768 `(K)` kernel has been live patched
+ 65536 `(X)` Auxiliary taint, defined and used by for distros
+131072 `(T)` The kernel was built with the struct randomization plugin
+====== ===== ==============================================================
See Documentation/admin-guide/tainted-kernels.rst for more information.
-==============================================================
-threads-max
+threads-max:
+============
This value controls the maximum number of threads that can be created
using fork().
@@ -1055,8 +1102,10 @@ maximum number of threads is created, the thread structures occupy only
a part (1/8th) of the available RAM pages.
The minimum value that can be written to threads-max is 20.
+
The maximum value that can be written to threads-max is given by the
constant FUTEX_TID_MASK (0x3fffffff).
+
If a value outside of this range is written to threads-max an error
EINVAL occurs.
@@ -1064,9 +1113,9 @@ The value written is checked against the available RAM pages. If the
thread structures would occupy too much (more than 1/8th) of the
available RAM pages threads-max is reduced accordingly.
-==============================================================
unknown_nmi_panic:
+==================
The value in this file affects behavior of handling NMI. When the
value is non-zero, unknown NMI is trapped and then panic occurs. At
@@ -1075,28 +1124,29 @@ that time, kernel debugging information is displayed on console.
NMI switch that most IA32 servers have fires unknown NMI up, for
example. If a system hangs up, try pressing the NMI switch.
-==============================================================
watchdog:
+=========
This parameter can be used to disable or enable the soft lockup detector
_and_ the NMI watchdog (i.e. the hard lockup detector) at the same time.
0 - disable both lockup detectors
+
1 - enable both lockup detectors
The soft lockup detector and the NMI watchdog can also be disabled or
enabled individually, using the soft_watchdog and nmi_watchdog parameters.
-If the watchdog parameter is read, for example by executing
+If the watchdog parameter is read, for example by executing::
cat /proc/sys/kernel/watchdog
the output of this command (0 or 1) shows the logical OR of soft_watchdog
and nmi_watchdog.
-==============================================================
watchdog_cpumask:
+=================
This value can be used to control on which cpus the watchdog may run.
The default cpumask is all possible cores, but if NO_HZ_FULL is
@@ -1111,13 +1161,13 @@ if a kernel lockup was suspected on those cores.
The argument value is the standard cpulist format for cpumasks,
so for example to enable the watchdog on cores 0, 2, 3, and 4 you
-might say:
+might say::
echo 0,2-4 > /proc/sys/kernel/watchdog_cpumask
-==============================================================
watchdog_thresh:
+================
This value can be used to control the frequency of hrtimer and NMI
events and the soft and hard lockup thresholds. The default threshold
@@ -1125,5 +1175,3 @@ is 10 seconds.
The softlockup threshold is (2 * watchdog_thresh). Setting this
tunable to zero will disable lockup detection altogether.
-
-==============================================================
diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.rst
similarity index 85%
rename from Documentation/sysctl/net.txt
rename to Documentation/sysctl/net.rst
index 2ae91d3873bb..a7d44e71019d 100644
--- a/Documentation/sysctl/net.txt
+++ b/Documentation/sysctl/net.rst
@@ -1,12 +1,25 @@
-Documentation for /proc/sys/net/*
- (c) 1999 Terrehon Bowden <terrehon@pacbell.net>
- Bodo Bauer <bb@ricochet.net>
- (c) 2000 Jorge Nerin <comandante@zaralinux.com>
- (c) 2009 Shen Feng <shen@cn.fujitsu.com>
+================================
+Documentation for /proc/sys/net/
+================================
-For general info and legal blurb, please look in README.
+Copyright
-==============================================================
+Copyright (c) 1999
+
+ - Terrehon Bowden <terrehon@pacbell.net>
+ - Bodo Bauer <bb@ricochet.net>
+
+Copyright (c) 2000
+
+ - Jorge Nerin <comandante@zaralinux.com>
+
+Copyright (c) 2009
+
+ - Shen Feng <shen@cn.fujitsu.com>
+
+For general info and legal blurb, please look in index.rst.
+
+------------------------------------------------------------------------------
This file contains the documentation for the sysctl files in
/proc/sys/net
@@ -17,20 +30,22 @@ see only some of them, depending on your kernel's configuration.
Table : Subdirectories in /proc/sys/net
-..............................................................................
- Directory Content Directory Content
- core General parameter appletalk Appletalk protocol
- unix Unix domain sockets netrom NET/ROM
- 802 E802 protocol ax25 AX25
- ethernet Ethernet protocol rose X.25 PLP layer
- ipv4 IP version 4 x25 X.25 protocol
- ipx IPX token-ring IBM token ring
- bridge Bridging decnet DEC net
- ipv6 IP version 6 tipc TIPC
-..............................................................................
+
+ ========= =================== = ========== ==================
+ Directory Content Directory Content
+ ========= =================== = ========== ==================
+ core General parameter appletalk Appletalk protocol
+ unix Unix domain sockets netrom NET/ROM
+ 802 E802 protocol ax25 AX25
+ ethernet Ethernet protocol rose X.25 PLP layer
+ ipv4 IP version 4 x25 X.25 protocol
+ ipx IPX token-ring IBM token ring
+ bridge Bridging decnet DEC net
+ ipv6 IP version 6 tipc TIPC
+ ========= =================== = ========== ==================
1. /proc/sys/net/core - Network core options
--------------------------------------------------------
+============================================
bpf_jit_enable
--------------
@@ -44,6 +59,7 @@ restricted C into a sequence of BPF instructions. After program load
through bpf(2) and passing a verifier in the kernel, a JIT will then
translate these BPF proglets into native CPU instructions. There are
two flavors of JITs, the newer eBPF JIT currently supported on:
+
- x86_64
- x86_32
- arm64
@@ -55,6 +71,7 @@ two flavors of JITs, the newer eBPF JIT currently supported on:
- riscv
And the older cBPF JIT supported on the following archs:
+
- mips
- ppc
- sparc
@@ -65,10 +82,11 @@ compile them transparently. Older cBPF JITs can only translate
tcpdump filters, seccomp rules, etc, but not mentioned eBPF
programs loaded through bpf(2).
-Values :
- 0 - disable the JIT (default value)
- 1 - enable the JIT
- 2 - enable the JIT and ask the compiler to emit traces on kernel log.
+Values:
+
+ - 0 - disable the JIT (default value)
+ - 1 - enable the JIT
+ - 2 - enable the JIT and ask the compiler to emit traces on kernel log.
bpf_jit_harden
--------------
@@ -76,10 +94,12 @@ bpf_jit_harden
This enables hardening for the BPF JIT compiler. Supported are eBPF
JIT backends. Enabling hardening trades off performance, but can
mitigate JIT spraying.
-Values :
- 0 - disable JIT hardening (default value)
- 1 - enable JIT hardening for unprivileged users only
- 2 - enable JIT hardening for all users
+
+Values:
+
+ - 0 - disable JIT hardening (default value)
+ - 1 - enable JIT hardening for unprivileged users only
+ - 2 - enable JIT hardening for all users
bpf_jit_kallsyms
----------------
@@ -89,9 +109,11 @@ addresses to the kernel, meaning they neither show up in traces nor
in /proc/kallsyms. This enables export of these addresses, which can
be used for debugging/tracing. If bpf_jit_harden is enabled, this
feature is disabled.
+
Values :
- 0 - disable JIT kallsyms export (default value)
- 1 - enable JIT kallsyms export for privileged users only
+
+ - 0 - disable JIT kallsyms export (default value)
+ - 1 - enable JIT kallsyms export for privileged users only
bpf_jit_limit
-------------
@@ -102,7 +124,7 @@ been surpassed. bpf_jit_limit contains the value of the global limit
in bytes.
dev_weight
---------------
+----------
The maximum number of packets that kernel can handle on a NAPI interrupt,
it's a Per-CPU variable. For drivers that support LRO or GRO_HW, a hardware
@@ -111,7 +133,7 @@ aggregated packet is counted as one packet in this context.
Default: 64
dev_weight_rx_bias
---------------
+------------------
RPS (e.g. RFS, aRFS) processing is competing with the registered NAPI poll function
of the driver for the per softirq cycle netdev_budget. This parameter influences
@@ -120,19 +142,22 @@ processing during RX softirq cycles. It is further meant for making current
dev_weight adaptable for asymmetric CPU needs on RX/TX side of the network stack.
(see dev_weight_tx_bias) It is effective on a per CPU basis. Determination is based
on dev_weight and is calculated multiplicative (dev_weight * dev_weight_rx_bias).
+
Default: 1
dev_weight_tx_bias
---------------
+------------------
Scales the maximum number of packets that can be processed during a TX softirq cycle.
Effective on a per CPU basis. Allows scaling of current dev_weight for asymmetric
net stack processing needs. Be careful to avoid making TX softirq processing a CPU hog.
+
Calculation is based on dev_weight (dev_weight * dev_weight_tx_bias).
+
Default: 1
default_qdisc
---------------
+-------------
The default queuing discipline to use for network devices. This allows
overriding the default of pfifo_fast with an alternative. Since the default
@@ -144,17 +169,21 @@ which require setting up classes and bandwidths. Note that physical multiqueue
interfaces still use mq as root qdisc, which in turn uses this default for its
leaves. Virtual devices (like e.g. lo or veth) ignore this setting and instead
default to noqueue.
+
Default: pfifo_fast
busy_read
-----------------
+---------
+
Low latency busy poll timeout for socket reads. (needs CONFIG_NET_RX_BUSY_POLL)
Approximate time in us to busy loop waiting for packets on the device queue.
This sets the default value of the SO_BUSY_POLL socket option.
Can be set or overridden per socket by setting socket option SO_BUSY_POLL,
which is the preferred method of enabling. If you need to enable the feature
globally via sysctl, a value of 50 is recommended.
+
Will increase power usage.
+
Default: 0 (off)
busy_poll
@@ -167,7 +196,9 @@ For more than that you probably want to use epoll.
Note that only sockets with SO_BUSY_POLL set will be busy polled,
so you want to either selectively set SO_BUSY_POLL on those sockets or set
sysctl.net.busy_read globally.
+
Will increase power usage.
+
Default: 0 (off)
rmem_default
@@ -185,6 +216,7 @@ tstamp_allow_data
Allow processes to receive tx timestamps looped together with the original
packet contents. If disabled, transmit timestamp requests from unprivileged
processes are dropped unless socket option SOF_TIMESTAMPING_OPT_TSONLY is set.
+
Default: 1 (on)
@@ -250,19 +282,24 @@ randomly generated.
Some user space might need to gather its content even if drivers do not
provide ethtool -x support yet.
-myhost:~# cat /proc/sys/net/core/netdev_rss_key
-84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8: ... (52 bytes total)
+::
+
+ myhost:~# cat /proc/sys/net/core/netdev_rss_key
+ 84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8: ... (52 bytes total)
File contains nul bytes if no driver ever called netdev_rss_key_fill() function.
+
Note:
-/proc/sys/net/core/netdev_rss_key contains 52 bytes of key,
-but most drivers only use 40 bytes of it.
+ /proc/sys/net/core/netdev_rss_key contains 52 bytes of key,
+ but most drivers only use 40 bytes of it.
-myhost:~# ethtool -x eth0
-RX flow hash indirection table for eth0 with 8 RX ring(s):
- 0: 0 1 2 3 4 5 6 7
-RSS hash key:
-84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89
+::
+
+ myhost:~# ethtool -x eth0
+ RX flow hash indirection table for eth0 with 8 RX ring(s):
+ 0: 0 1 2 3 4 5 6 7
+ RSS hash key:
+ 84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89
netdev_tstamp_prequeue
----------------------
@@ -293,7 +330,7 @@ user space is responsible for creating them if needed.
Default : 0 (for compatibility reasons)
devconf_inherit_init_net
-----------------------------
+------------------------
Controls if a new network namespace should inherit all current
settings under /proc/sys/net/{ipv4,ipv6}/conf/{all,default}/. By
@@ -307,7 +344,7 @@ forced to reset to their default values.
Default : 0 (for compatibility reasons)
2. /proc/sys/net/unix - Parameters for Unix domain sockets
--------------------------------------------------------
+----------------------------------------------------------
There is only one file in this directory.
unix_dgram_qlen limits the max number of datagrams queued in Unix domain
@@ -315,13 +352,13 @@ socket's buffer. It will not take effect unless PF_UNIX flag is specified.
3. /proc/sys/net/ipv4 - IPV4 settings
--------------------------------------------------------
+-------------------------------------
Please see: Documentation/networking/ip-sysctl.txt and ipvs-sysctl.txt for
descriptions of these entries.
4. Appletalk
--------------------------------------------------------
+------------
The /proc/sys/net/appletalk directory holds the Appletalk configuration data
when Appletalk is loaded. The configurable parameters are:
@@ -366,7 +403,7 @@ route flags, and the device the route is using.
5. IPX
--------------------------------------------------------
+------
The IPX protocol has no tunable values in proc/sys/net.
@@ -391,14 +428,16 @@ gives the destination network, the router node (or Directly) and the network
address of the router (or Connected) for internal networks.
6. TIPC
--------------------------------------------------------
+-------
tipc_rmem
-----------
+---------
The TIPC protocol now has a tunable for the receive memory, similar to the
tcp_rmem - i.e. a vector of 3 INTEGERs: (min, default, max)
+::
+
# cat /proc/sys/net/tipc/tipc_rmem
4252725 34021800 68043600
#
@@ -409,7 +448,7 @@ is not at this point in time used in any meaningful way, but the triplet is
preserved in order to be consistent with things like tcp_rmem.
named_timeout
---------------
+-------------
TIPC name table updates are distributed asynchronously in a cluster, without
any form of transaction handling. This means that different race scenarios are
diff --git a/Documentation/sysctl/sunrpc.txt b/Documentation/sysctl/sunrpc.rst
similarity index 62%
rename from Documentation/sysctl/sunrpc.txt
rename to Documentation/sysctl/sunrpc.rst
index ae1ecac6f85a..09780a682afd 100644
--- a/Documentation/sysctl/sunrpc.txt
+++ b/Documentation/sysctl/sunrpc.rst
@@ -1,9 +1,14 @@
-Documentation for /proc/sys/sunrpc/* kernel version 2.2.10
- (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
+===================================
+Documentation for /proc/sys/sunrpc/
+===================================
-For general info and legal blurb, please look in README.
+kernel version 2.2.10
-==============================================================
+Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
+
+For general info and legal blurb, please look in index.rst.
+
+------------------------------------------------------------------------------
This file contains the documentation for the sysctl files in
/proc/sys/sunrpc and is valid for Linux kernel version 2.2.
diff --git a/Documentation/sysctl/user.txt b/Documentation/sysctl/user.rst
similarity index 77%
rename from Documentation/sysctl/user.txt
rename to Documentation/sysctl/user.rst
index a5882865836e..650eaa03f15e 100644
--- a/Documentation/sysctl/user.txt
+++ b/Documentation/sysctl/user.rst
@@ -1,7 +1,12 @@
-Documentation for /proc/sys/user/* kernel version 4.9.0
- (c) 2016 Eric Biederman <ebiederm@xmission.com>
+=================================
+Documentation for /proc/sys/user/
+=================================
-==============================================================
+kernel version 4.9.0
+
+Copyright (c) 2016 Eric Biederman <ebiederm@xmission.com>
+
+------------------------------------------------------------------------------
This file contains the documentation for the sysctl files in
/proc/sys/user.
@@ -30,37 +35,44 @@ user namespace does not allow a user to escape their current limits.
Currently, these files are in /proc/sys/user:
-- max_cgroup_namespaces
+max_cgroup_namespaces
+=====================
The maximum number of cgroup namespaces that any user in the current
user namespace may create.
-- max_ipc_namespaces
+max_ipc_namespaces
+==================
The maximum number of ipc namespaces that any user in the current
user namespace may create.
-- max_mnt_namespaces
+max_mnt_namespaces
+==================
The maximum number of mount namespaces that any user in the current
user namespace may create.
-- max_net_namespaces
+max_net_namespaces
+==================
The maximum number of network namespaces that any user in the
current user namespace may create.
-- max_pid_namespaces
+max_pid_namespaces
+==================
The maximum number of pid namespaces that any user in the current
user namespace may create.
-- max_user_namespaces
+max_user_namespaces
+===================
The maximum number of user namespaces that any user in the current
user namespace may create.
-- max_uts_namespaces
+max_uts_namespaces
+==================
The maximum number of user namespaces that any user in the current
user namespace may create.
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.rst
similarity index 85%
rename from Documentation/sysctl/vm.txt
rename to Documentation/sysctl/vm.rst
index c5f0d44433a2..5aceb5cd5ce7 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.rst
@@ -1,10 +1,16 @@
-Documentation for /proc/sys/vm/* kernel version 2.6.29
- (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
- (c) 2008 Peter W. Morreale <pmorreale@novell.com>
+===============================
+Documentation for /proc/sys/vm/
+===============================
-For general info and legal blurb, please look in README.
+kernel version 2.6.29
-==============================================================
+Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
+
+Copyright (c) 2008 Peter W. Morreale <pmorreale@novell.com>
+
+For general info and legal blurb, please look in index.rst.
+
+------------------------------------------------------------------------------
This file contains the documentation for the sysctl files in
/proc/sys/vm and is valid for Linux kernel version 2.6.29.
@@ -68,9 +74,9 @@ Currently, these files are in /proc/sys/vm:
- watermark_scale_factor
- zone_reclaim_mode
-==============================================================
admin_reserve_kbytes
+====================
The amount of free memory in the system that should be reserved for users
with the capability cap_sys_admin.
@@ -97,25 +103,25 @@ On x86_64 this is about 128MB.
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.rst.
-==============================================================
compact_memory
+==============
Available only when CONFIG_COMPACTION is set. When 1 is written to the file,
all zones are compacted such that free memory is available in contiguous
blocks where possible. This can be important for example in the allocation of
huge pages although processes will also directly compact memory as required.
-==============================================================
compact_unevictable_allowed
+===========================
Available only when CONFIG_COMPACTION is set. When set to 1, compaction is
allowed to examine the unevictable lru (mlocked pages) for pages to compact.
@@ -123,21 +129,22 @@ This should be used on systems where stalls for minor page faults are an
acceptable trade for large contiguous free memory. Set to 0 to prevent
compaction from moving pages that are unevictable. Default value is 1.
-==============================================================
dirty_background_bytes
+======================
Contains the amount of dirty memory at which the background kernel
flusher threads will start writeback.
-Note: dirty_background_bytes is the counterpart of dirty_background_ratio. Only
-one of them may be specified at a time. When one sysctl is written it is
-immediately taken into account to evaluate the dirty memory limits and the
-other appears as 0 when read.
+Note:
+ dirty_background_bytes is the counterpart of dirty_background_ratio. Only
+ one of them may be specified at a time. When one sysctl is written it is
+ immediately taken into account to evaluate the dirty memory limits and the
+ other appears as 0 when read.
-==============================================================
dirty_background_ratio
+======================
Contains, as a percentage of total available memory that contains free pages
and reclaimable pages, the number of pages at which the background kernel
@@ -145,9 +152,9 @@ flusher threads will start writing out dirty data.
The total available memory is not equal to total system memory.
-==============================================================
dirty_bytes
+===========
Contains the amount of dirty memory at which a process generating disk writes
will itself start writeback.
@@ -161,18 +168,18 @@ Note: the minimum value allowed for dirty_bytes is two pages (in bytes); any
value lower than this limit will be ignored and the old configuration will be
retained.
-==============================================================
dirty_expire_centisecs
+======================
This tunable is used to define when dirty data is old enough to be eligible
for writeout by the kernel flusher threads. It is expressed in 100'ths
of a second. Data which has been dirty in-memory for longer than this
interval will be written out next time a flusher thread wakes up.
-==============================================================
dirty_ratio
+===========
Contains, as a percentage of total available memory that contains free pages
and reclaimable pages, the number of pages at which a process which is
@@ -180,9 +187,9 @@ generating disk writes will itself start writing out dirty data.
The total available memory is not equal to total system memory.
-==============================================================
dirtytime_expire_seconds
+========================
When a lazytime inode is constantly having its pages dirtied, the inode with
an updated timestamp will never get chance to be written out. And, if the
@@ -192,34 +199,39 @@ eventually gets pushed out to disk. This tunable is used to define when dirty
inode is old enough to be eligible for writeback by the kernel flusher threads.
And, it is also used as the interval to wakeup dirtytime_writeback thread.
-==============================================================
dirty_writeback_centisecs
+=========================
-The kernel flusher threads will periodically wake up and write `old' data
+The kernel flusher threads will periodically wake up and write `old` data
out to disk. This tunable expresses the interval between those wakeups, in
100'ths of a second.
Setting this to zero disables periodic writeback altogether.
-==============================================================
drop_caches
+===========
Writing to this will cause the kernel to drop clean caches, as well as
reclaimable slab objects like dentries and inodes. Once dropped, their
memory becomes free.
-To free pagecache:
+To free pagecache::
+
echo 1 > /proc/sys/vm/drop_caches
-To free reclaimable slab objects (includes dentries and inodes):
+
+To free reclaimable slab objects (includes dentries and inodes)::
+
echo 2 > /proc/sys/vm/drop_caches
-To free slab objects and pagecache:
+
+To free slab objects and pagecache::
+
echo 3 > /proc/sys/vm/drop_caches
This is a non-destructive operation and will not free any dirty objects.
To increase the number of objects freed by this operation, the user may run
-`sync' prior to writing to /proc/sys/vm/drop_caches. This will minimize the
+`sync` prior to writing to /proc/sys/vm/drop_caches. This will minimize the
number of dirty objects on the system and create more candidates to be
dropped.
@@ -233,16 +245,16 @@ dropped objects, especially if they were under heavy use. Because of this,
use outside of a testing or debugging environment is not recommended.
You may see informational messages in your kernel log when this file is
-used:
+used::
cat (1234): drop_caches: 3
These are informational only. They do not mean that anything is wrong
with your system. To disable them, echo 4 (bit 2) into drop_caches.
-==============================================================
extfrag_threshold
+=================
This parameter affects whether the kernel will compact memory or direct
reclaim to satisfy a high-order allocation. The extfrag/extfrag_index file in
@@ -254,9 +266,9 @@ implies that the allocation will succeed as long as watermarks are met.
The kernel will not compact memory in a zone if the
fragmentation index is <= extfrag_threshold. The default value is 500.
-==============================================================
highmem_is_dirtyable
+====================
Available only for systems with CONFIG_HIGHMEM enabled (32b systems).
@@ -274,30 +286,30 @@ OOM killer because some writers (e.g. direct block device writes) can
only use the low memory and they can fill it up with dirty data without
any throttling.
-==============================================================
hugetlb_shm_group
+=================
hugetlb_shm_group contains group id that is allowed to create SysV
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.rst.
-==============================================================
legacy_va_layout
+================
If non-zero, this sysctl disables the new 32-bit mmap layout - the kernel
will use the legacy (2.4) layout for all processes.
-==============================================================
lowmem_reserve_ratio
+====================
For some specialised workloads on highmem machines it is dangerous for
the kernel to allow process memory to be allocated from the "lowmem"
@@ -308,7 +320,7 @@ And on large highmem machines this lack of reclaimable lowmem memory
can be fatal.
So the Linux page allocator has a mechanism which prevents allocations
-which _could_ use highmem from using too much lowmem. This means that
+which *could* use highmem from using too much lowmem. This means that
a certain amount of lowmem is defended from the possibility of being
captured into pinned user memory.
@@ -316,39 +328,37 @@ captured into pinned user memory.
mechanism will also defend that region from allocations which could use
highmem or lowmem).
-The `lowmem_reserve_ratio' tunable determines how aggressive the kernel is
+The `lowmem_reserve_ratio` tunable determines how aggressive the kernel is
in defending these lower zones.
If you have a machine which uses highmem or ISA DMA and your
applications are using mlock(), or if you are running with no swap then
you probably should change the lowmem_reserve_ratio setting.
-The lowmem_reserve_ratio is an array. You can see them by reading this file.
--
-% cat /proc/sys/vm/lowmem_reserve_ratio
-256 256 32
--
+The lowmem_reserve_ratio is an array. You can see them by reading this file::
+
+ % cat /proc/sys/vm/lowmem_reserve_ratio
+ 256 256 32
But, these values are not used directly. The kernel calculates # of protection
pages for each zones from them. These are shown as array of protection pages
in /proc/zoneinfo like followings. (This is an example of x86-64 box).
-Each zone has an array of protection pages like this.
+Each zone has an array of protection pages like this::
--
-Node 0, zone DMA
- pages free 1355
- min 3
- low 3
- high 4
+ Node 0, zone DMA
+ pages free 1355
+ min 3
+ low 3
+ high 4
:
:
- numa_other 0
- protection: (0, 2004, 2004, 2004)
+ numa_other 0
+ protection: (0, 2004, 2004, 2004)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- pagesets
- cpu: 0 pcp: 0
- :
--
+ pagesets
+ cpu: 0 pcp: 0
+ :
+
These protections are added to score to judge whether this zone should be used
for page allocation or should be reclaimed.
@@ -359,20 +369,24 @@ not be used because pages_free(1355) is smaller than watermark + protection[2]
normal page requirement. If requirement is DMA zone(index=0), protection[0]
(=0) is used.
-zone[i]'s protection[j] is calculated by following expression.
+zone[i]'s protection[j] is calculated by following expression::
-(i < j):
- zone[i]->protection[j]
- = (total sums of managed_pages from zone[i+1] to zone[j] on the node)
- / lowmem_reserve_ratio[i];
-(i = j):
- (should not be protected. = 0;
-(i > j):
- (not necessary, but looks 0)
+ (i < j):
+ zone[i]->protection[j]
+ = (total sums of managed_pages from zone[i+1] to zone[j] on the node)
+ / lowmem_reserve_ratio[i];
+ (i = j):
+ (should not be protected. = 0;
+ (i > j):
+ (not necessary, but looks 0)
The default values of lowmem_reserve_ratio[i] are
+
+ === ====================================
256 (if zone[i] means DMA or DMA32 zone)
- 32 (others).
+ 32 (others)
+ === ====================================
+
As above expression, they are reciprocal number of ratio.
256 means 1/256. # of protection pages becomes about "0.39%" of total managed
pages of higher zones on the node.
@@ -381,9 +395,9 @@ If you would like to protect more pages, smaller values are effective.
The minimum value is 1 (1/1 -> 100%). The value less than 1 completely
disables protection of the pages.
-==============================================================
max_map_count:
+==============
This file contains the maximum number of memory map areas a process
may have. Memory map areas are used as a side-effect of calling
@@ -396,9 +410,9 @@ e.g., up to one or two maps per allocation.
The default value is 65536.
-=============================================================
memory_failure_early_kill:
+==========================
Control how to kill processes when uncorrected memory error (typically
a 2bit error in a memory module) is detected in the background by hardware
@@ -424,9 +438,9 @@ check handling and depends on the hardware capabilities.
Applications can override this setting individually with the PR_MCE_KILL prctl
-==============================================================
memory_failure_recovery
+=======================
Enable memory failure recovery (when supported by the platform)
@@ -434,9 +448,9 @@ Enable memory failure recovery (when supported by the platform)
0: Always panic on a memory failure.
-==============================================================
-min_free_kbytes:
+min_free_kbytes
+===============
This is used to force the Linux VM to keep a minimum number
of kilobytes free. The VM uses this number to compute a
@@ -450,9 +464,9 @@ become subtly broken, and prone to deadlock under high loads.
Setting this too high will OOM your machine instantly.
-=============================================================
-min_slab_ratio:
+min_slab_ratio
+==============
This is available only on NUMA kernels.
@@ -468,9 +482,9 @@ Note that slab reclaim is triggered in a per zone / node fashion.
The process of reclaiming slab memory is currently not node specific
and may not be fast.
-=============================================================
-min_unmapped_ratio:
+min_unmapped_ratio
+==================
This is available only on NUMA kernels.
@@ -485,9 +499,9 @@ files and similar are considered.
The default is 1 percent.
-==============================================================
mmap_min_addr
+=============
This file indicates the amount of address space which a user process will
be restricted from mmapping. Since kernel null dereference bugs could
@@ -498,9 +512,9 @@ security module. Setting this value to something like 64k will allow the
vast majority of applications to work correctly and provide defense in depth
against future potential kernel bugs.
-==============================================================
-mmap_rnd_bits:
+mmap_rnd_bits
+=============
This value can be used to select the number of bits to use to
determine the random offset to the base address of vma regions
@@ -511,9 +525,9 @@ by the architecture's minimum and maximum supported values.
This value can be changed after boot using the
/proc/sys/vm/mmap_rnd_bits tunable
-==============================================================
-mmap_rnd_compat_bits:
+mmap_rnd_compat_bits
+====================
This value can be used to select the number of bits to use to
determine the random offset to the base address of vma regions
@@ -525,35 +539,35 @@ architecture's minimum and maximum supported values.
This value can be changed after boot using the
/proc/sys/vm/mmap_rnd_compat_bits tunable
-==============================================================
nr_hugepages
+============
Change the minimum size of the hugepage pool.
See Documentation/admin-guide/mm/hugetlbpage.rst
-==============================================================
nr_hugepages_mempolicy
+======================
Change the size of the hugepage pool at run-time on a specific
set of NUMA nodes.
See Documentation/admin-guide/mm/hugetlbpage.rst
-==============================================================
nr_overcommit_hugepages
+=======================
Change the maximum size of the hugepage pool. The maximum is
nr_hugepages + nr_overcommit_hugepages.
See Documentation/admin-guide/mm/hugetlbpage.rst
-==============================================================
nr_trim_pages
+=============
This is available only on NOMMU kernels.
@@ -568,16 +582,17 @@ The default value is 1.
See Documentation/nommu-mmap.txt for more information.
-==============================================================
numa_zonelist_order
+===================
This sysctl is only for NUMA and it is deprecated. Anything but
Node order will fail!
'where the memory is allocated from' is controlled by zonelists.
+
(This documentation ignores ZONE_HIGHMEM/ZONE_DMA32 for simple explanation.
- you may be able to read ZONE_DMA as ZONE_DMA32...)
+you may be able to read ZONE_DMA as ZONE_DMA32...)
In non-NUMA case, a zonelist for GFP_KERNEL is ordered as following.
ZONE_NORMAL -> ZONE_DMA
@@ -585,10 +600,10 @@ This means that a memory allocation request for GFP_KERNEL will
get memory from ZONE_DMA only when ZONE_NORMAL is not available.
In NUMA case, you can think of following 2 types of order.
-Assume 2 node NUMA and below is zonelist of Node(0)'s GFP_KERNEL
+Assume 2 node NUMA and below is zonelist of Node(0)'s GFP_KERNEL::
-(A) Node(0) ZONE_NORMAL -> Node(0) ZONE_DMA -> Node(1) ZONE_NORMAL
-(B) Node(0) ZONE_NORMAL -> Node(1) ZONE_NORMAL -> Node(0) ZONE_DMA.
+ (A) Node(0) ZONE_NORMAL -> Node(0) ZONE_DMA -> Node(1) ZONE_NORMAL
+ (B) Node(0) ZONE_NORMAL -> Node(1) ZONE_NORMAL -> Node(0) ZONE_DMA.
Type(A) offers the best locality for processes on Node(0), but ZONE_DMA
will be used before ZONE_NORMAL exhaustion. This increases possibility of
@@ -616,9 +631,9 @@ order will be selected.
Default order is recommended unless this is causing problems for your
system/application.
-==============================================================
oom_dump_tasks
+==============
Enables a system-wide task dump (excluding kernel threads) to be produced
when the kernel performs an OOM-killing and includes such information as
@@ -638,9 +653,9 @@ OOM killer actually kills a memory-hogging task.
The default value is 1 (enabled).
-==============================================================
oom_kill_allocating_task
+========================
This enables or disables killing the OOM-triggering task in
out-of-memory situations.
@@ -659,9 +674,9 @@ is used in oom_kill_allocating_task.
The default value is 0.
-==============================================================
-overcommit_kbytes:
+overcommit_kbytes
+=================
When overcommit_memory is set to 2, the committed address space is not
permitted to exceed swap plus this amount of physical RAM. See below.
@@ -670,9 +685,9 @@ Note: overcommit_kbytes is the counterpart of overcommit_ratio. Only one
of them may be specified at a time. Setting one disables the other (which
then appears as 0 when read).
-==============================================================
-overcommit_memory:
+overcommit_memory
+=================
This value contains a flag that enables memory overcommitment.
@@ -695,17 +710,17 @@ The default value is 0.
See Documentation/vm/overcommit-accounting.rst and
mm/util.c::__vm_enough_memory() for more information.
-==============================================================
-overcommit_ratio:
+overcommit_ratio
+================
When overcommit_memory is set to 2, the committed address
space is not permitted to exceed swap plus this percentage
of physical RAM. See above.
-==============================================================
page-cluster
+============
page-cluster controls the number of pages up to which consecutive pages
are read in from swap in a single attempt. This is the swap counterpart
@@ -725,9 +740,9 @@ Lower values mean lower latencies for initial faults, but at the same time
extra faults and I/O delays for following faults if they would have been part of
that consecutive pages readahead would have brought in.
-=============================================================
panic_on_oom
+============
This enables or disables panic on out-of-memory feature.
@@ -747,14 +762,16 @@ above-mentioned. Even oom happens under memory cgroup, the whole
system panics.
The default value is 0.
+
1 and 2 are for failover of clustering. Please select either
according to your policy of failover.
+
panic_on_oom=2+kdump gives you very strong tool to investigate
why oom happens. You can get snapshot.
-=============================================================
percpu_pagelist_fraction
+========================
This is the fraction of pages at most (high mark pcp->high) in each zone that
are allocated for each per cpu page list. The min value for this is 8. It
@@ -770,16 +787,16 @@ The initial value is zero. Kernel does not use this value at boot time to set
the high water marks for each per cpu page list. If the user writes '0' to this
sysctl, it will revert to this default behavior.
-==============================================================
stat_interval
+=============
The time interval between which vm statistics are updated. The default
is 1 second.
-==============================================================
stat_refresh
+============
Any read or write (by root only) flushes all the per-cpu vm statistics
into their global totals, for more accurate reports when testing
@@ -790,24 +807,26 @@ as 0) and "fails" with EINVAL if any are found, with a warning in dmesg.
(At time of writing, a few stats are known sometimes to be found negative,
with no ill effects: errors and warnings on these stats are suppressed.)
-==============================================================
numa_stat
+=========
This interface allows runtime configuration of numa statistics.
When page allocation performance becomes a bottleneck and you can tolerate
some possible tool breakage and decreased numa counter precision, you can
-do:
+do::
+
echo 0 > /proc/sys/vm/numa_stat
When page allocation performance is not a bottleneck and you want all
-tooling to work, you can do:
+tooling to work, you can do::
+
echo 1 > /proc/sys/vm/numa_stat
-==============================================================
swappiness
+==========
This control is used to define how aggressive the kernel will swap
memory pages. Higher values will increase aggressiveness, lower values
@@ -817,9 +836,9 @@ than the high water mark in a zone.
The default value is 60.
-==============================================================
unprivileged_userfaultfd
+========================
This flag controls whether unprivileged users can use the userfaultfd
system calls. Set this to 1 to allow unprivileged users to use the
@@ -828,9 +847,9 @@ privileged users (with SYS_CAP_PTRACE capability).
The default value is 1.
-==============================================================
-- user_reserve_kbytes
+user_reserve_kbytes
+===================
When overcommit_memory is set to 2, "never overcommit" mode, reserve
min(3% of current process size, user_reserve_kbytes) of free memory.
@@ -846,10 +865,9 @@ Any subsequent attempts to execute a command will result in
Changing this takes effect whenever an application requests memory.
-==============================================================
vfs_cache_pressure
-------------------
+==================
This percentage value controls the tendency of the kernel to reclaim
the memory which is used for caching of directory and inode objects.
@@ -867,9 +885,9 @@ performance impact. Reclaim code needs to take various locks to find freeable
directory and inode objects. With vfs_cache_pressure=1000, it will look for
ten times more freeable objects than there are.
-=============================================================
-watermark_boost_factor:
+watermark_boost_factor
+======================
This factor controls the level of reclaim when memory is being fragmented.
It defines the percentage of the high watermark of a zone that will be
@@ -887,9 +905,9 @@ fragmentation events that occurred in the recent past. If this value is
smaller than a pageblock then a pageblocks worth of pages will be reclaimed
(e.g. 2MB on 64-bit x86). A boost factor of 0 will disable the feature.
-=============================================================
-watermark_scale_factor:
+watermark_scale_factor
+======================
This factor controls the aggressiveness of kswapd. It defines the
amount of memory left in a node/system before kswapd is woken up and
@@ -905,20 +923,22 @@ that the number of free pages kswapd maintains for latency reasons is
too small for the allocation bursts occurring in the system. This knob
can then be used to tune kswapd aggressiveness accordingly.
-==============================================================
-zone_reclaim_mode:
+zone_reclaim_mode
+=================
Zone_reclaim_mode allows someone to set more or less aggressive approaches to
reclaim memory when a zone runs out of memory. If it is set to zero then no
zone reclaim occurs. Allocations will be satisfied from other zones / nodes
in the system.
-This is value ORed together of
+This is value OR'ed together of
-1 = Zone reclaim on
-2 = Zone reclaim writes dirty pages out
-4 = Zone reclaim swaps pages
+= ===================================
+1 Zone reclaim on
+2 Zone reclaim writes dirty pages out
+4 Zone reclaim swaps pages
+= ===================================
zone_reclaim_mode is disabled by default. For file servers or workloads
that benefit from having their data cached, zone_reclaim_mode should be
@@ -942,5 +962,3 @@ of other processes running on other nodes will not be affected.
Allowing regular swap effectively restricts allocations to the local
node unless explicitly overridden by memory policies or cpuset
configurations.
-
-============ End of Document =================================
diff --git a/Documentation/vm/unevictable-lru.rst b/Documentation/vm/unevictable-lru.rst
index c6d94118fbcc..8ba656f37cd8 100644
--- a/Documentation/vm/unevictable-lru.rst
+++ b/Documentation/vm/unevictable-lru.rst
@@ -439,7 +439,7 @@ Compacting MLOCKED Pages
The unevictable LRU can be scanned for compactable regions and the default
behavior is to do so. /proc/sys/vm/compact_unevictable_allowed controls
-this behavior (see Documentation/sysctl/vm.txt). Once scanning of the
+this behavior (see Documentation/sysctl/vm.rst). Once scanning of the
unevictable LRU is enabled, the work of compaction is mostly handled by
the page migration code and the same work flow as described in MIGRATING
MLOCKED PAGES will apply.
diff --git a/kernel/panic.c b/kernel/panic.c
index 4d9f55bf7d38..e0ea74bbb41d 100644
--- a/kernel/panic.c
+++ b/kernel/panic.c
@@ -372,7 +372,7 @@ const struct taint_flag taint_flags[TAINT_FLAGS_COUNT] = {
/**
* print_tainted - return a string to represent the kernel taint state.
*
- * For individual taint flag meanings, see Documentation/sysctl/kernel.txt
+ * For individual taint flag meanings, see Documentation/sysctl/kernel.rst
*
* The string is overwritten by the next call to print_tainted(),
* but is always NULL terminated.
diff --git a/mm/swap.c b/mm/swap.c
index 607c48229a1d..83a2a15f4836 100644
--- a/mm/swap.c
+++ b/mm/swap.c
@@ -8,7 +8,7 @@
/*
* This file contains the default values for the operation of the
* Linux VM subsystem. Fine-tuning documentation can be found in
- * Documentation/sysctl/vm.txt.
+ * Documentation/sysctl/vm.rst.
* Started 18.12.91
* Swap aging added 23.2.95, Stephen Tweedie.
* Buffermem limits added 12.3.98, Rik van Riel.
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 40/43] docs: block: convert to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (37 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 39/43] docs: sysctl: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir Mauro Carvalho Chehab
` (3 subsequent siblings)
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Paolo Valente, Jens Axboe, linux-block
Rename the block 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>
---
.../admin-guide/kernel-parameters.txt | 8 +-
.../{bfq-iosched.txt => bfq-iosched.rst} | 66 ++--
.../block/{biodoc.txt => biodoc.rst} | 328 +++++++++++-------
.../block/{biovecs.txt => biovecs.rst} | 20 +-
Documentation/block/capability.rst | 18 +
Documentation/block/capability.txt | 15 -
...ne-partition.txt => cmdline-partition.rst} | 13 +-
...{data-integrity.txt => data-integrity.rst} | 60 ++--
...dline-iosched.txt => deadline-iosched.rst} | 21 +-
Documentation/block/index.rst | 25 ++
.../block/{ioprio.txt => ioprio.rst} | 95 +++--
.../{kyber-iosched.txt => kyber-iosched.rst} | 3 +-
.../block/{null_blk.txt => null_blk.rst} | 65 +++-
Documentation/block/{pr.txt => pr.rst} | 18 +-
.../{queue-sysfs.txt => queue-sysfs.rst} | 7 +-
.../block/{request.txt => request.rst} | 47 ++-
Documentation/block/{stat.txt => stat.rst} | 13 +-
...witching-sched.txt => switching-sched.rst} | 28 +-
...ontrol.txt => writeback_cache_control.rst} | 12 +-
Documentation/blockdev/zram.rst | 2 +-
MAINTAINERS | 2 +-
block/Kconfig | 2 +-
block/Kconfig.iosched | 2 +-
block/bfq-iosched.c | 2 +-
block/blk-integrity.c | 2 +-
block/ioprio.c | 2 +-
block/mq-deadline.c | 2 +-
block/partitions/cmdline.c | 2 +-
28 files changed, 540 insertions(+), 340 deletions(-)
rename Documentation/block/{bfq-iosched.txt => bfq-iosched.rst} (95%)
rename Documentation/block/{biodoc.txt => biodoc.rst} (85%)
rename Documentation/block/{biovecs.txt => biovecs.rst} (92%)
create mode 100644 Documentation/block/capability.rst
delete mode 100644 Documentation/block/capability.txt
rename Documentation/block/{cmdline-partition.txt => cmdline-partition.rst} (92%)
rename Documentation/block/{data-integrity.txt => data-integrity.rst} (91%)
rename Documentation/block/{deadline-iosched.txt => deadline-iosched.rst} (89%)
create mode 100644 Documentation/block/index.rst
rename Documentation/block/{ioprio.txt => ioprio.rst} (75%)
rename Documentation/block/{kyber-iosched.txt => kyber-iosched.rst} (86%)
rename Documentation/block/{null_blk.txt => null_blk.rst} (60%)
rename Documentation/block/{pr.txt => pr.rst} (93%)
rename Documentation/block/{queue-sysfs.txt => queue-sysfs.rst} (99%)
rename Documentation/block/{request.txt => request.rst} (59%)
rename Documentation/block/{stat.txt => stat.rst} (89%)
rename Documentation/block/{switching-sched.txt => switching-sched.rst} (67%)
rename Documentation/block/{writeback_cache_control.txt => writeback_cache_control.rst} (94%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 61abadd70a86..b2007fb4daf0 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -430,7 +430,7 @@
blkdevparts= Manual partition parsing of block device(s) for
embedded devices based on command line input.
- See Documentation/block/cmdline-partition.txt
+ See Documentation/block/cmdline-partition.rst
boot_delay= Milliseconds to delay each printk during boot.
Values larger than 10 seconds (10000) are changed to
@@ -1199,9 +1199,9 @@
elevator= [IOSCHED]
Format: { "mq-deadline" | "kyber" | "bfq" }
- See Documentation/block/deadline-iosched.txt,
- Documentation/block/kyber-iosched.txt and
- Documentation/block/bfq-iosched.txt for details.
+ See Documentation/block/deadline-iosched.rst,
+ Documentation/block/kyber-iosched.rst and
+ Documentation/block/bfq-iosched.rst for details.
elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390]
Specifies physical address of start of kernel core
diff --git a/Documentation/block/bfq-iosched.txt b/Documentation/block/bfq-iosched.rst
similarity index 95%
rename from Documentation/block/bfq-iosched.txt
rename to Documentation/block/bfq-iosched.rst
index bbd6eb5bbb07..2c13b2fc1888 100644
--- a/Documentation/block/bfq-iosched.txt
+++ b/Documentation/block/bfq-iosched.rst
@@ -1,9 +1,11 @@
+==========================
BFQ (Budget Fair Queueing)
==========================
BFQ is a proportional-share I/O scheduler, with some extra
low-latency capabilities. In addition to cgroups support (blkio or io
controllers), BFQ's main features are:
+
- BFQ guarantees a high system and application responsiveness, and a
low latency for time-sensitive applications, such as audio or video
players;
@@ -55,18 +57,18 @@ sustainable throughputs, on the same systems as above:
BFQ works for multi-queue devices too.
-The table of contents follow. Impatients can just jump to Section 3.
+.. The table of contents follow. Impatients can just jump to Section 3.
-CONTENTS
+.. CONTENTS
-1. When may BFQ be useful?
- 1-1 Personal systems
- 1-2 Server systems
-2. How does BFQ work?
-3. What are BFQ's tunables and how to properly configure BFQ?
-4. BFQ group scheduling
- 4-1 Service guarantees provided
- 4-2 Interface
+ 1. When may BFQ be useful?
+ 1-1 Personal systems
+ 1-2 Server systems
+ 2. How does BFQ work?
+ 3. What are BFQ's tunables and how to properly configure BFQ?
+ 4. BFQ group scheduling
+ 4-1 Service guarantees provided
+ 4-2 Interface
1. When may BFQ be useful?
==========================
@@ -77,17 +79,20 @@ BFQ provides the following benefits on personal and server systems.
--------------------
Low latency for interactive applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Regardless of the actual background workload, BFQ guarantees that, for
interactive tasks, the storage device is virtually as responsive as if
it was idle. For example, even if one or more of the following
background workloads are being executed:
+
- one or more large files are being read, written or copied,
- a tree of source files is being compiled,
- one or more virtual machines are performing I/O,
- a software update is in progress,
- indexing daemons are scanning filesystems and updating their
databases,
+
starting an application or loading a file from within an application
takes about the same time as if the storage device was idle. As a
comparison, with CFQ, NOOP or DEADLINE, and in the same conditions,
@@ -95,13 +100,14 @@ applications experience high latencies, or even become unresponsive
until the background workload terminates (also on SSDs).
Low latency for soft real-time applications
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Also soft real-time applications, such as audio and video
players/streamers, enjoy a low latency and a low drop rate, regardless
of the background I/O workload. As a consequence, these applications
do not suffer from almost any glitch due to the background workload.
Higher speed for code-development tasks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If some additional workload happens to be executed in parallel, then
BFQ executes the I/O-related components of typical code-development
@@ -109,6 +115,7 @@ tasks (compilation, checkout, merge, ...) much more quickly than CFQ,
NOOP or DEADLINE.
High throughput
+^^^^^^^^^^^^^^^
On hard disks, BFQ achieves up to 30% higher throughput than CFQ, and
up to 150% higher throughput than DEADLINE and NOOP, with all the
@@ -117,6 +124,7 @@ and with all the workloads on flash-based devices, BFQ achieves,
instead, about the same throughput as the other schedulers.
Strong fairness, bandwidth and delay guarantees
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BFQ distributes the device throughput, and not just the device time,
among I/O-bound applications in proportion their weights, with any
@@ -133,15 +141,15 @@ Most benefits for server systems follow from the same service
properties as above. In particular, regardless of whether additional,
possibly heavy workloads are being served, BFQ guarantees:
-. audio and video-streaming with zero or very low jitter and drop
+* audio and video-streaming with zero or very low jitter and drop
rate;
-. fast retrieval of WEB pages and embedded objects;
+* fast retrieval of WEB pages and embedded objects;
-. real-time recording of data in live-dumping applications (e.g.,
+* real-time recording of data in live-dumping applications (e.g.,
packet logging);
-. responsiveness in local and remote access to a server.
+* responsiveness in local and remote access to a server.
2. How does BFQ work?
@@ -151,7 +159,7 @@ BFQ is a proportional-share I/O scheduler, whose general structure,
plus a lot of code, are borrowed from CFQ.
- Each process doing I/O on a device is associated with a weight and a
- (bfq_)queue.
+ `(bfq_)queue`.
- BFQ grants exclusive access to the device, for a while, to one queue
(process) at a time, and implements this service model by
@@ -540,11 +548,12 @@ created, and kept up-to-date by bfq, depends on whether
CONFIG_BFQ_CGROUP_DEBUG is set. If it is set, then bfq creates all
the stat files documented in
Documentation/cgroup-v1/blkio-controller.rst. If, instead,
-CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files
-blkio.bfq.io_service_bytes
-blkio.bfq.io_service_bytes_recursive
-blkio.bfq.io_serviced
-blkio.bfq.io_serviced_recursive
+CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files::
+
+ blkio.bfq.io_service_bytes
+ blkio.bfq.io_service_bytes_recursive
+ blkio.bfq.io_serviced
+ blkio.bfq.io_serviced_recursive
The value of CONFIG_BFQ_CGROUP_DEBUG greatly influences the maximum
throughput sustainable with bfq, because updating the blkio.bfq.*
@@ -567,17 +576,22 @@ weight of the queues associated with interactive and soft real-time
applications. Unset this tunable if you need/want to control weights.
-[1] P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O
+[1]
+ P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O
Scheduler", Proceedings of the First Workshop on Mobile System
Technologies (MST-2015), May 2015.
+
http://algogroup.unimore.it/people/paolo/disk_sched/mst-2015.pdf
-[2] P. Valente and M. Andreolini, "Improving Application
+[2]
+ P. Valente and M. Andreolini, "Improving Application
Responsiveness with the BFQ Disk I/O Scheduler", Proceedings of
the 5th Annual International Systems and Storage Conference
(SYSTOR '12), June 2012.
+
Slightly extended version:
- http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite-
- results.pdf
-[3] https://github.com/Algodev-github/S
+ http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite-results.pdf
+
+[3]
+ https://github.com/Algodev-github/S
diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.rst
similarity index 85%
rename from Documentation/block/biodoc.txt
rename to Documentation/block/biodoc.rst
index 31c177663ed5..d6e30b680405 100644
--- a/Documentation/block/biodoc.txt
+++ b/Documentation/block/biodoc.rst
@@ -1,15 +1,24 @@
- Notes on the Generic Block Layer Rewrite in Linux 2.5
- =====================================================
+=====================================================
+Notes on the Generic Block Layer Rewrite in Linux 2.5
+=====================================================
+
+.. note::
+
+ It seems that there are lot of outdated stuff here. This seems
+ to be written somewhat as a task list. Yet, eventually, something
+ here might still be useful.
Notes Written on Jan 15, 2002:
- Jens Axboe <jens.axboe@oracle.com>
- Suparna Bhattacharya <suparna@in.ibm.com>
+ - Jens Axboe <jens.axboe@oracle.com>
+ - Suparna Bhattacharya <suparna@in.ibm.com>
Last Updated May 2, 2002
+
September 2003: Updated I/O Scheduler portions
- Nick Piggin <npiggin@kernel.dk>
+ - Nick Piggin <npiggin@kernel.dk>
-Introduction:
+Introduction
+============
These are some notes describing some aspects of the 2.5 block layer in the
context of the bio rewrite. The idea is to bring out some of the key
@@ -17,11 +26,11 @@ changes and a glimpse of the rationale behind those changes.
Please mail corrections & suggestions to suparna@in.ibm.com.
-Credits:
----------
+Credits
+=======
2.5 bio rewrite:
- Jens Axboe <jens.axboe@oracle.com>
+ - Jens Axboe <jens.axboe@oracle.com>
Many aspects of the generic block layer redesign were driven by and evolved
over discussions, prior patches and the collective experience of several
@@ -29,62 +38,63 @@ people. See sections 8 and 9 for a list of some related references.
The following people helped with review comments and inputs for this
document:
- Christoph Hellwig <hch@infradead.org>
- Arjan van de Ven <arjanv@redhat.com>
- Randy Dunlap <rdunlap@xenotime.net>
- Andre Hedrick <andre@linux-ide.org>
+
+ - Christoph Hellwig <hch@infradead.org>
+ - Arjan van de Ven <arjanv@redhat.com>
+ - Randy Dunlap <rdunlap@xenotime.net>
+ - Andre Hedrick <andre@linux-ide.org>
The following people helped with fixes/contributions to the bio patches
while it was still work-in-progress:
- David S. Miller <davem@redhat.com>
+ - David S. Miller <davem@redhat.com>
-Description of Contents:
-------------------------
-1. Scope for tuning of logic to various needs
- 1.1 Tuning based on device or low level driver capabilities
+.. Description of Contents:
+
+ 1. Scope for tuning of logic to various needs
+ 1.1 Tuning based on device or low level driver capabilities
- Per-queue parameters
- Highmem I/O support
- I/O scheduler modularization
- 1.2 Tuning based on high level requirements/capabilities
+ 1.2 Tuning based on high level requirements/capabilities
1.2.1 Request Priority/Latency
- 1.3 Direct access/bypass to lower layers for diagnostics and special
- device operations
+ 1.3 Direct access/bypass to lower layers for diagnostics and special
+ device operations
1.3.1 Pre-built commands
-2. New flexible and generic but minimalist i/o structure or descriptor
- (instead of using buffer heads at the i/o layer)
- 2.1 Requirements/Goals addressed
- 2.2 The bio struct in detail (multi-page io unit)
- 2.3 Changes in the request structure
-3. Using bios
- 3.1 Setup/teardown (allocation, splitting)
- 3.2 Generic bio helper routines
- 3.2.1 Traversing segments and completion units in a request
- 3.2.2 Setting up DMA scatterlists
- 3.2.3 I/O completion
- 3.2.4 Implications for drivers that do not interpret bios (don't handle
- multiple segments)
- 3.3 I/O submission
-4. The I/O scheduler
-5. Scalability related changes
- 5.1 Granular locking: Removal of io_request_lock
- 5.2 Prepare for transition to 64 bit sector_t
-6. Other Changes/Implications
- 6.1 Partition re-mapping handled by the generic block layer
-7. A few tips on migration of older drivers
-8. A list of prior/related/impacted patches/ideas
-9. Other References/Discussion Threads
+ 2. New flexible and generic but minimalist i/o structure or descriptor
+ (instead of using buffer heads at the i/o layer)
+ 2.1 Requirements/Goals addressed
+ 2.2 The bio struct in detail (multi-page io unit)
+ 2.3 Changes in the request structure
+ 3. Using bios
+ 3.1 Setup/teardown (allocation, splitting)
+ 3.2 Generic bio helper routines
+ 3.2.1 Traversing segments and completion units in a request
+ 3.2.2 Setting up DMA scatterlists
+ 3.2.3 I/O completion
+ 3.2.4 Implications for drivers that do not interpret bios (don't handle
+ multiple segments)
+ 3.3 I/O submission
+ 4. The I/O scheduler
+ 5. Scalability related changes
+ 5.1 Granular locking: Removal of io_request_lock
+ 5.2 Prepare for transition to 64 bit sector_t
+ 6. Other Changes/Implications
+ 6.1 Partition re-mapping handled by the generic block layer
+ 7. A few tips on migration of older drivers
+ 8. A list of prior/related/impacted patches/ideas
+ 9. Other References/Discussion Threads
----------------------------------------------------------------------------
Bio Notes
---------
+=========
Let us discuss the changes in the context of how some overall goals for the
block layer are addressed.
1. Scope for tuning the generic logic to satisfy various requirements
+=====================================================================
The block layer design supports adaptable abstractions to handle common
processing with the ability to tune the logic to an appropriate extent
@@ -97,6 +107,7 @@ and application/middleware software designed to take advantage of these
capabilities.
1.1 Tuning based on low level device / driver capabilities
+----------------------------------------------------------
Sophisticated devices with large built-in caches, intelligent i/o scheduling
optimizations, high memory DMA support, etc may find some of the
@@ -133,12 +144,12 @@ Some new queue property settings:
Sets two variables that limit the size of the request.
- The request queue's max_sectors, which is a soft size in
- units of 512 byte sectors, and could be dynamically varied
- by the core kernel.
+ units of 512 byte sectors, and could be dynamically varied
+ by the core kernel.
- The request queue's max_hw_sectors, which is a hard limit
- and reflects the maximum size request a driver can handle
- in units of 512 byte sectors.
+ and reflects the maximum size request a driver can handle
+ in units of 512 byte sectors.
The default for both max_sectors and max_hw_sectors is
255. The upper limit of max_sectors is 1024.
@@ -234,6 +245,7 @@ I/O scheduler wrappers are to be used instead of accessing the queue directly.
See section 4. The I/O scheduler for details.
1.2 Tuning Based on High level code capabilities
+------------------------------------------------
i. Application capabilities for raw i/o
@@ -258,9 +270,11 @@ would need an additional mechanism either via open flags or ioctls, or some
other upper level mechanism to communicate such settings to block.
1.2.1 Request Priority/Latency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Todo/Under discussion:
-Arjan's proposed request priority scheme allows higher levels some broad
+Todo/Under discussion::
+
+ Arjan's proposed request priority scheme allows higher levels some broad
control (high/med/low) over the priority of an i/o request vs other pending
requests in the queue. For example it allows reads for bringing in an
executable page on demand to be given a higher priority over pending write
@@ -272,7 +286,9 @@ Arjan's proposed request priority scheme allows higher levels some broad
1.3 Direct Access to Low level Device/Driver Capabilities (Bypass mode)
- (e.g Diagnostics, Systems Management)
+-----------------------------------------------------------------------
+
+(e.g Diagnostics, Systems Management)
There are situations where high-level code needs to have direct access to
the low level device capabilities or requires the ability to issue commands
@@ -308,28 +324,32 @@ involved. In the latter case, the driver would modify and manage the
request->buffer, request->sector and request->nr_sectors or
request->current_nr_sectors fields itself rather than using the block layer
end_request or end_that_request_first completion interfaces.
-(See 2.3 or Documentation/block/request.txt for a brief explanation of
+(See 2.3 or Documentation/block/request.rst for a brief explanation of
the request structure fields)
-[TBD: end_that_request_last should be usable even in this case;
-Perhaps an end_that_direct_request_first routine could be implemented to make
-handling direct requests easier for such drivers; Also for drivers that
-expect bios, a helper function could be provided for setting up a bio
-corresponding to a data buffer]
+::
-<JENS: I dont understand the above, why is end_that_request_first() not
-usable? Or _last for that matter. I must be missing something>
-<SUP: What I meant here was that if the request doesn't have a bio, then
- end_that_request_first doesn't modify nr_sectors or current_nr_sectors,
- and hence can't be used for advancing request state settings on the
- completion of partial transfers. The driver has to modify these fields
- directly by hand.
- This is because end_that_request_first only iterates over the bio list,
- and always returns 0 if there are none associated with the request.
- _last works OK in this case, and is not a problem, as I mentioned earlier
->
+ [TBD: end_that_request_last should be usable even in this case;
+ Perhaps an end_that_direct_request_first routine could be implemented to make
+ handling direct requests easier for such drivers; Also for drivers that
+ expect bios, a helper function could be provided for setting up a bio
+ corresponding to a data buffer]
+
+ <JENS: I dont understand the above, why is end_that_request_first() not
+ usable? Or _last for that matter. I must be missing something>
+
+ <SUP: What I meant here was that if the request doesn't have a bio, then
+ end_that_request_first doesn't modify nr_sectors or current_nr_sectors,
+ and hence can't be used for advancing request state settings on the
+ completion of partial transfers. The driver has to modify these fields
+ directly by hand.
+ This is because end_that_request_first only iterates over the bio list,
+ and always returns 0 if there are none associated with the request.
+ _last works OK in this case, and is not a problem, as I mentioned earlier
+ >
1.3.1 Pre-built Commands
+^^^^^^^^^^^^^^^^^^^^^^^^
A request can be created with a pre-built custom command to be sent directly
to the device. The cmd block in the request structure has room for filling
@@ -360,9 +380,11 @@ Aside:
the pre-builder hook can be invoked there.
-2. Flexible and generic but minimalist i/o structure/descriptor.
+2. Flexible and generic but minimalist i/o structure/descriptor
+===============================================================
2.1 Reason for a new structure and requirements addressed
+---------------------------------------------------------
Prior to 2.5, buffer heads were used as the unit of i/o at the generic block
layer, and the low level request structure was associated with a chain of
@@ -378,26 +400,26 @@ which were generated for each such chunk.
The following were some of the goals and expectations considered in the
redesign of the block i/o data structure in 2.5.
-i. Should be appropriate as a descriptor for both raw and buffered i/o -
+1. Should be appropriate as a descriptor for both raw and buffered i/o -
avoid cache related fields which are irrelevant in the direct/page i/o path,
or filesystem block size alignment restrictions which may not be relevant
for raw i/o.
-ii. Ability to represent high-memory buffers (which do not have a virtual
+2. Ability to represent high-memory buffers (which do not have a virtual
address mapping in kernel address space).
-iii.Ability to represent large i/os w/o unnecessarily breaking them up (i.e
+3. Ability to represent large i/os w/o unnecessarily breaking them up (i.e
greater than PAGE_SIZE chunks in one shot)
-iv. At the same time, ability to retain independent identity of i/os from
+4. At the same time, ability to retain independent identity of i/os from
different sources or i/o units requiring individual completion (e.g. for
latency reasons)
-v. Ability to represent an i/o involving multiple physical memory segments
+5. Ability to represent an i/o involving multiple physical memory segments
(including non-page aligned page fragments, as specified via readv/writev)
without unnecessarily breaking it up, if the underlying device is capable of
handling it.
-vi. Preferably should be based on a memory descriptor structure that can be
+6. Preferably should be based on a memory descriptor structure that can be
passed around different types of subsystems or layers, maybe even
networking, without duplication or extra copies of data/descriptor fields
themselves in the process
-vii.Ability to handle the possibility of splits/merges as the structure passes
+7. Ability to handle the possibility of splits/merges as the structure passes
through layered drivers (lvm, md, evms), with minimal overhead.
The solution was to define a new structure (bio) for the block layer,
@@ -408,6 +430,7 @@ bh structure for buffered i/o, and in the case of raw/direct i/o kiobufs are
mapped to bio structures.
2.2 The bio struct
+------------------
The bio structure uses a vector representation pointing to an array of tuples
of <page, offset, len> to describe the i/o buffer, and has various other
@@ -417,16 +440,18 @@ performing the i/o.
Notice that this representation means that a bio has no virtual address
mapping at all (unlike buffer heads).
-struct bio_vec {
+::
+
+ struct bio_vec {
struct page *bv_page;
unsigned short bv_len;
unsigned short bv_offset;
-};
+ };
-/*
- * main unit of I/O for the block layer and lower layers (ie drivers)
- */
-struct bio {
+ /*
+ * main unit of I/O for the block layer and lower layers (ie drivers)
+ */
+ struct bio {
struct bio *bi_next; /* request queue link */
struct block_device *bi_bdev; /* target device */
unsigned long bi_flags; /* status, command, etc */
@@ -443,7 +468,7 @@ struct bio {
bio_end_io_t *bi_end_io; /* bi_end_io (bio) */
atomic_t bi_cnt; /* pin count: free when it hits zero */
void *bi_private;
-};
+ };
With this multipage bio design:
@@ -453,7 +478,7 @@ With this multipage bio design:
- Splitting of an i/o request across multiple devices (as in the case of
lvm or raid) is achieved by cloning the bio (where the clone points to
the same bi_io_vec array, but with the index and size accordingly modified)
-- A linked list of bios is used as before for unrelated merges (*) - this
+- A linked list of bios is used as before for unrelated merges [*]_ - this
avoids reallocs and makes independent completions easier to handle.
- Code that traverses the req list can find all the segments of a bio
by using rq_for_each_segment. This handles the fact that a request
@@ -462,10 +487,12 @@ With this multipage bio design:
field to keep track of the next bio_vec entry to process.
(e.g a 1MB bio_vec needs to be handled in max 128kB chunks for IDE)
[TBD: Should preferably also have a bi_voffset and bi_vlen to avoid modifying
- bi_offset an len fields]
+ bi_offset an len fields]
-(*) unrelated merges -- a request ends up containing two or more bios that
- didn't originate from the same place.
+.. [*]
+
+ unrelated merges -- a request ends up containing two or more bios that
+ didn't originate from the same place.
bi_end_io() i/o callback gets called on i/o completion of the entire bio.
@@ -483,10 +510,11 @@ which in turn means that only raw I/O uses it (direct i/o may not work
right now). The intent however is to enable clustering of pages etc to
become possible. The pagebuf abstraction layer from SGI also uses multi-page
bios, but that is currently not included in the stock development kernels.
-The same is true of Andrew Morton's work-in-progress multipage bio writeout
+The same is true of Andrew Morton's work-in-progress multipage bio writeout
and readahead patches.
2.3 Changes in the Request Structure
+------------------------------------
The request structure is the structure that gets passed down to low level
drivers. The block layer make_request function builds up a request structure,
@@ -499,11 +527,11 @@ request structure.
Only some relevant fields (mainly those which changed or may be referred
to in some of the discussion here) are listed below, not necessarily in
the order in which they occur in the structure (see include/linux/blkdev.h)
-Refer to Documentation/block/request.txt for details about all the request
+Refer to Documentation/block/request.rst for details about all the request
structure fields and a quick reference about the layers which are
-supposed to use or modify those fields.
+supposed to use or modify those fields::
-struct request {
+ struct request {
struct list_head queuelist; /* Not meant to be directly accessed by
the driver.
Used by q->elv_next_request_fn
@@ -548,11 +576,11 @@ struct request {
.
struct bio *bio, *biotail; /* bio list instead of bh */
struct request_list *rl;
-}
-
+ }
+
See the req_ops and req_flag_bits definitions for an explanation of the various
flags available. Some bits are used by the block layer or i/o scheduler.
-
+
The behaviour of the various sector counts are almost the same as before,
except that since we have multi-segment bios, current_nr_sectors refers
to the numbers of sectors in the current segment being processed which could
@@ -578,8 +606,10 @@ a driver needs to be careful about interoperation with the block layer helper
functions which the driver uses. (Section 1.3)
3. Using bios
+=============
3.1 Setup/Teardown
+------------------
There are routines for managing the allocation, and reference counting, and
freeing of bios (bio_alloc, bio_get, bio_put).
@@ -606,10 +636,13 @@ case of bio, these routines make use of the standard slab allocator.
The caller of bio_alloc is expected to taken certain steps to avoid
deadlocks, e.g. avoid trying to allocate more memory from the pool while
already holding memory obtained from the pool.
-[TBD: This is a potential issue, though a rare possibility
- in the bounce bio allocation that happens in the current code, since
- it ends up allocating a second bio from the same pool while
- holding the original bio ]
+
+::
+
+ [TBD: This is a potential issue, though a rare possibility
+ in the bounce bio allocation that happens in the current code, since
+ it ends up allocating a second bio from the same pool while
+ holding the original bio ]
Memory allocated from the pool should be released back within a limited
amount of time (in the case of bio, that would be after the i/o is completed).
@@ -635,14 +668,18 @@ same bio_vec_list). This would typically be used for splitting i/o requests
in lvm or md.
3.2 Generic bio helper Routines
+-------------------------------
3.2.1 Traversing segments and completion units in a request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The macro rq_for_each_segment() should be used for traversing the bios
in the request list (drivers should avoid directly trying to do it
themselves). Using these helpers should also make it easier to cope
with block changes in the future.
+::
+
struct req_iterator iter;
rq_for_each_segment(bio_vec, rq, iter)
/* bio_vec is now current segment */
@@ -653,6 +690,7 @@ which don't make a distinction between segments and completion units would
need to be reorganized to support multi-segment bios.
3.2.2 Setting up DMA scatterlists
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The blk_rq_map_sg() helper routine would be used for setting up scatter
gather lists from a request, so a driver need not do it on its own.
@@ -683,6 +721,7 @@ of physical data segments in a request (i.e. the largest sized scatter list
a driver could handle)
3.2.3 I/O completion
+^^^^^^^^^^^^^^^^^^^^
The existing generic block layer helper routines end_request,
end_that_request_first and end_that_request_last can be used for i/o
@@ -691,8 +730,10 @@ request can be kicked of) as before. With the introduction of multi-page
bio support, end_that_request_first requires an additional argument indicating
the number of sectors completed.
-3.2.4 Implications for drivers that do not interpret bios (don't handle
- multiple segments)
+3.2.4 Implications for drivers that do not interpret bios
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+(don't handle multiple segments)
Drivers that do not interpret bios e.g those which do not handle multiple
segments and do not support i/o into high memory addresses (require bounce
@@ -707,15 +748,18 @@ be used if only if the request has come down from block/bio path, not for
direct access requests which only specify rq->buffer without a valid rq->bio)
3.3 I/O Submission
+------------------
The routine submit_bio() is used to submit a single io. Higher level i/o
routines make use of this:
(a) Buffered i/o:
+
The routine submit_bh() invokes submit_bio() on a bio corresponding to the
bh, allocating the bio if required. ll_rw_block() uses submit_bh() as before.
(b) Kiobuf i/o (for raw/direct i/o):
+
The ll_rw_kio() routine breaks up the kiobuf into page sized chunks and
maps the array to one or more multi-page bios, issuing submit_bio() to
perform the i/o on each of these.
@@ -738,6 +782,7 @@ Todo/Observation:
(c) Page i/o:
+
Todo/Under discussion:
Andrew Morton's multi-page bio patches attempt to issue multi-page
@@ -753,6 +798,7 @@ Todo/Under discussion:
abstraction, but intended to be as lightweight as possible).
(d) Direct access i/o:
+
Direct access requests that do not contain bios would be submitted differently
as discussed earlier in section 1.3.
@@ -780,11 +826,13 @@ Aside:
4. The I/O scheduler
+====================
+
I/O scheduler, a.k.a. elevator, is implemented in two layers. Generic dispatch
queue and specific I/O schedulers. Unless stated otherwise, elevator is used
to refer to both parts and I/O scheduler to specific I/O schedulers.
-Block layer implements generic dispatch queue in block/*.c.
+Block layer implements generic dispatch queue in `block/*.c`.
The generic dispatch queue is responsible for requeueing, handling non-fs
requests and all other subtleties.
@@ -802,8 +850,11 @@ doesn't implement a function, the switch does nothing or some minimal house
keeping work.
4.1. I/O scheduler API
+----------------------
The functions an elevator may implement are: (* are mandatory)
+
+=============================== ================================================
elevator_merge_fn called to query requests for merge with a bio
elevator_merge_req_fn called when two requests get merged. the one
@@ -862,8 +913,11 @@ elevator_deactivate_req_fn Called when device driver decides to delay
elevator_init_fn*
elevator_exit_fn Allocate and free any elevator specific storage
for a queue.
+=============================== ================================================
4.2 Request flows seen by I/O schedulers
+----------------------------------------
+
All requests seen by I/O schedulers strictly follow one of the following three
flows.
@@ -877,9 +931,12 @@ flows.
-> put_req_fn
4.3 I/O scheduler implementation
+--------------------------------
+
The generic i/o scheduler algorithm attempts to sort/merge/batch requests for
optimal disk scan and request servicing performance (based on generic
principles and device capabilities), optimized for:
+
i. improved throughput
ii. improved latency
iii. better utilization of h/w & CPU time
@@ -933,15 +990,19 @@ Aside:
a big request from the broken up pieces coming by.
4.4 I/O contexts
+----------------
+
I/O contexts provide a dynamically allocated per process data area. They may
be used in I/O schedulers, and in the block layer (could be used for IO statis,
-priorities for example). See *io_context in block/ll_rw_blk.c, and as-iosched.c
+priorities for example). See `*io_context` in block/ll_rw_blk.c, and as-iosched.c
for an example of usage in an i/o scheduler.
5. Scalability related changes
+==============================
5.1 Granular Locking: io_request_lock replaced by a per-queue lock
+------------------------------------------------------------------
The global io_request_lock has been removed as of 2.5, to avoid
the scalability bottleneck it was causing, and has been replaced by more
@@ -956,20 +1017,23 @@ request_fn execution which it means that lots of older drivers
should still be SMP safe. Drivers are free to drop the queue
lock themselves, if required. Drivers that explicitly used the
io_request_lock for serialization need to be modified accordingly.
-Usually it's as easy as adding a global lock:
+Usually it's as easy as adding a global lock::
static DEFINE_SPINLOCK(my_driver_lock);
and passing the address to that lock to blk_init_queue().
5.2 64 bit sector numbers (sector_t prepares for 64 bit support)
+----------------------------------------------------------------
The sector number used in the bio structure has been changed to sector_t,
which could be defined as 64 bit in preparation for 64 bit sector support.
6. Other Changes/Implications
+=============================
6.1 Partition re-mapping handled by the generic block layer
+-----------------------------------------------------------
In 2.5 some of the gendisk/partition related code has been reorganized.
Now the generic block layer performs partition-remapping early and thus
@@ -984,6 +1048,7 @@ sent are offset from the beginning of the device.
7. A Few Tips on Migration of older drivers
+===========================================
Old-style drivers that just use CURRENT and ignores clustered requests,
may not need much change. The generic layer will automatically handle
@@ -1017,12 +1082,12 @@ blk_init_queue time.
Drivers no longer have to map a {partition, sector offset} into the
correct absolute location anymore, this is done by the block layer, so
-where a driver received a request ala this before:
+where a driver received a request ala this before::
rq->rq_dev = mk_kdev(3, 5); /* /dev/hda5 */
rq->sector = 0; /* first sector on hda5 */
- it will now see
+it will now see::
rq->rq_dev = mk_kdev(3, 0); /* /dev/hda */
rq->sector = 123128; /* offset from start of disk */
@@ -1039,38 +1104,65 @@ a bio into the virtual address space.
8. Prior/Related/Impacted patches
+=================================
8.1. Earlier kiobuf patches (sct/axboe/chait/hch/mkp)
+-----------------------------------------------------
+
- orig kiobuf & raw i/o patches (now in 2.4 tree)
- direct kiobuf based i/o to devices (no intermediate bh's)
- page i/o using kiobuf
- kiobuf splitting for lvm (mkp)
- elevator support for kiobuf request merging (axboe)
+
8.2. Zero-copy networking (Dave Miller)
+---------------------------------------
+
8.3. SGI XFS - pagebuf patches - use of kiobufs
+-----------------------------------------------
8.4. Multi-page pioent patch for bio (Christoph Hellwig)
+--------------------------------------------------------
8.5. Direct i/o implementation (Andrea Arcangeli) since 2.4.10-pre11
+--------------------------------------------------------------------
8.6. Async i/o implementation patch (Ben LaHaise)
+-------------------------------------------------
8.7. EVMS layering design (IBM EVMS team)
-8.8. Larger page cache size patch (Ben LaHaise) and
- Large page size (Daniel Phillips)
+-----------------------------------------
+8.8. Larger page cache size patch (Ben LaHaise) and Large page size (Daniel Phillips)
+-------------------------------------------------------------------------------------
+
=> larger contiguous physical memory buffers
+
8.9. VM reservations patch (Ben LaHaise)
+----------------------------------------
8.10. Write clustering patches ? (Marcelo/Quintela/Riel ?)
+----------------------------------------------------------
8.11. Block device in page cache patch (Andrea Archangeli) - now in 2.4.10+
-8.12. Multiple block-size transfers for faster raw i/o (Shailabh Nagar,
- Badari)
+---------------------------------------------------------------------------
+8.12. Multiple block-size transfers for faster raw i/o (Shailabh Nagar, Badari)
+-------------------------------------------------------------------------------
8.13 Priority based i/o scheduler - prepatches (Arjan van de Ven)
+------------------------------------------------------------------
8.14 IDE Taskfile i/o patch (Andre Hedrick)
+--------------------------------------------
8.15 Multi-page writeout and readahead patches (Andrew Morton)
+---------------------------------------------------------------
8.16 Direct i/o patches for 2.5 using kvec and bio (Badari Pulavarthy)
+-----------------------------------------------------------------------
-9. Other References:
+9. Other References
+===================
+
+9.1 The Splice I/O Model
+------------------------
+
+Larry McVoy (and subsequent discussions on lkml, and Linus' comments - Jan 2001
+
+9.2 Discussions about kiobuf and bh design
+------------------------------------------
+
+On lkml between sct, linus, alan et al - Feb-March 2001 (many of the
+initial thoughts that led to bio were brought up in this discussion thread)
-9.1 The Splice I/O Model - Larry McVoy (and subsequent discussions on lkml,
-and Linus' comments - Jan 2001)
-9.2 Discussions about kiobuf and bh design on lkml between sct, linus, alan
-et al - Feb-March 2001 (many of the initial thoughts that led to bio were
-brought up in this discussion thread)
9.3 Discussions on mempool on lkml - Dec 2001.
-
+----------------------------------------------
diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.rst
similarity index 92%
rename from Documentation/block/biovecs.txt
rename to Documentation/block/biovecs.rst
index ce6eccaf5df7..86fa66c87172 100644
--- a/Documentation/block/biovecs.txt
+++ b/Documentation/block/biovecs.rst
@@ -1,6 +1,6 @@
-
-Immutable biovecs and biovec iterators:
-=======================================
+======================================
+Immutable biovecs and biovec iterators
+======================================
Kent Overstreet <kmo@daterainc.com>
@@ -121,10 +121,12 @@ Other implications:
Usage of helpers:
=================
-* The following helpers whose names have the suffix of "_all" can only be used
-on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
-shouldn't use them because the bio may have been split before it reached the
-driver.
+* The following helpers whose names have the suffix of `_all` can only be used
+ on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
+ shouldn't use them because the bio may have been split before it reached the
+ driver.
+
+::
bio_for_each_segment_all()
bio_first_bvec_all()
@@ -132,13 +134,13 @@ driver.
bio_last_bvec_all()
* The following helpers iterate over single-page segment. The passed 'struct
-bio_vec' will contain a single-page IO vector during the iteration
+ bio_vec' will contain a single-page IO vector during the iteration::
bio_for_each_segment()
bio_for_each_segment_all()
* The following helpers iterate over multi-page bvec. The passed 'struct
-bio_vec' will contain a multi-page IO vector during the iteration
+ bio_vec' will contain a multi-page IO vector during the iteration::
bio_for_each_bvec()
rq_for_each_bvec()
diff --git a/Documentation/block/capability.rst b/Documentation/block/capability.rst
new file mode 100644
index 000000000000..2cf258d64bbe
--- /dev/null
+++ b/Documentation/block/capability.rst
@@ -0,0 +1,18 @@
+===============================
+Generic Block Device Capability
+===============================
+
+This file documents the sysfs file block/<disk>/capability
+
+capability is a hex word indicating which capabilities a specific disk
+supports. For more information on bits not listed here, see
+include/linux/genhd.h
+
+GENHD_FL_MEDIA_CHANGE_NOTIFY
+----------------------------
+
+Value: 4
+
+When this bit is set, the disk supports Asynchronous Notification
+of media change events. These events will be broadcast to user
+space via kernel uevent.
diff --git a/Documentation/block/capability.txt b/Documentation/block/capability.txt
deleted file mode 100644
index 2f1729424ef4..000000000000
--- a/Documentation/block/capability.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-Generic Block Device Capability
-===============================================================================
-This file documents the sysfs file block/<disk>/capability
-
-capability is a hex word indicating which capabilities a specific disk
-supports. For more information on bits not listed here, see
-include/linux/genhd.h
-
-Capability Value
--------------------------------------------------------------------------------
-GENHD_FL_MEDIA_CHANGE_NOTIFY 4
- When this bit is set, the disk supports Asynchronous Notification
- of media change events. These events will be broadcast to user
- space via kernel uevent.
-
diff --git a/Documentation/block/cmdline-partition.txt b/Documentation/block/cmdline-partition.rst
similarity index 92%
rename from Documentation/block/cmdline-partition.txt
rename to Documentation/block/cmdline-partition.rst
index 760a3f7c3ed4..530bedff548a 100644
--- a/Documentation/block/cmdline-partition.txt
+++ b/Documentation/block/cmdline-partition.rst
@@ -1,5 +1,6 @@
+==============================================
Embedded device command line partition parsing
-=====================================================================
+==============================================
The "blkdevparts" command line option adds support for reading the
block device partition table from the kernel command line.
@@ -22,12 +23,15 @@ blkdevparts=<blkdev-def>[;<blkdev-def>]
<size>
partition size, in bytes, such as: 512, 1m, 1G.
size may contain an optional suffix of (upper or lower case):
+
K, M, G, T, P, E.
+
"-" is used to denote all remaining space.
<offset>
partition start address, in bytes.
offset may contain an optional suffix of (upper or lower case):
+
K, M, G, T, P, E.
(part-name)
@@ -36,11 +40,14 @@ blkdevparts=<blkdev-def>[;<blkdev-def>]
User space application can access partition by partition name.
Example:
+
eMMC disk names are "mmcblk0" and "mmcblk0boot0".
- bootargs:
+ bootargs::
+
'blkdevparts=mmcblk0:1G(data0),1G(data1),-;mmcblk0boot0:1m(boot),-(kernel)'
- dmesg:
+ dmesg::
+
mmcblk0: p1(data0) p2(data1) p3()
mmcblk0boot0: p1(boot) p2(kernel)
diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.rst
similarity index 91%
rename from Documentation/block/data-integrity.txt
rename to Documentation/block/data-integrity.rst
index 934c44ea0c57..4f2452a95c43 100644
--- a/Documentation/block/data-integrity.txt
+++ b/Documentation/block/data-integrity.rst
@@ -1,5 +1,9 @@
-----------------------------------------------------------------------
-1. INTRODUCTION
+==============
+Data Integrity
+==============
+
+1. Introduction
+===============
Modern filesystems feature checksumming of data and metadata to
protect against data corruption. However, the detection of the
@@ -28,8 +32,8 @@ integrity of the I/O and reject it if corruption is detected. This
allows not only corruption prevention but also isolation of the point
of failure.
-----------------------------------------------------------------------
-2. THE DATA INTEGRITY EXTENSIONS
+2. The Data Integrity Extensions
+================================
As written, the protocol extensions only protect the path between
controller and storage device. However, many controllers actually
@@ -75,8 +79,8 @@ Extensions. As these extensions are outside the scope of the protocol
bodies (T10, T13), Oracle and its partners are trying to standardize
them within the Storage Networking Industry Association.
-----------------------------------------------------------------------
-3. KERNEL CHANGES
+3. Kernel Changes
+=================
The data integrity framework in Linux enables protection information
to be pinned to I/Os and sent to/received from controllers that
@@ -123,10 +127,11 @@ access to manipulate the tags from user space. A passthrough
interface for this is being worked on.
-----------------------------------------------------------------------
-4. BLOCK LAYER IMPLEMENTATION DETAILS
+4. Block Layer Implementation Details
+=====================================
-4.1 BIO
+4.1 Bio
+-------
The data integrity patches add a new field to struct bio when
CONFIG_BLK_DEV_INTEGRITY is enabled. bio_integrity(bio) returns a
@@ -145,7 +150,8 @@ attached using bio_integrity_add_page().
bio_free() will automatically free the bip.
-4.2 BLOCK DEVICE
+4.2 Block Device
+----------------
Because the format of the protection data is tied to the physical
disk, each block device has been extended with a block integrity
@@ -163,10 +169,11 @@ and MD linear, RAID0 and RAID1 are currently supported. RAID4/5/6
will require extra work due to the application tag.
-----------------------------------------------------------------------
-5.0 BLOCK LAYER INTEGRITY API
+5.0 Block Layer Integrity API
+=============================
-5.1 NORMAL FILESYSTEM
+5.1 Normal Filesystem
+---------------------
The normal filesystem is unaware that the underlying block device
is capable of sending/receiving integrity metadata. The IMD will
@@ -174,25 +181,26 @@ will require extra work due to the application tag.
in case of a WRITE. A READ request will cause the I/O integrity
to be verified upon completion.
- IMD generation and verification can be toggled using the
+ IMD generation and verification can be toggled using the::
/sys/block/<bdev>/integrity/write_generate
- and
+ and::
/sys/block/<bdev>/integrity/read_verify
flags.
-5.2 INTEGRITY-AWARE FILESYSTEM
+5.2 Integrity-Aware Filesystem
+------------------------------
A filesystem that is integrity-aware can prepare I/Os with IMD
attached. It can also use the application tag space if this is
supported by the block device.
- bool bio_integrity_prep(bio);
+ `bool bio_integrity_prep(bio);`
To generate IMD for WRITE and to set up buffers for READ, the
filesystem must call bio_integrity_prep(bio).
@@ -204,14 +212,15 @@ will require extra work due to the application tag.
Complete bio with error if prepare failed for some reson.
-5.3 PASSING EXISTING INTEGRITY METADATA
+5.3 Passing Existing Integrity Metadata
+---------------------------------------
Filesystems that either generate their own integrity metadata or
are capable of transferring IMD from user space can use the
following calls:
- struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);
+ `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
Allocates the bio integrity payload and hangs it off of the bio.
nr_pages indicate how many pages of protection data need to be
@@ -220,7 +229,7 @@ will require extra work due to the application tag.
The integrity payload will be freed at bio_free() time.
- int bio_integrity_add_page(bio, page, len, offset);
+ `int bio_integrity_add_page(bio, page, len, offset);`
Attaches a page containing integrity metadata to an existing
bio. The bio must have an existing bip,
@@ -241,21 +250,21 @@ will require extra work due to the application tag.
integrity upon completion.
-5.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY
- METADATA
+5.4 Registering A Block Device As Capable Of Exchanging Integrity Metadata
+--------------------------------------------------------------------------
To enable integrity exchange on a block device the gendisk must be
registered as capable:
- int blk_integrity_register(gendisk, blk_integrity);
+ `int blk_integrity_register(gendisk, blk_integrity);`
The blk_integrity struct is a template and should contain the
- following:
+ following::
static struct blk_integrity my_profile = {
.name = "STANDARDSBODY-TYPE-VARIANT-CSUM",
.generate_fn = my_generate_fn,
- .verify_fn = my_verify_fn,
+ .verify_fn = my_verify_fn,
.tuple_size = sizeof(struct my_tuple_size),
.tag_size = <tag bytes per hw sector>,
};
@@ -278,4 +287,5 @@ will require extra work due to the application tag.
0 depending on the value of the Control Mode Page ATO bit.
----------------------------------------------------------------------
+
2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>
diff --git a/Documentation/block/deadline-iosched.txt b/Documentation/block/deadline-iosched.rst
similarity index 89%
rename from Documentation/block/deadline-iosched.txt
rename to Documentation/block/deadline-iosched.rst
index 2d82c80322cb..9f5c5a4c370e 100644
--- a/Documentation/block/deadline-iosched.txt
+++ b/Documentation/block/deadline-iosched.rst
@@ -1,3 +1,4 @@
+==============================
Deadline IO scheduler tunables
==============================
@@ -7,15 +8,13 @@ of interest to power users.
Selecting IO schedulers
-----------------------
-Refer to Documentation/block/switching-sched.txt for information on
+Refer to Documentation/block/switching-sched.rst for information on
selecting an io scheduler on a per-device basis.
-
-********************************************************************************
-
+------------------------------------------------------------------------------
read_expire (in ms)
------------
+-----------------------
The goal of the deadline io scheduler is to attempt to guarantee a start
service time for a request. As we focus mainly on read latencies, this is
@@ -25,15 +24,15 @@ milliseconds.
write_expire (in ms)
------------
+-----------------------
Similar to read_expire mentioned above, but for writes.
fifo_batch (number of requests)
-----------
+------------------------------------
-Requests are grouped into ``batches'' of a particular data direction (read or
+Requests are grouped into ``batches`` of a particular data direction (read or
write) which are serviced in increasing sector order. To limit extra seeking,
deadline expiries are only checked between batches. fifo_batch controls the
maximum number of requests per batch.
@@ -45,7 +44,7 @@ generally improves throughput, at the cost of latency variation.
writes_starved (number of dispatches)
---------------
+--------------------------------------
When we have to move requests from the io scheduler queue to the block
device dispatch queue, we always give a preference to reads. However, we
@@ -56,7 +55,7 @@ same criteria as reads.
front_merges (bool)
-------------
+----------------------
Sometimes it happens that a request enters the io scheduler that is contiguous
with a request that is already on the queue. Either it fits in the back of that
@@ -71,5 +70,3 @@ rbtree front sector lookup when the io scheduler merge function is called.
Nov 11 2002, Jens Axboe <jens.axboe@oracle.com>
-
-
diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst
new file mode 100644
index 000000000000..8cd226a0e86e
--- /dev/null
+++ b/Documentation/block/index.rst
@@ -0,0 +1,25 @@
+:orphan:
+
+=====
+Block
+=====
+
+.. toctree::
+ :maxdepth: 1
+
+ bfq-iosched
+ biodoc
+ biovecs
+ capability
+ cmdline-partition
+ data-integrity
+ deadline-iosched
+ ioprio
+ kyber-iosched
+ null_blk
+ pr
+ queue-sysfs
+ request
+ stat
+ switching-sched
+ writeback_cache_control
diff --git a/Documentation/block/ioprio.txt b/Documentation/block/ioprio.rst
similarity index 75%
rename from Documentation/block/ioprio.txt
rename to Documentation/block/ioprio.rst
index 8ed8c59380b4..f72b0de65af7 100644
--- a/Documentation/block/ioprio.txt
+++ b/Documentation/block/ioprio.rst
@@ -1,3 +1,4 @@
+===================
Block io priorities
===================
@@ -40,81 +41,81 @@ class data, since it doesn't really apply here.
Tools
-----
-See below for a sample ionice tool. Usage:
+See below for a sample ionice tool. Usage::
-# ionice -c<class> -n<level> -p<pid>
+ # ionice -c<class> -n<level> -p<pid>
If pid isn't given, the current process is assumed. IO priority settings
are inherited on fork, so you can use ionice to start the process at a given
-level:
+level::
-# ionice -c2 -n0 /bin/ls
+ # ionice -c2 -n0 /bin/ls
will run ls at the best-effort scheduling class at the highest priority.
-For a running process, you can give the pid instead:
+For a running process, you can give the pid instead::
-# ionice -c1 -n2 -p100
+ # ionice -c1 -n2 -p100
will change pid 100 to run at the realtime scheduling class, at priority 2.
----> snip ionice.c tool <---
+ionice.c tool::
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <getopt.h>
-#include <unistd.h>
-#include <sys/ptrace.h>
-#include <asm/unistd.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <errno.h>
+ #include <getopt.h>
+ #include <unistd.h>
+ #include <sys/ptrace.h>
+ #include <asm/unistd.h>
-extern int sys_ioprio_set(int, int, int);
-extern int sys_ioprio_get(int, int);
+ extern int sys_ioprio_set(int, int, int);
+ extern int sys_ioprio_get(int, int);
-#if defined(__i386__)
-#define __NR_ioprio_set 289
-#define __NR_ioprio_get 290
-#elif defined(__ppc__)
-#define __NR_ioprio_set 273
-#define __NR_ioprio_get 274
-#elif defined(__x86_64__)
-#define __NR_ioprio_set 251
-#define __NR_ioprio_get 252
-#elif defined(__ia64__)
-#define __NR_ioprio_set 1274
-#define __NR_ioprio_get 1275
-#else
-#error "Unsupported arch"
-#endif
+ #if defined(__i386__)
+ #define __NR_ioprio_set 289
+ #define __NR_ioprio_get 290
+ #elif defined(__ppc__)
+ #define __NR_ioprio_set 273
+ #define __NR_ioprio_get 274
+ #elif defined(__x86_64__)
+ #define __NR_ioprio_set 251
+ #define __NR_ioprio_get 252
+ #elif defined(__ia64__)
+ #define __NR_ioprio_set 1274
+ #define __NR_ioprio_get 1275
+ #else
+ #error "Unsupported arch"
+ #endif
-static inline int ioprio_set(int which, int who, int ioprio)
-{
+ static inline int ioprio_set(int which, int who, int ioprio)
+ {
return syscall(__NR_ioprio_set, which, who, ioprio);
-}
+ }
-static inline int ioprio_get(int which, int who)
-{
+ static inline int ioprio_get(int which, int who)
+ {
return syscall(__NR_ioprio_get, which, who);
-}
+ }
-enum {
+ enum {
IOPRIO_CLASS_NONE,
IOPRIO_CLASS_RT,
IOPRIO_CLASS_BE,
IOPRIO_CLASS_IDLE,
-};
+ };
-enum {
+ enum {
IOPRIO_WHO_PROCESS = 1,
IOPRIO_WHO_PGRP,
IOPRIO_WHO_USER,
-};
+ };
-#define IOPRIO_CLASS_SHIFT 13
+ #define IOPRIO_CLASS_SHIFT 13
-const char *to_prio[] = { "none", "realtime", "best-effort", "idle", };
+ const char *to_prio[] = { "none", "realtime", "best-effort", "idle", };
-int main(int argc, char *argv[])
-{
+ int main(int argc, char *argv[])
+ {
int ioprio = 4, set = 0, ioprio_class = IOPRIO_CLASS_BE;
int c, pid = 0;
@@ -175,9 +176,7 @@ int main(int argc, char *argv[])
}
return 0;
-}
-
----> snip ionice.c tool <---
+ }
March 11 2005, Jens Axboe <jens.axboe@oracle.com>
diff --git a/Documentation/block/kyber-iosched.txt b/Documentation/block/kyber-iosched.rst
similarity index 86%
rename from Documentation/block/kyber-iosched.txt
rename to Documentation/block/kyber-iosched.rst
index e94feacd7edc..3e164dd0617c 100644
--- a/Documentation/block/kyber-iosched.txt
+++ b/Documentation/block/kyber-iosched.rst
@@ -1,5 +1,6 @@
+============================
Kyber I/O scheduler tunables
-===========================
+============================
The only two tunables for the Kyber scheduler are the target latencies for
reads and synchronous writes. Kyber will throttle requests in order to meet
diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.rst
similarity index 60%
rename from Documentation/block/null_blk.txt
rename to Documentation/block/null_blk.rst
index 41f0a3d33bbd..31451d80783c 100644
--- a/Documentation/block/null_blk.txt
+++ b/Documentation/block/null_blk.rst
@@ -1,33 +1,43 @@
+========================
Null block device driver
-================================================================================
+========================
-I. Overview
+1. Overview
+===========
The null block device (/dev/nullb*) is used for benchmarking the various
block-layer implementations. It emulates a block device of X gigabytes in size.
The following instances are possible:
Single-queue block-layer
+
- Request-based.
- Single submission queue per device.
- Implements IO scheduling algorithms (CFQ, Deadline, noop).
+
Multi-queue block-layer
+
- Request-based.
- Configurable submission queues per device.
+
No block-layer (Known as bio-based)
+
- Bio-based. IO requests are submitted directly to the device driver.
- Directly accepts bio data structure and returns them.
All of them have a completion queue for each core in the system.
-II. Module parameters applicable for all instances:
+2. Module parameters applicable for all instances
+=================================================
queue_mode=[0-2]: Default: 2-Multi-queue
Selects which block-layer the module should instantiate with.
- 0: Bio-based.
- 1: Single-queue.
- 2: Multi-queue.
+ = ============
+ 0 Bio-based
+ 1 Single-queue
+ 2 Multi-queue
+ = ============
home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
Selects what CPU node the data structures are allocated from.
@@ -45,12 +55,14 @@ nr_devices=[Number of devices]: Default: 1
irqmode=[0-2]: Default: 1-Soft-irq
The completion mode used for completing IOs to the block-layer.
- 0: None.
- 1: Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
+ = ===========================================================================
+ 0 None.
+ 1 Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
when IOs are issued from another CPU node than the home the device is
connected to.
- 2: Timer: Waits a specific period (completion_nsec) for each IO before
+ 2 Timer: Waits a specific period (completion_nsec) for each IO before
completion.
+ = ===========================================================================
completion_nsec=[ns]: Default: 10,000ns
Combined with irqmode=2 (timer). The time each completion event must wait.
@@ -66,30 +78,45 @@ hw_queue_depth=[0..qdepth]: Default: 64
III: Multi-queue specific parameters
use_per_node_hctx=[0/1]: Default: 0
- 0: The number of submit queues are set to the value of the submit_queues
+
+ = =====================================================================
+ 0 The number of submit queues are set to the value of the submit_queues
parameter.
- 1: The multi-queue block layer is instantiated with a hardware dispatch
+ 1 The multi-queue block layer is instantiated with a hardware dispatch
queue for each CPU node in the system.
+ = =====================================================================
no_sched=[0/1]: Default: 0
- 0: nullb* use default blk-mq io scheduler.
- 1: nullb* doesn't use io scheduler.
+
+ = ======================================
+ 0 nullb* use default blk-mq io scheduler
+ 1 nullb* doesn't use io scheduler
+ = ======================================
blocking=[0/1]: Default: 0
- 0: Register as a non-blocking blk-mq driver device.
- 1: Register as a blocking blk-mq driver device, null_blk will set
+
+ = ===============================================================
+ 0 Register as a non-blocking blk-mq driver device.
+ 1 Register as a blocking blk-mq driver device, null_blk will set
the BLK_MQ_F_BLOCKING flag, indicating that it sometimes/always
needs to block in its ->queue_rq() function.
+ = ===============================================================
shared_tags=[0/1]: Default: 0
- 0: Tag set is not shared.
- 1: Tag set shared between devices for blk-mq. Only makes sense with
+
+ = ================================================================
+ 0 Tag set is not shared.
+ 1 Tag set shared between devices for blk-mq. Only makes sense with
nr_devices > 1, otherwise there's no tag set to share.
+ = ================================================================
zoned=[0/1]: Default: 0
- 0: Block device is exposed as a random-access block device.
- 1: Block device is exposed as a host-managed zoned block device. Requires
+
+ = ======================================================================
+ 0 Block device is exposed as a random-access block device.
+ 1 Block device is exposed as a host-managed zoned block device. Requires
CONFIG_BLK_DEV_ZONED.
+ = ======================================================================
zone_size=[MB]: Default: 256
Per zone size when exposed as a zoned block device. Must be a power of two.
diff --git a/Documentation/block/pr.txt b/Documentation/block/pr.rst
similarity index 93%
rename from Documentation/block/pr.txt
rename to Documentation/block/pr.rst
index ac9b8e70e64b..30ea1c2e39eb 100644
--- a/Documentation/block/pr.txt
+++ b/Documentation/block/pr.rst
@@ -1,4 +1,4 @@
-
+===============================================
Block layer support for Persistent Reservations
===============================================
@@ -23,22 +23,18 @@ The following types of reservations are supported:
--------------------------------------------------
- PR_WRITE_EXCLUSIVE
-
Only the initiator that owns the reservation can write to the
device. Any initiator can read from the device.
- PR_EXCLUSIVE_ACCESS
-
Only the initiator that owns the reservation can access the
device.
- PR_WRITE_EXCLUSIVE_REG_ONLY
-
Only initiators with a registered key can write to the device,
Any initiator can read from the device.
- PR_EXCLUSIVE_ACCESS_REG_ONLY
-
Only initiators with a registered key can access the device.
- PR_WRITE_EXCLUSIVE_ALL_REGS
@@ -48,21 +44,21 @@ The following types of reservations are supported:
All initiators with a registered key are considered reservation
holders.
Please reference the SPC spec on the meaning of a reservation
- holder if you want to use this type.
+ holder if you want to use this type.
- PR_EXCLUSIVE_ACCESS_ALL_REGS
-
Only initiators with a registered key can access the device.
All initiators with a registered key are considered reservation
holders.
Please reference the SPC spec on the meaning of a reservation
- holder if you want to use this type.
+ holder if you want to use this type.
The following ioctl are supported:
----------------------------------
1. IOC_PR_REGISTER
+^^^^^^^^^^^^^^^^^^
This ioctl command registers a new reservation if the new_key argument
is non-null. If no existing reservation exists old_key must be zero,
@@ -74,6 +70,7 @@ in old_key.
2. IOC_PR_RESERVE
+^^^^^^^^^^^^^^^^^
This ioctl command reserves the device and thus restricts access for other
devices based on the type argument. The key argument must be the existing
@@ -82,12 +79,14 @@ IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
3. IOC_PR_RELEASE
+^^^^^^^^^^^^^^^^^
This ioctl command releases the reservation specified by key and flags
and thus removes any access restriction implied by it.
4. IOC_PR_PREEMPT
+^^^^^^^^^^^^^^^^^
This ioctl command releases the existing reservation referred to by
old_key and replaces it with a new reservation of type for the
@@ -95,11 +94,13 @@ reservation key new_key.
5. IOC_PR_PREEMPT_ABORT
+^^^^^^^^^^^^^^^^^^^^^^^
This ioctl command works like IOC_PR_PREEMPT except that it also aborts
any outstanding command sent over a connection identified by old_key.
6. IOC_PR_CLEAR
+^^^^^^^^^^^^^^^
This ioctl command unregisters both key and any other reservation key
registered with the device and drops any existing reservation.
@@ -111,7 +112,6 @@ Flags
All the ioctls have a flag field. Currently only one flag is supported:
- PR_FL_IGNORE_KEY
-
Ignore the existing reservation key. This is commonly supported for
IOC_PR_REGISTER, and some implementation may support the flag for
IOC_PR_RESERVE.
diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.rst
similarity index 99%
rename from Documentation/block/queue-sysfs.txt
rename to Documentation/block/queue-sysfs.rst
index 83b457e24bba..9022249208b5 100644
--- a/Documentation/block/queue-sysfs.txt
+++ b/Documentation/block/queue-sysfs.rst
@@ -1,3 +1,4 @@
+=================
Queue sysfs files
=================
@@ -10,7 +11,7 @@ Files denoted with a RO postfix are readonly and the RW postfix means
read-write.
add_random (RW)
-----------------
+---------------
This file allows to turn off the disk entropy contribution. Default
value of this file is '1'(on).
@@ -21,13 +22,13 @@ used by CPU-addressable storage to bypass the pagecache. It shows '1'
if true, '0' if not.
discard_granularity (RO)
------------------------
+------------------------
This shows the size of internal allocation of the device in bytes, if
reported by the device. A value of '0' means device does not support
the discard functionality.
discard_max_hw_bytes (RO)
-----------------------
+-------------------------
Devices that support discard functionality may have internal limits on
the number of bytes that can be trimmed or unmapped in a single operation.
The discard_max_bytes parameter is set by the device driver to the maximum
diff --git a/Documentation/block/request.txt b/Documentation/block/request.rst
similarity index 59%
rename from Documentation/block/request.txt
rename to Documentation/block/request.rst
index 754e104ed369..747021e1ffdb 100644
--- a/Documentation/block/request.txt
+++ b/Documentation/block/request.rst
@@ -1,26 +1,37 @@
-
+============================
struct request documentation
+============================
Jens Axboe <jens.axboe@oracle.com> 27/05/02
-1.0
-Index
-2.0 Struct request members classification
+.. FIXME:
+ No idea about what does mean - seems just some noise, so comment it
- 2.1 struct request members explanation
+ 1.0
+ Index
+
+ 2.0 Struct request members classification
+
+ 2.1 struct request members explanation
+
+ 3.0
+
+
+ 2.0
-3.0
-2.0
Short explanation of request members
+====================================
Classification flags:
+ = ====================
D driver member
B block layer member
I I/O scheduler member
+ = ====================
Unless an entry contains a D classification, a device driver must not access
this member. Some members may contain D classifications, but should only be
@@ -28,14 +39,13 @@ access through certain macros or functions (eg ->flags).
<linux/blkdev.h>
-2.1
+=============================== ======= =======================================
Member Flag Comment
------- ---- -------
-
+=============================== ======= =======================================
struct list_head queuelist BI Organization on various internal
queues
-void *elevator_private I I/O scheduler private data
+``void *elevator_private`` I I/O scheduler private data
unsigned char cmd[16] D Driver can use this for setting up
a cdb before execution, see
@@ -71,18 +81,19 @@ unsigned int hard_cur_sectors B Used to keep current_nr_sectors sane
int tag DB TCQ tag, if assigned
-void *special D Free to be used by driver
+``void *special`` D Free to be used by driver
-char *buffer D Map of first segment, also see
+``char *buffer`` D Map of first segment, also see
section on bouncing SECTION
-struct completion *waiting D Can be used by driver to get signalled
+``struct completion *waiting`` D Can be used by driver to get signalled
on request completion
-struct bio *bio DBI First bio in request
+``struct bio *bio`` DBI First bio in request
-struct bio *biotail DBI Last bio in request
+``struct bio *biotail`` DBI Last bio in request
-struct request_queue *q DB Request queue this request belongs to
+``struct request_queue *q`` DB Request queue this request belongs to
-struct request_list *rl B Request list this request came from
+``struct request_list *rl`` B Request list this request came from
+=============================== ======= =======================================
diff --git a/Documentation/block/stat.txt b/Documentation/block/stat.rst
similarity index 89%
rename from Documentation/block/stat.txt
rename to Documentation/block/stat.rst
index 0aace9cc536c..9c07bc22b0bc 100644
--- a/Documentation/block/stat.txt
+++ b/Documentation/block/stat.rst
@@ -1,3 +1,4 @@
+===============================================
Block layer statistics in /sys/block/<dev>/stat
===============================================
@@ -6,9 +7,12 @@ This file documents the contents of the /sys/block/<dev>/stat file.
The stat file provides several statistics about the state of block
device <dev>.
-Q. Why are there multiple statistics in a single file? Doesn't sysfs
+Q.
+ Why are there multiple statistics in a single file? Doesn't sysfs
normally contain a single value per file?
-A. By having a single file, the kernel can guarantee that the statistics
+
+A.
+ By having a single file, the kernel can guarantee that the statistics
represent a consistent snapshot of the state of the device. If the
statistics were exported as multiple files containing one statistic
each, it would be impossible to guarantee that a set of readings
@@ -18,8 +22,10 @@ The stat file consists of a single line of text containing 11 decimal
values separated by whitespace. The fields are summarized in the
following table, and described in more detail below.
+
+=============== ============= =================================================
Name units description
----- ----- -----------
+=============== ============= =================================================
read I/Os requests number of read I/Os processed
read merges requests number of read I/Os merged with in-queue I/O
read sectors sectors number of sectors read
@@ -35,6 +41,7 @@ discard I/Os requests number of discard I/Os processed
discard merges requests number of discard I/Os merged with in-queue I/O
discard sectors sectors number of sectors discarded
discard ticks milliseconds total wait time for discard requests
+=============== ============= =================================================
read I/Os, write I/Os, discard I/0s
===================================
diff --git a/Documentation/block/switching-sched.txt b/Documentation/block/switching-sched.rst
similarity index 67%
rename from Documentation/block/switching-sched.txt
rename to Documentation/block/switching-sched.rst
index 7977f6fb8b20..42042417380e 100644
--- a/Documentation/block/switching-sched.txt
+++ b/Documentation/block/switching-sched.rst
@@ -1,35 +1,39 @@
+===================
+Switching Scheduler
+===================
+
To choose IO schedulers at boot time, use the argument 'elevator=deadline'.
'noop' and 'cfq' (the default) are also available. IO schedulers are assigned
globally at boot time only presently.
Each io queue has a set of io scheduler tunables associated with it. These
tunables control how the io scheduler works. You can find these entries
-in:
+in::
-/sys/block/<device>/queue/iosched
+ /sys/block/<device>/queue/iosched
assuming that you have sysfs mounted on /sys. If you don't have sysfs mounted,
-you can do so by typing:
+you can do so by typing::
-# mount none /sys -t sysfs
+ # mount none /sys -t sysfs
It is possible to change the IO scheduler for a given block device on
the fly to select one of mq-deadline, none, bfq, or kyber schedulers -
which can improve that device's throughput.
-To set a specific scheduler, simply do this:
+To set a specific scheduler, simply do this::
-echo SCHEDNAME > /sys/block/DEV/queue/scheduler
+ echo SCHEDNAME > /sys/block/DEV/queue/scheduler
where SCHEDNAME is the name of a defined IO scheduler, and DEV is the
device name (hda, hdb, sga, or whatever you happen to have).
The list of defined schedulers can be found by simply doing
a "cat /sys/block/DEV/queue/scheduler" - the list of valid names
-will be displayed, with the currently selected scheduler in brackets:
+will be displayed, with the currently selected scheduler in brackets::
-# cat /sys/block/sda/queue/scheduler
-[mq-deadline] kyber bfq none
-# echo none >/sys/block/sda/queue/scheduler
-# cat /sys/block/sda/queue/scheduler
-[none] mq-deadline kyber bfq
+ # cat /sys/block/sda/queue/scheduler
+ [mq-deadline] kyber bfq none
+ # echo none >/sys/block/sda/queue/scheduler
+ # cat /sys/block/sda/queue/scheduler
+ [none] mq-deadline kyber bfq
diff --git a/Documentation/block/writeback_cache_control.txt b/Documentation/block/writeback_cache_control.rst
similarity index 94%
rename from Documentation/block/writeback_cache_control.txt
rename to Documentation/block/writeback_cache_control.rst
index 8a6bdada5f6b..2c752c57c14c 100644
--- a/Documentation/block/writeback_cache_control.txt
+++ b/Documentation/block/writeback_cache_control.rst
@@ -1,6 +1,6 @@
-
+==========================================
Explicit volatile write back cache control
-=====================================
+==========================================
Introduction
------------
@@ -31,7 +31,7 @@ the blkdev_issue_flush() helper for a pure cache flush.
Forced Unit Access
------------------
+------------------
The REQ_FUA flag can be OR ed into the r/w flags of a bio submitted from the
filesystem and will make sure that I/O completion for this request is only
@@ -62,14 +62,14 @@ flags themselves without any help from the block layer.
Implementation details for request_fn based block drivers
---------------------------------------------------------------
+---------------------------------------------------------
For devices that do not support volatile write caches there is no driver
support required, the block layer completes empty REQ_PREFLUSH requests before
entering the driver and strips off the REQ_PREFLUSH and REQ_FUA bits from
requests that have a payload. For devices with volatile write caches the
driver needs to tell the block layer that it supports flushing caches by
-doing:
+doing::
blk_queue_write_cache(sdkp->disk->queue, true, false);
@@ -77,7 +77,7 @@ and handle empty REQ_OP_FLUSH requests in its prep_fn/request_fn. Note that
REQ_PREFLUSH requests with a payload are automatically turned into a sequence
of an empty REQ_OP_FLUSH request followed by the actual write by the block
layer. For devices that also support the FUA bit the block layer needs
-to be told to pass through the REQ_FUA bit using:
+to be told to pass through the REQ_FUA bit using::
blk_queue_write_cache(sdkp->disk->queue, true, true);
diff --git a/Documentation/blockdev/zram.rst b/Documentation/blockdev/zram.rst
index 2111231c9c0f..6eccf13219ff 100644
--- a/Documentation/blockdev/zram.rst
+++ b/Documentation/blockdev/zram.rst
@@ -215,7 +215,7 @@ User space is advised to use the following files to read the device statistics.
File /sys/block/zram<id>/stat
-Represents block layer statistics. Read Documentation/block/stat.txt for
+Represents block layer statistics. Read Documentation/block/stat.rst for
details.
File /sys/block/zram<id>/io_stat
diff --git a/MAINTAINERS b/MAINTAINERS
index f5a2121294b3..fd6fab0dec77 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2929,7 +2929,7 @@ M: Jens Axboe <axboe@kernel.dk>
L: linux-block@vger.kernel.org
S: Maintained
F: block/bfq-*
-F: Documentation/block/bfq-iosched.txt
+F: Documentation/block/bfq-iosched.rst
BFS FILE SYSTEM
M: "Tigran A. Aivazian" <aivazian.tigran@gmail.com>
diff --git a/block/Kconfig b/block/Kconfig
index 56cb1695cd87..b16b3e075d31 100644
--- a/block/Kconfig
+++ b/block/Kconfig
@@ -110,7 +110,7 @@ config BLK_CMDLINE_PARSER
which don't otherwise have any standardized method for listing the
partitions on a block device.
- See Documentation/block/cmdline-partition.txt for more information.
+ See Documentation/block/cmdline-partition.rst for more information.
config BLK_WBT
bool "Enable support for block device writeback throttling"
diff --git a/block/Kconfig.iosched b/block/Kconfig.iosched
index 7a6b2f29a582..b89310a022ad 100644
--- a/block/Kconfig.iosched
+++ b/block/Kconfig.iosched
@@ -26,7 +26,7 @@ config IOSCHED_BFQ
regardless of the device parameters and with any workload. It
also guarantees a low latency to interactive and soft
real-time applications. Details in
- Documentation/block/bfq-iosched.txt
+ Documentation/block/bfq-iosched.rst
config BFQ_GROUP_IOSCHED
bool "BFQ hierarchical scheduling support"
diff --git a/block/bfq-iosched.c b/block/bfq-iosched.c
index 008c93d6b8d7..e8803fff8ea2 100644
--- a/block/bfq-iosched.c
+++ b/block/bfq-iosched.c
@@ -17,7 +17,7 @@
* low-latency capabilities. BFQ also supports full hierarchical
* scheduling through cgroups. Next paragraphs provide an introduction
* on BFQ inner workings. Details on BFQ benefits, usage and
- * limitations can be found in Documentation/block/bfq-iosched.txt.
+ * limitations can be found in Documentation/block/bfq-iosched.rst.
*
* BFQ is a proportional-share storage-I/O scheduling algorithm based
* on the slice-by-slice service scheme of CFQ. But BFQ assigns
diff --git a/block/blk-integrity.c b/block/blk-integrity.c
index 825c9c070458..ca39b4624cf8 100644
--- a/block/blk-integrity.c
+++ b/block/blk-integrity.c
@@ -383,7 +383,7 @@ static const struct blk_integrity_profile nop_profile = {
* send/receive integrity metadata it must use this function to register
* the capability with the block layer. The template is a blk_integrity
* struct with values appropriate for the underlying hardware. See
- * Documentation/block/data-integrity.txt.
+ * Documentation/block/data-integrity.rst.
*/
void blk_integrity_register(struct gendisk *disk, struct blk_integrity *template)
{
diff --git a/block/ioprio.c b/block/ioprio.c
index 2e0559f157c8..77bcab11dce5 100644
--- a/block/ioprio.c
+++ b/block/ioprio.c
@@ -17,7 +17,7 @@
*
* ioprio_set(PRIO_PROCESS, pid, prio);
*
- * See also Documentation/block/ioprio.txt
+ * See also Documentation/block/ioprio.rst
*
*/
#include <linux/gfp.h>
diff --git a/block/mq-deadline.c b/block/mq-deadline.c
index b8a682b5a1bb..2a2a2e82832e 100644
--- a/block/mq-deadline.c
+++ b/block/mq-deadline.c
@@ -25,7 +25,7 @@
#include "blk-mq-sched.h"
/*
- * See Documentation/block/deadline-iosched.txt
+ * See Documentation/block/deadline-iosched.rst
*/
static const int read_expire = HZ / 2; /* max time before a read is submitted. */
static const int write_expire = 5 * HZ; /* ditto for writes, these limits are SOFT! */
diff --git a/block/partitions/cmdline.c b/block/partitions/cmdline.c
index 60fb3df9897c..f1edd5452249 100644
--- a/block/partitions/cmdline.c
+++ b/block/partitions/cmdline.c
@@ -11,7 +11,7 @@
*
* The format for the command line is just like mtdparts.
*
- * For further information, see "Documentation/block/cmdline-partition.txt"
+ * For further information, see "Documentation/block/cmdline-partition.rst"
*
*/
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (38 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 40/43] docs: block: " Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-07-01 1:40 ` Chanwoo Choi
2019-07-05 9:41 ` Rafael J. Wysocki
2019-06-28 12:20 ` [PATCH 42/43] docs: move gcc_plugins.txt to core-api and rename to .rst Mauro Carvalho Chehab
` (2 subsequent siblings)
42 siblings, 2 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, MyungJoo Ham, Chanwoo Choi, Rafael J. Wysocki,
Len Brown, linux-acpi
The intel-int3496.txt file is a documentation for an ACPI driver.
There's no reason to keep it on a separate directory.
So, instead of keeping it on some random location, move it
to a sub-directory inside the ACPI documentation dir,
renaming it to .rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/extcon-intel-int3496.rst} | 14 ++++++++++----
Documentation/firmware-guide/acpi/index.rst | 1 +
MAINTAINERS | 6 +++---
3 files changed, 14 insertions(+), 7 deletions(-)
rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
similarity index 66%
rename from Documentation/extcon/intel-int3496.txt
rename to Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
index 8155dbc7fad3..5137ca834b54 100644
--- a/Documentation/extcon/intel-int3496.txt
+++ b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
@@ -1,5 +1,6 @@
+=====================================================
Intel INT3496 ACPI device extcon driver documentation
------------------------------------------------------
+=====================================================
The Intel INT3496 ACPI device extcon driver is a driver for ACPI
devices with an acpi-id of INT3496, such as found for example on
@@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
The ACPI devices exposes this functionality by returning an array with up
to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
-Index 0: The input gpio for the id-pin, this is always present and valid
-Index 1: The output gpio for enabling Vbus output from the device to the otg
+======= =====================================================================
+Index 0 The input gpio for the id-pin, this is always present and valid
+Index 1 The output gpio for enabling Vbus output from the device to the otg
port, write 1 to enable the Vbus output (this gpio descriptor may
be absent or invalid)
-Index 2: The output gpio for muxing of the data pins between the USB host and
+Index 2 The output gpio for muxing of the data pins between the USB host and
the USB peripheral controller, write 1 to mux to the peripheral
controller
+======= =====================================================================
There is a mapping between indices and GPIO connection IDs as follows
+
+ ======= =======
id index 0
vbus index 1
mux index 2
+ ======= =======
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index ae609eec4679..90c90d42d9ad 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -24,3 +24,4 @@ ACPI Support
acpi-lid
lpit
video_extension
+ extcon-intel-int3496
diff --git a/MAINTAINERS b/MAINTAINERS
index fd6fab0dec77..2cf8abf6d48e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -321,7 +321,7 @@ F: drivers/pnp/pnpacpi/
F: include/linux/acpi.h
F: include/linux/fwnode.h
F: include/acpi/
-F: Documentation/acpi/
+F: Documentation/firmware-guide/acpi/
F: Documentation/ABI/testing/sysfs-bus-acpi
F: Documentation/ABI/testing/configfs-acpi
F: drivers/pci/*acpi*
@@ -4896,7 +4896,7 @@ S: Maintained
F: Documentation/
F: scripts/kernel-doc
X: Documentation/ABI/
-X: Documentation/acpi/
+X: Documentation/firmware-guide/acpi/
X: Documentation/devicetree/
X: Documentation/i2c/
X: Documentation/media/
@@ -6073,7 +6073,7 @@ S: Maintained
F: drivers/extcon/
F: include/linux/extcon/
F: include/linux/extcon.h
-F: Documentation/extcon/
+F: Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
F: Documentation/devicetree/bindings/extcon/
EXYNOS DP DRIVER
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 42/43] docs: move gcc_plugins.txt to core-api and rename to .rst
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (39 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-06-28 14:47 ` Kees Cook
2019-06-28 12:20 ` [PATCH 43/43] docs: logo.txt: rename it to COPYING-logo Mauro Carvalho Chehab
2019-07-29 9:50 ` [PATCH 00/43] Convert doc files to ReST Geert Uytterhoeven
42 siblings, 1 reply; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Kees Cook, Emese Revfy
The gcc_plugins.txt file is already a ReST file. Move it
to the core-api book while renaming it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/{gcc-plugins.txt => core-api/gcc-plugins.rst} | 0
Documentation/core-api/index.rst | 2 +-
MAINTAINERS | 2 +-
scripts/gcc-plugins/Kconfig | 2 +-
4 files changed, 3 insertions(+), 3 deletions(-)
rename Documentation/{gcc-plugins.txt => core-api/gcc-plugins.rst} (100%)
diff --git a/Documentation/gcc-plugins.txt b/Documentation/core-api/gcc-plugins.rst
similarity index 100%
rename from Documentation/gcc-plugins.txt
rename to Documentation/core-api/gcc-plugins.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 2466a4c51031..d1e5b95bf86d 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -35,7 +35,7 @@ Core utilities
boot-time-mm
memory-hotplug
protection-keys
-
+ gcc-plugins
Interfaces for kernel debugging
===============================
diff --git a/MAINTAINERS b/MAINTAINERS
index 2cf8abf6d48e..7ba6d174f49f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6609,7 +6609,7 @@ S: Maintained
F: scripts/gcc-plugins/
F: scripts/gcc-plugin.sh
F: scripts/Makefile.gcc-plugins
-F: Documentation/gcc-plugins.txt
+F: Documentation/core-api/gcc-plugins.rst
GASKET DRIVER FRAMEWORK
M: Rob Springer <rspringer@google.com>
diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig
index e9c677a53c74..d33de0b9f4f5 100644
--- a/scripts/gcc-plugins/Kconfig
+++ b/scripts/gcc-plugins/Kconfig
@@ -23,7 +23,7 @@ config GCC_PLUGINS
GCC plugins are loadable modules that provide extra features to the
compiler. They are useful for runtime instrumentation and static analysis.
- See Documentation/gcc-plugins.txt for details.
+ See Documentation/core-api/gcc-plugins.rst for details.
menu "GCC plugins"
depends on GCC_PLUGINS
--
2.21.0
^ permalink raw reply related [flat|nested] 54+ messages in thread
* [PATCH 43/43] docs: logo.txt: rename it to COPYING-logo
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (40 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 42/43] docs: move gcc_plugins.txt to core-api and rename to .rst Mauro Carvalho Chehab
@ 2019-06-28 12:20 ` Mauro Carvalho Chehab
2019-07-29 9:50 ` [PATCH 00/43] Convert doc files to ReST Geert Uytterhoeven
42 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-28 12:20 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This file has nothing to do with the Kernel documentation. It
contains the copyright permissions for Tux at Documentation/logo.gif.
So, rename it accordingly.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/{logo.txt => COPYING-logo} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename Documentation/{logo.txt => COPYING-logo} (100%)
diff --git a/Documentation/logo.txt b/Documentation/COPYING-logo
similarity index 100%
rename from Documentation/logo.txt
rename to Documentation/COPYING-logo
--
2.21.0
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 11/43] docs: console.txt: convert docs to ReST and rename to *.rst
2019-06-28 12:20 ` [PATCH 11/43] docs: console.txt: " Mauro Carvalho Chehab
@ 2019-06-28 12:53 ` Bartlomiej Zolnierkiewicz
0 siblings, 0 replies; 54+ messages in thread
From: Bartlomiej Zolnierkiewicz @ 2019-06-28 12:53 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Greg Kroah-Hartman, Jiri Slaby, dri-devel,
linux-fbdev
On 6/28/19 2:20 PM, Mauro Carvalho Chehab wrote:
> 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>
> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
> ---
> .../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%)
Best regards,
--
Bartlomiej Zolnierkiewicz
Samsung R&D Institute Poland
Samsung Electronics
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 42/43] docs: move gcc_plugins.txt to core-api and rename to .rst
2019-06-28 12:20 ` [PATCH 42/43] docs: move gcc_plugins.txt to core-api and rename to .rst Mauro Carvalho Chehab
@ 2019-06-28 14:47 ` Kees Cook
0 siblings, 0 replies; 54+ messages in thread
From: Kees Cook @ 2019-06-28 14:47 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Emese Revfy
On Fri, Jun 28, 2019 at 09:20:38AM -0300, Mauro Carvalho Chehab wrote:
> The gcc_plugins.txt file is already a ReST file. Move it
> to the core-api book while renaming it.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Kees Cook <keescook@chromium.org>
-Kees
> ---
> Documentation/{gcc-plugins.txt => core-api/gcc-plugins.rst} | 0
> Documentation/core-api/index.rst | 2 +-
> MAINTAINERS | 2 +-
> scripts/gcc-plugins/Kconfig | 2 +-
> 4 files changed, 3 insertions(+), 3 deletions(-)
> rename Documentation/{gcc-plugins.txt => core-api/gcc-plugins.rst} (100%)
>
> diff --git a/Documentation/gcc-plugins.txt b/Documentation/core-api/gcc-plugins.rst
> similarity index 100%
> rename from Documentation/gcc-plugins.txt
> rename to Documentation/core-api/gcc-plugins.rst
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index 2466a4c51031..d1e5b95bf86d 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -35,7 +35,7 @@ Core utilities
> boot-time-mm
> memory-hotplug
> protection-keys
> -
> + gcc-plugins
>
> Interfaces for kernel debugging
> ===============================
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 2cf8abf6d48e..7ba6d174f49f 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -6609,7 +6609,7 @@ S: Maintained
> F: scripts/gcc-plugins/
> F: scripts/gcc-plugin.sh
> F: scripts/Makefile.gcc-plugins
> -F: Documentation/gcc-plugins.txt
> +F: Documentation/core-api/gcc-plugins.rst
>
> GASKET DRIVER FRAMEWORK
> M: Rob Springer <rspringer@google.com>
> diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig
> index e9c677a53c74..d33de0b9f4f5 100644
> --- a/scripts/gcc-plugins/Kconfig
> +++ b/scripts/gcc-plugins/Kconfig
> @@ -23,7 +23,7 @@ config GCC_PLUGINS
> GCC plugins are loadable modules that provide extra features to the
> compiler. They are useful for runtime instrumentation and static analysis.
>
> - See Documentation/gcc-plugins.txt for details.
> + See Documentation/core-api/gcc-plugins.rst for details.
>
> menu "GCC plugins"
> depends on GCC_PLUGINS
> --
> 2.21.0
>
--
Kees Cook
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 30/43] docs: nvdimm: convert to ReST
2019-06-28 12:20 ` [PATCH 30/43] docs: nvdimm: " Mauro Carvalho Chehab
@ 2019-06-28 16:32 ` Dan Williams
0 siblings, 0 replies; 54+ messages in thread
From: Dan Williams @ 2019-06-28 16:32 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Vishal Verma,
Dave Jiang, Keith Busch, Ira Weiny, linux-nvdimm
On Fri, Jun 28, 2019 at 5:21 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Rename the nvdimm 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>
Acked-by: Dan Williams <dan.j.williams@intel.com>
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 24/43] docs: leds: convert to ReST
2019-06-28 12:20 ` [PATCH 24/43] docs: leds: " Mauro Carvalho Chehab
@ 2019-06-28 19:01 ` Jacek Anaszewski
2019-07-06 10:41 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 54+ messages in thread
From: Jacek Anaszewski @ 2019-06-28 19:01 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Vadim Pasternak, Pavel Machek, Dan Murphy, Pablo Neira Ayuso,
Jozsef Kadlecsik, Florian Westphal, David S. Miller, linux-leds,
netfilter-devel, coreteam, netdev
Hi Mauro,
On 6/28/19 2:20 PM, Mauro Carvalho Chehab wrote:
> 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>
> Acked-by: Pavel Machek <pavel@ucw.cz>
> ---
> 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%)
Patches 4/9 and 24/43 applied to the for-next branch of linux-leds.git.
Thanks!
--
Best regards,
Jacek Anaszewski
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir
2019-06-28 12:20 ` [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir Mauro Carvalho Chehab
@ 2019-07-01 1:40 ` Chanwoo Choi
2019-07-05 9:41 ` Rafael J. Wysocki
1 sibling, 0 replies; 54+ messages in thread
From: Chanwoo Choi @ 2019-07-01 1:40 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
MyungJoo Ham, Rafael J. Wysocki, Len Brown, linux-acpi
Hi Mauro,
On 19. 6. 28. 오후 9:20, Mauro Carvalho Chehab wrote:
> The intel-int3496.txt file is a documentation for an ACPI driver.
>
> There's no reason to keep it on a separate directory.
>
> So, instead of keeping it on some random location, move it
> to a sub-directory inside the ACPI documentation dir,
> renaming it to .rst.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../acpi/extcon-intel-int3496.rst} | 14 ++++++++++----
> Documentation/firmware-guide/acpi/index.rst | 1 +
> MAINTAINERS | 6 +++---
> 3 files changed, 14 insertions(+), 7 deletions(-)
> rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
>
> diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> similarity index 66%
> rename from Documentation/extcon/intel-int3496.txt
> rename to Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> index 8155dbc7fad3..5137ca834b54 100644
> --- a/Documentation/extcon/intel-int3496.txt
> +++ b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> @@ -1,5 +1,6 @@
> +=====================================================
> Intel INT3496 ACPI device extcon driver documentation
> ------------------------------------------------------
> +=====================================================
>
> The Intel INT3496 ACPI device extcon driver is a driver for ACPI
> devices with an acpi-id of INT3496, such as found for example on
> @@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
> The ACPI devices exposes this functionality by returning an array with up
> to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
>
> -Index 0: The input gpio for the id-pin, this is always present and valid
> -Index 1: The output gpio for enabling Vbus output from the device to the otg
> +======= =====================================================================
> +Index 0 The input gpio for the id-pin, this is always present and valid
> +Index 1 The output gpio for enabling Vbus output from the device to the otg
> port, write 1 to enable the Vbus output (this gpio descriptor may
> be absent or invalid)
> -Index 2: The output gpio for muxing of the data pins between the USB host and
> +Index 2 The output gpio for muxing of the data pins between the USB host and
> the USB peripheral controller, write 1 to mux to the peripheral
> controller
> +======= =====================================================================
>
> There is a mapping between indices and GPIO connection IDs as follows
> +
> + ======= =======
> id index 0
> vbus index 1
> mux index 2
> + ======= =======
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index ae609eec4679..90c90d42d9ad 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -24,3 +24,4 @@ ACPI Support
> acpi-lid
> lpit
> video_extension
> + extcon-intel-int3496
> diff --git a/MAINTAINERS b/MAINTAINERS
> index fd6fab0dec77..2cf8abf6d48e 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -321,7 +321,7 @@ F: drivers/pnp/pnpacpi/
> F: include/linux/acpi.h
> F: include/linux/fwnode.h
> F: include/acpi/
> -F: Documentation/acpi/
> +F: Documentation/firmware-guide/acpi/
> F: Documentation/ABI/testing/sysfs-bus-acpi
> F: Documentation/ABI/testing/configfs-acpi
> F: drivers/pci/*acpi*
> @@ -4896,7 +4896,7 @@ S: Maintained
> F: Documentation/
> F: scripts/kernel-doc
> X: Documentation/ABI/
> -X: Documentation/acpi/
> +X: Documentation/firmware-guide/acpi/
> X: Documentation/devicetree/
> X: Documentation/i2c/
> X: Documentation/media/
> @@ -6073,7 +6073,7 @@ S: Maintained
> F: drivers/extcon/
> F: include/linux/extcon/
> F: include/linux/extcon.h
> -F: Documentation/extcon/
> +F: Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> F: Documentation/devicetree/bindings/extcon/
>
> EXYNOS DP DRIVER
>
Acked-by: Chanwoo Choi <cw00.choi@samsung.com>
--
Best Regards,
Chanwoo Choi
Samsung Electronics
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 03/43] docs: hid: convert to ReST
2019-06-28 12:19 ` [PATCH 03/43] docs: hid: " Mauro Carvalho Chehab
@ 2019-07-02 9:58 ` Benjamin Tissoires
0 siblings, 0 replies; 54+ messages in thread
From: Benjamin Tissoires @ 2019-07-02 9:58 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, lkml,
Jonathan Corbet, Jiri Kosina, Jonathan Cameron,
Srinivas Pandruvada, Dmitry Torokhov, open list:HID CORE LAYER,
linux-iio, Linux USB Mailing List
On Fri, Jun 28, 2019 at 2:21 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> 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>
> Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
> ---
This patch has been pushed to for-5.3/doc in the HID tree.
Cheers,
Benjamin
> .../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 4f41d67f1b4b..0fe526f36db6 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 3e3b9738f2e6..9458cdaa5b4b 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -16461,7 +16461,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 [flat|nested] 54+ messages in thread
* Re: [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst
2019-06-28 12:19 ` [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-07-03 18:06 ` Jason Gunthorpe
2019-07-06 11:02 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 54+ messages in thread
From: Jason Gunthorpe @ 2019-07-03 18:06 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Doug Ledford, linux-rdma
On Fri, Jun 28, 2019 at 09:19:57AM -0300, Mauro Carvalho Chehab wrote:
> The InfiniBand docs are plain text with no markups.
> So, all we needed to do were to add the title markups and
> some markup sequences in order to properly parse tables,
> lists and literal blocks.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../{core_locking.txt => core_locking.rst} | 64 ++++++-----
> Documentation/infiniband/index.rst | 23 ++++
> .../infiniband/{ipoib.txt => ipoib.rst} | 24 ++--
> .../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +++++++++---------
> .../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
> .../{tag_matching.txt => tag_matching.rst} | 5 +
> .../infiniband/{user_mad.txt => user_mad.rst} | 33 ++++--
> .../{user_verbs.txt => user_verbs.rst} | 12 +-
> drivers/infiniband/core/user_mad.c | 2 +-
> drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
> 10 files changed, 174 insertions(+), 103 deletions(-)
> rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
> create mode 100644 Documentation/infiniband/index.rst
> rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
> rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
> rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
> rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
> rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
> rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
I'm not sure anymore if I sent a note or not, but this patch was
already applied to the rdma.git:
commit 97162a1ee8a1735fc7a7159fe08de966d88354ce
Author: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Date: Sat Jun 8 23:27:03 2019 -0300
docs: infiniband: convert docs to ReST and rename to *.rst
The InfiniBand docs are plain text with no markups. So, all we needed to
do were to add the title markups and some markup sequences in order to
properly parse tables, lists and literal blocks.
At its new index.rst, let's add a :orphan: while this is not linked to the
main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jason Gunthorpe <jgg@mellanox.com>
Thanks,
Jason
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir
2019-06-28 12:20 ` [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir Mauro Carvalho Chehab
2019-07-01 1:40 ` Chanwoo Choi
@ 2019-07-05 9:41 ` Rafael J. Wysocki
1 sibling, 0 replies; 54+ messages in thread
From: Rafael J. Wysocki @ 2019-07-05 9:41 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, MyungJoo Ham, Chanwoo Choi, Len Brown,
linux-acpi
On Friday, June 28, 2019 2:20:37 PM CEST Mauro Carvalho Chehab wrote:
> The intel-int3496.txt file is a documentation for an ACPI driver.
>
> There's no reason to keep it on a separate directory.
>
> So, instead of keeping it on some random location, move it
> to a sub-directory inside the ACPI documentation dir,
> renaming it to .rst.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../acpi/extcon-intel-int3496.rst} | 14 ++++++++++----
> Documentation/firmware-guide/acpi/index.rst | 1 +
> MAINTAINERS | 6 +++---
> 3 files changed, 14 insertions(+), 7 deletions(-)
> rename Documentation/{extcon/intel-int3496.txt => firmware-guide/acpi/extcon-intel-int3496.rst} (66%)
>
> diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> similarity index 66%
> rename from Documentation/extcon/intel-int3496.txt
> rename to Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> index 8155dbc7fad3..5137ca834b54 100644
> --- a/Documentation/extcon/intel-int3496.txt
> +++ b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> @@ -1,5 +1,6 @@
> +=====================================================
> Intel INT3496 ACPI device extcon driver documentation
> ------------------------------------------------------
> +=====================================================
>
> The Intel INT3496 ACPI device extcon driver is a driver for ACPI
> devices with an acpi-id of INT3496, such as found for example on
> @@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
> The ACPI devices exposes this functionality by returning an array with up
> to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
>
> -Index 0: The input gpio for the id-pin, this is always present and valid
> -Index 1: The output gpio for enabling Vbus output from the device to the otg
> +======= =====================================================================
> +Index 0 The input gpio for the id-pin, this is always present and valid
> +Index 1 The output gpio for enabling Vbus output from the device to the otg
> port, write 1 to enable the Vbus output (this gpio descriptor may
> be absent or invalid)
> -Index 2: The output gpio for muxing of the data pins between the USB host and
> +Index 2 The output gpio for muxing of the data pins between the USB host and
> the USB peripheral controller, write 1 to mux to the peripheral
> controller
> +======= =====================================================================
>
> There is a mapping between indices and GPIO connection IDs as follows
> +
> + ======= =======
> id index 0
> vbus index 1
> mux index 2
> + ======= =======
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index ae609eec4679..90c90d42d9ad 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -24,3 +24,4 @@ ACPI Support
> acpi-lid
> lpit
> video_extension
> + extcon-intel-int3496
> diff --git a/MAINTAINERS b/MAINTAINERS
> index fd6fab0dec77..2cf8abf6d48e 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -321,7 +321,7 @@ F: drivers/pnp/pnpacpi/
> F: include/linux/acpi.h
> F: include/linux/fwnode.h
> F: include/acpi/
> -F: Documentation/acpi/
> +F: Documentation/firmware-guide/acpi/
> F: Documentation/ABI/testing/sysfs-bus-acpi
> F: Documentation/ABI/testing/configfs-acpi
> F: drivers/pci/*acpi*
> @@ -4896,7 +4896,7 @@ S: Maintained
> F: Documentation/
> F: scripts/kernel-doc
> X: Documentation/ABI/
> -X: Documentation/acpi/
> +X: Documentation/firmware-guide/acpi/
> X: Documentation/devicetree/
> X: Documentation/i2c/
> X: Documentation/media/
> @@ -6073,7 +6073,7 @@ S: Maintained
> F: drivers/extcon/
> F: include/linux/extcon/
> F: include/linux/extcon.h
> -F: Documentation/extcon/
> +F: Documentation/firmware-guide/acpi/extcon-intel-int3496.rst
> F: Documentation/devicetree/bindings/extcon/
>
> EXYNOS DP DRIVER
>
Applied, thanks!
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 24/43] docs: leds: convert to ReST
2019-06-28 19:01 ` Jacek Anaszewski
@ 2019-07-06 10:41 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-06 10:41 UTC (permalink / raw)
To: Jacek Anaszewski
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Vadim Pasternak, Pavel Machek, Dan Murphy,
Pablo Neira Ayuso, Jozsef Kadlecsik, Florian Westphal,
David S. Miller, linux-leds, netfilter-devel, coreteam, netdev
Em Fri, 28 Jun 2019 21:01:40 +0200
Jacek Anaszewski <jacek.anaszewski@gmail.com> escreveu:
> Hi Mauro,
>
> On 6/28/19 2:20 PM, Mauro Carvalho Chehab wrote:
> > 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>
> > Acked-by: Pavel Machek <pavel@ucw.cz>
> > ---
> > 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%)
>
> Patches 4/9 and 24/43 applied to the for-next branch of linux-leds.git.
Thanks!
I'll keep this one on my tree:
[PATCH 10/39] docs: leds: add it to the driver-api book
From the other series. If everything goes well, either Jon or I should
be sending upstream by the end of the merge window, after rebasing it,
together with a bunch of other patches touching the driver-api index.rst.
That should hopefully avoid merge conflicts.
Regards,
Mauro
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst
2019-07-03 18:06 ` Jason Gunthorpe
@ 2019-07-06 11:02 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 54+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-06 11:02 UTC (permalink / raw)
To: Jason Gunthorpe
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Doug Ledford, linux-rdma
Em Wed, 3 Jul 2019 15:06:41 -0300
Jason Gunthorpe <jgg@ziepe.ca> escreveu:
> On Fri, Jun 28, 2019 at 09:19:57AM -0300, Mauro Carvalho Chehab wrote:
> > The InfiniBand docs are plain text with no markups.
> > So, all we needed to do were to add the title markups and
> > some markup sequences in order to properly parse tables,
> > lists and literal blocks.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > .../{core_locking.txt => core_locking.rst} | 64 ++++++-----
> > Documentation/infiniband/index.rst | 23 ++++
> > .../infiniband/{ipoib.txt => ipoib.rst} | 24 ++--
> > .../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +++++++++---------
> > .../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
> > .../{tag_matching.txt => tag_matching.rst} | 5 +
> > .../infiniband/{user_mad.txt => user_mad.rst} | 33 ++++--
> > .../{user_verbs.txt => user_verbs.rst} | 12 +-
> > drivers/infiniband/core/user_mad.c | 2 +-
> > drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
> > 10 files changed, 174 insertions(+), 103 deletions(-)
> > rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
> > create mode 100644 Documentation/infiniband/index.rst
> > rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
> > rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
> > rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
> > rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
> > rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
> > rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
>
> I'm not sure anymore if I sent a note or not, but this patch was
> already applied to the rdma.git:
>
> commit 97162a1ee8a1735fc7a7159fe08de966d88354ce
> Author: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Date: Sat Jun 8 23:27:03 2019 -0300
>
> docs: infiniband: convert docs to ReST and rename to *.rst
>
> The InfiniBand docs are plain text with no markups. So, all we needed to
> do were to add the title markups and some markup sequences in order to
> properly parse tables, lists and literal blocks.
>
> At its new index.rst, let's add a :orphan: while this is not linked to the
> main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Signed-off-by: Jason Gunthorpe <jgg@mellanox.com>
Ah, ok, thanks!
Not sure why but this one still applies on the top of -next.
Probably just the usual merge noise that happens close to
a new merge window.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 54+ messages in thread
* Re: [PATCH 00/43] Convert doc files to ReST
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
` (41 preceding siblings ...)
2019-06-28 12:20 ` [PATCH 43/43] docs: logo.txt: rename it to COPYING-logo Mauro Carvalho Chehab
@ 2019-07-29 9:50 ` Geert Uytterhoeven
42 siblings, 0 replies; 54+ messages in thread
From: Geert Uytterhoeven @ 2019-07-29 9:50 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Linux-Renesas
Hi Mauro,
On Fri, Jun 28, 2019 at 2:25 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> This patchset contains the patches that weren't merged yet from
> part 2 and 3 of the previous ReST conversion patchset.
>
> This is based aganst linux-next (next-20190627), so they may not
> apply cleanly at docs-next.
>
> It does contain file renames, but, except for a few exceptions, the files
> are kept where they are.
>
> The first patches on this series were agreed to be merged via subsystem's
> tree, but, as they didn't appear at -next, I'm recending as a gentile
> ping.
[...]
> .../arm/{SH-Mobile => sh-mobile}/.gitignore | 0
I guess that should have been "shmobile^H^H^H^H^H^H^H^Hrenesas",
for consistency with modern naming?
For whatever it's worth keeping empty subdirectories, of course,
containing just an obsolete .gitignore file...
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
^ permalink raw reply [flat|nested] 54+ messages in thread
end of thread, other threads:[~2019-07-29 9:50 UTC | newest]
Thread overview: 54+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-06-28 12:19 [PATCH 00/43] Convert doc files to ReST Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 01/43] docs: infiniband: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-07-03 18:06 ` Jason Gunthorpe
2019-07-06 11:02 ` Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 02/43] docs: iio: convert to ReST Mauro Carvalho Chehab
2019-06-28 12:19 ` [PATCH 03/43] docs: hid: " Mauro Carvalho Chehab
2019-07-02 9:58 ` Benjamin Tissoires
2019-06-28 12:20 ` [PATCH 04/43] docs: locking: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 05/43] docs: powerpc: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 06/43] docs: connector: convert to ReST and rename to connector.rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 07/43] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 08/43] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 09/43] docs: m68k: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 10/43] docs: cma/debugfs.txt: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 11/43] docs: console.txt: " Mauro Carvalho Chehab
2019-06-28 12:53 ` Bartlomiej Zolnierkiewicz
2019-06-28 12:20 ` [PATCH 12/43] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 13/43] docs: early-userspace: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 15/43] docs: memory-devices: convert ti-emif.txt to ReST Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 16/43] docs: xen-tpmfront.txt: convert it to .rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 17/43] docs: bus-devices: ti-gpmc.rst: convert it to ReST Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 18/43] docs: nvmem: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 19/43] docs: phy: convert samsung-usb2.txt to ReST format Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 20/43] docs: rbtree.txt: fix Sphinx build warnings Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 21/43] docs: DMA-API-HOWTO.txt: fix an unmarked code block Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 22/43] docs: accounting: convert to ReST Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 23/43] docs: ia64: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 24/43] docs: leds: " Mauro Carvalho Chehab
2019-06-28 19:01 ` Jacek Anaszewski
2019-07-06 10:41 ` Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 25/43] docs: laptops: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 26/43] docs: namespaces: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 27/43] docs: nfc: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 28/43] docs: md: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 29/43] docs: mtd: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 30/43] docs: nvdimm: " Mauro Carvalho Chehab
2019-06-28 16:32 ` Dan Williams
2019-06-28 12:20 ` [PATCH 31/43] docs: xtensa: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 32/43] docs: mmc: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 33/43] docs: ioctl-number.txt: convert it to ReST format Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 34/43] docs: ioctl: convert to ReST Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 35/43] docs: thermal: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 36/43] docs: rapidio: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 37/43] docs: blockdev: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 38/43] docs: perf: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 39/43] docs: sysctl: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 40/43] docs: block: " Mauro Carvalho Chehab
2019-06-28 12:20 ` [PATCH 41/43] docs: extcon: convert it to ReST and move to acpi dir Mauro Carvalho Chehab
2019-07-01 1:40 ` Chanwoo Choi
2019-07-05 9:41 ` Rafael J. Wysocki
2019-06-28 12:20 ` [PATCH 42/43] docs: move gcc_plugins.txt to core-api and rename to .rst Mauro Carvalho Chehab
2019-06-28 14:47 ` Kees Cook
2019-06-28 12:20 ` [PATCH 43/43] docs: logo.txt: rename it to COPYING-logo Mauro Carvalho Chehab
2019-07-29 9:50 ` [PATCH 00/43] Convert doc files to ReST Geert Uytterhoeven
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).