Convert files to ReST
Subsystems (41)
cover Convert files to ReST
This series convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, the series is based on linux-next.
I have a separate patch series with do the actual rename and adjustment of references. I opted to submit this first, as it sounds easier to merge this way, as each subsystem maintainer can apply the conversion directly on their trees (or at docs tree), avoiding merge conflects.
Both this series and the next steps are on my devel git tree, at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=all_with_indexes-v3
The final output in html can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
Mauro Carvalho Chehab (57):
docs: trace: fix some Sphinx warnings
docs: acpi: convert text files to ReST
docs: aoe: convert text files to ReST
docs: arm64: convert documentation to ReST format
docs: cdrom/cdrom-standard.tex: convert from LaTeX to ReST
docs: cdrom: convert remaining files to ReST
docs: cgroup-v1: convert to ReST file format
docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
docs: cpu-freq: convert files to ReST
docs: device-mapper: convert it to ReST format
docs: extcon: move it to acpi dir and convert it to ReST
docs: fault-injection: convert it to ReST format
docs: fb: convert documentation to ReST format
docs: fpga: convert it to ReST
docs: gpio: convert it to ReST
docs: ide: convert it to ReST format
docs: infiniband: convert it to ReST format
docs: kbuild: convert it to ReST output
docs: kdump: convert it to ReST
docs: livepatch: convert it to ReST format
docs: locking: convert docs to ReST format
docs: mic: convert it to ReST format
docs: netlabel: convert it to ReST
docs: pcmcia: convert it to ReST format
docs: power: convert docs to ReST
docs: powerpc: convert docs to ReST
docs: pps/pps.txt convert it to ReST and move to API book
docs: ptp.txt: convert to ReST and move to driver-api
docs: riscv: convert it to ReST format
docs: s390: Debugging390.txt: convert table to ascii artwork
docs: s390: convert text files to ReST format
s390: include/asm/debug.h add kerneldoc markups
docs: serial: convert it to ReST format
docs: target: convert it to ReST format
docs: timers: convert documentation to ReST
docs: usb: convert documents to ReST
docs: watchdog: convert documents to ReST format
docs: x86: convert text files to ReST
docs: xilinx: convert eemi.txt to ReST
docs: scheduler: convert files to ReST
docs: EDID/HOWTO.txt: convert to ReST and move to kernel-API
docs: connector.txt: convert to ReST
docs: lcd-panel-cgram.txt convert it to ReST and move to admin-guide
docs: lp855x-driver.txt: convert to ReST and move to kernel-api
docs: m68k: convert it to ReST file format and add to arch bookset
docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm
docs: console.txt: convert to ReST format
docs: pti_intel_mid.txt: convert to ReST
docs: early-userspace: convert docs to ReST
docs: driver-model: convert it to ReST format
docs: arm: convert text files to ReST format
docs: memory-devices: convert ti-emif.txt to ReST format
docs: xen-tpmfront.txt: convert the file to ReST format
docs: bus-devices: ti-gpmc.txt: convert it to ReST
docs: nvmem: convert file to ReST format
docs: phy: convert samsung-usb2.txt to ReST format
docs: Prepare files to be renamed to *.rst
Documentation/EDID/HOWTO.txt | 29 +-
Documentation/acpi/DSD-properties-rules.txt | 4 +-
Documentation/acpi/acpi-lid.txt | 37 +-
Documentation/acpi/aml-debugger.txt | 31 +-
Documentation/acpi/apei/einj.txt | 59 +-
Documentation/acpi/apei/output_format.txt | 247 +-
Documentation/acpi/cppc_sysfs.txt | 52 +-
Documentation/acpi/debug.txt | 20 +-
.../drivers/extcon-intel-int3496.txt} | 14 +-
.../acpi/dsd/data-node-references.txt | 11 +-
Documentation/acpi/dsd/graph.txt | 24 +-
Documentation/acpi/dsd/leds.txt | 18 +-
Documentation/acpi/dsdt-override.txt | 4 +-
Documentation/acpi/enumeration.txt | 42 +-
Documentation/acpi/gpio-properties.txt | 42 +-
Documentation/acpi/i2c-muxes.txt | 21 +-
Documentation/acpi/initrd_table_override.txt | 90 +-
Documentation/acpi/linuxized-acpica.txt | 58 +-
Documentation/acpi/lpit.txt | 8 +-
Documentation/acpi/method-customizing.txt | 48 +-
Documentation/acpi/method-tracing.txt | 132 +-
Documentation/acpi/namespace.txt | 323 +-
Documentation/acpi/osi.txt | 3 +-
Documentation/acpi/scan_handlers.txt | 9 +-
Documentation/acpi/ssdt-overlays.txt | 128 +-
Documentation/acpi/video_extension.txt | 16 +-
Documentation/aoe/aoe.txt | 63 +-
Documentation/aoe/todo.txt | 3 +
Documentation/aoe/udev.txt | 2 +-
Documentation/arm/Booting | 71 +-
Documentation/arm/IXP4xx | 61 +-
Documentation/arm/Interrupts | 86 +-
Documentation/arm/Marvell/README | 537 ++--
Documentation/arm/Microchip/README | 63 +-
Documentation/arm/Netwinder | 59 +-
Documentation/arm/OMAP/DSS | 112 +-
Documentation/arm/OMAP/README | 7 +
Documentation/arm/OMAP/omap_pm | 55 +-
Documentation/arm/Porting | 14 +-
Documentation/arm/README | 50 +-
Documentation/arm/SA1100/ADSBitsy | 14 +-
Documentation/arm/SA1100/Assabet | 185 +-
Documentation/arm/SA1100/Brutus | 45 +-
Documentation/arm/SA1100/CERF | 10 +-
Documentation/arm/SA1100/FreeBird | 26 +-
Documentation/arm/SA1100/GraphicsClient | 46 +-
Documentation/arm/SA1100/GraphicsMaster | 13 +-
Documentation/arm/SA1100/HUW_WEBPANEL | 8 +-
Documentation/arm/SA1100/Itsy | 14 +-
Documentation/arm/SA1100/LART | 3 +-
Documentation/arm/SA1100/PLEB | 6 +-
Documentation/arm/SA1100/Pangolin | 10 +-
Documentation/arm/SA1100/Tifon | 4 +-
Documentation/arm/SA1100/Yopy | 5 +-
Documentation/arm/SA1100/empeg | 2 -
Documentation/arm/SA1100/nanoEngine | 6 +-
Documentation/arm/SA1100/serial_UART | 60 +-
Documentation/arm/SPEAr/overview.txt | 20 +-
Documentation/arm/Samsung-S3C24XX/CPUfreq.txt | 5 +-
.../arm/Samsung-S3C24XX/EB2410ITX.txt | 5 +-
Documentation/arm/Samsung-S3C24XX/GPIO.txt | 21 +-
Documentation/arm/Samsung-S3C24XX/H1940.txt | 5 +-
Documentation/arm/Samsung-S3C24XX/NAND.txt | 6 +-
.../arm/Samsung-S3C24XX/Overview.txt | 15 +-
Documentation/arm/Samsung-S3C24XX/S3C2412.txt | 5 +-
Documentation/arm/Samsung-S3C24XX/S3C2413.txt | 7 +-
.../arm/Samsung-S3C24XX/SMDK2440.txt | 5 +-
Documentation/arm/Samsung-S3C24XX/Suspend.txt | 20 +-
.../arm/Samsung-S3C24XX/USB-Host.txt | 16 +-
.../arm/Samsung/Bootloader-interface.txt | 27 +-
Documentation/arm/Samsung/GPIO.txt | 5 +-
Documentation/arm/Samsung/Overview.txt | 11 +-
Documentation/arm/Setup | 49 +-
Documentation/arm/VFP/release-notes.txt | 4 +-
.../arm/cluster-pm-race-avoidance.txt | 177 +-
Documentation/arm/firmware.txt | 14 +-
Documentation/arm/kernel_mode_neon.txt | 3 +
Documentation/arm/kernel_user_helpers.txt | 79 +-
Documentation/arm/keystone/Overview.txt | 47 +-
Documentation/arm/keystone/knav-qmss.txt | 6 +-
Documentation/arm/mem_alignment | 11 +-
Documentation/arm/memory.txt | 9 +-
Documentation/arm/nwfpe/NOTES | 3 +
Documentation/arm/nwfpe/README | 10 +-
Documentation/arm/nwfpe/README.FPE | 24 +-
Documentation/arm/nwfpe/TODO | 47 +-
Documentation/arm/pxa/mfp.txt | 106 +-
Documentation/arm/sti/overview.txt | 21 +-
Documentation/arm/sti/stih407-overview.txt | 9 +-
Documentation/arm/sti/stih415-overview.txt | 8 +-
Documentation/arm/sti/stih416-overview.txt | 5 +-
Documentation/arm/sti/stih418-overview.txt | 9 +-
.../arm/stm32/stm32f429-overview.rst | 5 +-
.../arm/stm32/stm32f746-overview.rst | 5 +-
.../arm/stm32/stm32f769-overview.rst | 5 +-
.../arm/stm32/stm32h743-overview.rst | 5 +-
.../arm/stm32/stm32mp157-overview.rst | 1 +
Documentation/arm/sunxi/README | 98 +-
Documentation/arm/sunxi/clocks.txt | 7 +-
Documentation/arm/swp_emulation | 24 +-
Documentation/arm/tcm.txt | 54 +-
Documentation/arm/uefi.txt | 39 +-
Documentation/arm/vlocks.txt | 9 +-
Documentation/arm64/acpi_object_usage.txt | 288 +-
Documentation/arm64/arm-acpi.txt | 153 +-
Documentation/arm64/booting.txt | 91 +-
Documentation/arm64/cpu-feature-registers.txt | 190 +-
Documentation/arm64/elf_hwcaps.txt | 50 +-
Documentation/arm64/hugetlbpage.txt | 7 +-
Documentation/arm64/legacy_instructions.txt | 43 +-
Documentation/arm64/memory.txt | 91 +-
.../arm64/pointer-authentication.txt | 2 +
Documentation/arm64/silicon-errata.txt | 63 +-
Documentation/arm64/sve.txt | 10 +-
Documentation/arm64/tagged-pointers.txt | 6 +-
Documentation/auxdisplay/lcd-panel-cgram.txt | 7 +-
Documentation/backlight/lp855x-driver.txt | 65 +-
Documentation/bt8xxgpio.txt | 1 -
Documentation/bus-devices/ti-gpmc.txt | 157 +-
Documentation/bus-virt-phys-mapping.txt | 50 +-
Documentation/cdrom/Makefile | 21 -
Documentation/cdrom/cdrom-standard.tex | 1026 -------
Documentation/cdrom/cdrom-standard.txt | 1063 +++++++
Documentation/cdrom/ide-cd | 178 +-
Documentation/cdrom/packet-writing.txt | 27 +-
Documentation/cgroup-v1/blkio-controller.txt | 103 +-
Documentation/cgroup-v1/cgroups.txt | 180 +-
Documentation/cgroup-v1/cpuacct.txt | 15 +-
Documentation/cgroup-v1/cpusets.txt | 203 +-
Documentation/cgroup-v1/devices.txt | 40 +-
Documentation/cgroup-v1/freezer-subsystem.txt | 14 +-
Documentation/cgroup-v1/hugetlb.txt | 31 +-
Documentation/cgroup-v1/memcg_test.txt | 259 +-
Documentation/cgroup-v1/memory.txt | 449 +--
Documentation/cgroup-v1/net_cls.txt | 37 +-
Documentation/cgroup-v1/net_prio.txt | 24 +-
Documentation/cgroup-v1/pids.txt | 78 +-
Documentation/cgroup-v1/rdma.txt | 66 +-
Documentation/cma/debugfs.txt | 6 +-
Documentation/connector/connector.txt | 128 +-
Documentation/console/console.txt | 61 +-
Documentation/cpu-freq/amd-powernow.txt | 11 +-
Documentation/cpu-freq/core.txt | 66 +-
Documentation/cpu-freq/cpu-drivers.txt | 217 +-
Documentation/cpu-freq/cpufreq-nforce2.txt | 12 +-
Documentation/cpu-freq/cpufreq-stats.txt | 141 +-
Documentation/cpu-freq/pcc-cpufreq.txt | 102 +-
.../device-mapper/cache-policies.txt | 24 +-
Documentation/device-mapper/cache.txt | 206 +-
Documentation/device-mapper/delay.txt | 29 +-
Documentation/device-mapper/dm-crypt.txt | 57 +-
Documentation/device-mapper/dm-flakey.txt | 45 +-
Documentation/device-mapper/dm-init.txt | 75 +-
Documentation/device-mapper/dm-integrity.txt | 55 +-
Documentation/device-mapper/dm-io.txt | 14 +-
Documentation/device-mapper/dm-log.txt | 5 +-
.../device-mapper/dm-queue-length.txt | 25 +-
Documentation/device-mapper/dm-raid.txt | 225 +-
.../device-mapper/dm-service-time.txt | 68 +-
Documentation/device-mapper/dm-uevent.txt | 143 +-
Documentation/device-mapper/dm-zoned.txt | 10 +-
Documentation/device-mapper/era.txt | 36 +-
Documentation/device-mapper/kcopyd.txt | 10 +-
Documentation/device-mapper/linear.txt | 100 +-
Documentation/device-mapper/log-writes.txt | 91 +-
.../device-mapper/persistent-data.txt | 4 +
Documentation/device-mapper/snapshot.txt | 116 +-
Documentation/device-mapper/statistics.txt | 62 +-
Documentation/device-mapper/striped.txt | 68 +-
Documentation/device-mapper/switch.txt | 47 +-
.../device-mapper/thin-provisioning.txt | 68 +-
Documentation/device-mapper/unstriped.txt | 111 +-
Documentation/device-mapper/verity.txt | 20 +-
Documentation/device-mapper/writecache.txt | 13 +-
Documentation/device-mapper/zero.txt | 14 +-
Documentation/driver-model/binding.txt | 20 +-
Documentation/driver-model/bus.txt | 69 +-
Documentation/driver-model/class.txt | 74 +-
.../driver-model/design-patterns.txt | 106 +-
Documentation/driver-model/device.txt | 57 +-
Documentation/driver-model/devres.txt | 50 +-
Documentation/driver-model/driver.txt | 112 +-
Documentation/driver-model/overview.txt | 37 +-
Documentation/driver-model/platform.txt | 30 +-
Documentation/driver-model/porting.txt | 333 +--
Documentation/early-userspace/README | 3 +
.../early-userspace/buffer-format.txt | 19 +-
.../fault-injection/fault-injection.txt | 265 +-
.../fault-injection/notifier-error-inject.txt | 18 +-
.../fault-injection/nvme-fault-injection.txt | 174 +-
.../fault-injection/provoke-crashes.txt | 40 +-
Documentation/fb/api.txt | 29 +-
Documentation/fb/arkfb.txt | 8 +-
Documentation/fb/aty128fb.txt | 31 +-
Documentation/fb/cirrusfb.txt | 47 +-
Documentation/fb/cmap_xfbdev.txt | 57 +-
Documentation/fb/deferred_io.txt | 28 +-
Documentation/fb/efifb.txt | 18 +-
Documentation/fb/ep93xx-fb.txt | 25 +-
Documentation/fb/fbcon.txt | 177 +-
Documentation/fb/framebuffer.txt | 79 +-
Documentation/fb/gxfb.txt | 22 +-
Documentation/fb/intel810.txt | 77 +-
Documentation/fb/intelfb.txt | 62 +-
Documentation/fb/internals.txt | 24 +-
Documentation/fb/lxfb.txt | 23 +-
Documentation/fb/matroxfb.txt | 526 ++--
Documentation/fb/metronomefb.txt | 8 +-
Documentation/fb/modedb.txt | 44 +-
Documentation/fb/pvr2fb.txt | 55 +-
Documentation/fb/pxafb.txt | 81 +-
Documentation/fb/s3fb.txt | 8 +-
Documentation/fb/sa1100fb.txt | 23 +-
Documentation/fb/sh7760fb.txt | 153 +-
Documentation/fb/sisfb.txt | 40 +-
Documentation/fb/sm501.txt | 7 +-
Documentation/fb/sm712fb.txt | 18 +-
Documentation/fb/sstfb.txt | 231 +-
Documentation/fb/tgafb.txt | 30 +-
Documentation/fb/tridentfb.txt | 34 +-
Documentation/fb/udlfb.txt | 55 +-
Documentation/fb/uvesafb.txt | 128 +-
Documentation/fb/vesafb.txt | 121 +-
Documentation/fb/viafb.txt | 393 +--
Documentation/fb/vt8623fb.txt | 10 +-
Documentation/fpga/dfl.txt | 58 +-
Documentation/gpio/sysfs.txt | 39 +-
Documentation/highuid.txt | 2 +-
Documentation/ide/ide-tape.txt | 23 +-
Documentation/ide/ide.txt | 147 +-
Documentation/ide/warm-plug-howto.txt | 10 +-
Documentation/index.rst | 1 +
Documentation/infiniband/core_locking.txt | 64 +-
Documentation/infiniband/ipoib.txt | 24 +-
Documentation/infiniband/opa_vnic.txt | 108 +-
Documentation/infiniband/sysfs.txt | 4 +-
Documentation/infiniband/tag_matching.txt | 5 +
Documentation/infiniband/user_mad.txt | 33 +-
Documentation/infiniband/user_verbs.txt | 12 +-
Documentation/kbuild/headers_install.txt | 5 +-
Documentation/kbuild/kbuild.txt | 119 +-
Documentation/kbuild/kconfig-language.txt | 232 +-
.../kbuild/kconfig-macro-language.txt | 37 +-
Documentation/kbuild/kconfig.txt | 136 +-
Documentation/kbuild/makefiles.txt | 518 ++--
Documentation/kbuild/modules.txt | 166 +-
Documentation/kdump/kdump.txt | 131 +-
Documentation/kdump/vmcoreinfo.txt | 59 +-
Documentation/kobject.txt | 2 +-
Documentation/ldm.txt | 3 +-
Documentation/livepatch/callbacks.txt | 12 +-
.../livepatch/cumulative-patches.txt | 14 +-
Documentation/livepatch/livepatch.txt | 56 +-
Documentation/livepatch/module-elf-format.txt | 211 +-
Documentation/livepatch/shadow-vars.txt | 65 +-
Documentation/locking/lockdep-design.txt | 41 +-
Documentation/locking/lockstat.txt | 219 +-
Documentation/locking/locktorture.txt | 105 +-
Documentation/locking/mutex-design.txt | 26 +-
Documentation/locking/rt-mutex-design.txt | 135 +-
Documentation/locking/rt-mutex.txt | 30 +-
Documentation/locking/spinlocks.txt | 32 +-
Documentation/locking/ww-mutex-design.txt | 82 +-
Documentation/m68k/kernel-options.txt | 319 +-
Documentation/memory-barriers.txt | 2 +-
Documentation/memory-devices/ti-emif.txt | 25 +-
Documentation/mic/mic_overview.txt | 6 +-
Documentation/mic/scif_overview.txt | 58 +-
Documentation/netlabel/cipso_ipv4.txt | 19 +-
Documentation/netlabel/introduction.txt | 16 +-
Documentation/netlabel/lsm_interface.txt | 16 +-
Documentation/numastat.txt | 1 -
Documentation/nvmem/nvmem.txt | 110 +-
Documentation/pcmcia/devicetable.txt | 4 +
Documentation/pcmcia/driver-changes.txt | 35 +-
Documentation/pcmcia/driver.txt | 18 +-
Documentation/pcmcia/locking.txt | 39 +-
Documentation/phy/samsung-usb2.txt | 60 +-
Documentation/pnp.txt | 11 +-
Documentation/power/apm-acpi.txt | 10 +-
Documentation/power/basic-pm-debugging.txt | 77 +-
Documentation/power/charger-manager.txt | 101 +-
Documentation/power/drivers-testing.txt | 5 +
Documentation/power/energy-model.txt | 101 +-
Documentation/power/freezing-of-tasks.txt | 91 +-
Documentation/power/interface.txt | 20 +-
Documentation/power/opp.txt | 175 +-
Documentation/power/pci.txt | 77 +-
Documentation/power/pm_qos_interface.txt | 127 +-
Documentation/power/power_supply_class.txt | 269 +-
Documentation/power/powercap/powercap.txt | 297 +-
Documentation/power/regulator/consumer.txt | 141 +-
Documentation/power/regulator/design.txt | 9 +-
Documentation/power/regulator/machine.txt | 47 +-
Documentation/power/regulator/overview.txt | 51 +-
Documentation/power/regulator/regulator.txt | 18 +-
Documentation/power/runtime_pm.txt | 234 +-
Documentation/power/s2ram.txt | 20 +-
.../power/suspend-and-cpuhotplug.txt | 42 +-
.../power/suspend-and-interrupts.txt | 2 +
Documentation/power/swsusp-and-swap-files.txt | 15 +-
Documentation/power/swsusp-dmcrypt.txt | 118 +-
Documentation/power/swsusp.txt | 639 ++--
Documentation/power/tricks.txt | 6 +-
Documentation/power/userland-swsusp.txt | 53 +-
Documentation/power/video.txt | 156 +-
Documentation/powerpc/DAWR-POWER9.txt | 10 +-
Documentation/powerpc/bootwrapper.txt | 28 +-
Documentation/powerpc/cpu_families.txt | 23 +-
Documentation/powerpc/cpu_features.txt | 6 +-
Documentation/powerpc/cxl.txt | 46 +-
Documentation/powerpc/cxlflash.txt | 8 +-
Documentation/powerpc/dscr.txt | 18 +-
.../powerpc/eeh-pci-error-recovery.txt | 108 +-
.../powerpc/firmware-assisted-dump.txt | 117 +-
Documentation/powerpc/hvcs.txt | 108 +-
Documentation/powerpc/isa-versions.rst | 13 +-
Documentation/powerpc/mpc52xx.txt | 12 +-
.../powerpc/pci_iov_resource_on_powernv.txt | 15 +-
Documentation/powerpc/pmu-ebb.txt | 1 +
Documentation/powerpc/ptrace.txt | 169 +-
Documentation/powerpc/qe_firmware.txt | 37 +-
Documentation/powerpc/syscall64-abi.txt | 29 +-
.../powerpc/transactional_memory.txt | 45 +-
Documentation/pps/pps.txt | 67 +-
Documentation/preempt-locking.txt | 2 +-
Documentation/pti/pti_intel_mid.txt | 135 +-
Documentation/ptp/ptp.txt | 26 +-
Documentation/rbtree.txt | 52 +-
Documentation/riscv/pmu.txt | 98 +-
Documentation/rtc.txt | 6 +-
Documentation/s390/3270.txt | 85 +-
Documentation/s390/CommonIO | 47 +-
Documentation/s390/DASD | 33 +-
Documentation/s390/Debugging390.txt | 2599 ++++++++++-------
Documentation/s390/cds.txt | 354 ++-
Documentation/s390/driver-model.txt | 179 +-
Documentation/s390/monreader.txt | 85 +-
Documentation/s390/qeth.txt | 36 +-
Documentation/s390/s390dbf.txt | 639 ++--
Documentation/s390/vfio-ap.txt | 487 +--
Documentation/s390/vfio-ccw.txt | 88 +-
Documentation/s390/zfcpdump.txt | 2 +
Documentation/scheduler/completion.txt | 38 +-
Documentation/scheduler/sched-arch.txt | 18 +-
Documentation/scheduler/sched-bwc.txt | 28 +-
Documentation/scheduler/sched-deadline.txt | 293 +-
Documentation/scheduler/sched-design-CFS.txt | 15 +-
Documentation/scheduler/sched-domains.txt | 8 +-
Documentation/scheduler/sched-energy.txt | 47 +-
Documentation/scheduler/sched-nice-design.txt | 6 +-
Documentation/scheduler/sched-rt-group.txt | 28 +-
Documentation/scheduler/sched-stats.txt | 35 +-
Documentation/security/tpm/xen-tpmfront.txt | 101 +-
Documentation/serial/README.cycladesZ | 5 +-
Documentation/serial/driver | 113 +-
Documentation/serial/moxa-smartio | 750 ++---
Documentation/serial/n_gsm.txt | 81 +-
Documentation/serial/rocket.txt | 144 +-
Documentation/serial/serial-iso7816.txt | 21 +-
Documentation/serial/serial-rs485.txt | 22 +-
Documentation/serial/tty.txt | 111 +-
Documentation/target/tcm_mod_builder.txt | 200 +-
Documentation/target/tcmu-design.txt | 268 +-
Documentation/timers/NO_HZ.txt | 40 +-
Documentation/timers/highres.txt | 11 +-
Documentation/timers/hpet.txt | 4 +-
Documentation/timers/hrtimers.txt | 6 +-
Documentation/timers/timekeeping.txt | 3 +-
Documentation/timers/timers-howto.txt | 15 +-
Documentation/trace/ftrace.rst | 1 +
Documentation/trace/histogram.rst | 86 +-
Documentation/usb/WUSB-Design-overview.txt | 56 +-
Documentation/usb/acm.txt | 156 +-
Documentation/usb/authorization.txt | 75 +-
Documentation/usb/chipidea.txt | 101 +-
Documentation/usb/dwc3.txt | 12 +-
Documentation/usb/ehci.txt | 42 +-
Documentation/usb/functionfs.txt | 17 +-
Documentation/usb/gadget-testing.txt | 609 ++--
Documentation/usb/gadget_configfs.txt | 302 +-
Documentation/usb/gadget_hid.txt | 175 +-
Documentation/usb/gadget_multi.txt | 43 +-
Documentation/usb/gadget_printer.txt | 155 +-
Documentation/usb/gadget_serial.txt | 73 +-
Documentation/usb/iuu_phoenix.txt | 34 +-
Documentation/usb/mass-storage.txt | 19 +-
Documentation/usb/misc_usbsevseg.txt | 9 +-
Documentation/usb/mtouchusb.txt | 42 +-
Documentation/usb/ohci.txt | 5 +-
Documentation/usb/rio.txt | 83 +-
Documentation/usb/usb-help.txt | 21 +-
Documentation/usb/usb-serial.txt | 203 +-
Documentation/usb/usbip_protocol.txt | 552 ++--
Documentation/usb/usbmon.txt | 100 +-
.../convert_drivers_to_kernel_api.txt | 109 +-
Documentation/watchdog/hpwdt.txt | 23 +-
Documentation/watchdog/mlx-wdt.txt | 24 +-
Documentation/watchdog/pcwd-watchdog.txt | 13 +-
Documentation/watchdog/watchdog-api.txt | 76 +-
.../watchdog/watchdog-kernel-api.txt | 89 +-
.../watchdog/watchdog-parameters.txt | 672 +++--
Documentation/watchdog/watchdog-pm.txt | 3 +
Documentation/watchdog/wdt.txt | 31 +-
Documentation/x86/amd-memory-encryption.txt | 10 +-
Documentation/x86/boot.txt | 578 ++--
Documentation/x86/earlyprintk.txt | 69 +-
Documentation/x86/entry_64.txt | 11 +-
Documentation/x86/exception-tables.txt | 245 +-
Documentation/x86/i386/IO-APIC.txt | 23 +-
Documentation/x86/intel_mpx.txt | 55 +-
Documentation/x86/microcode.txt | 51 +-
Documentation/x86/mtrr.txt | 442 +--
Documentation/x86/orc-unwinder.txt | 1 +
Documentation/x86/pat.txt | 217 +-
Documentation/x86/protection-keys.txt | 33 +-
Documentation/x86/pti.txt | 8 +-
Documentation/x86/resctrl_ui.txt | 621 ++--
Documentation/x86/tlb.txt | 12 +-
Documentation/x86/topology.txt | 26 +-
Documentation/x86/usb-legacy-support.txt | 33 +-
Documentation/x86/x86_64/5level-paging.txt | 14 +-
Documentation/x86/x86_64/boot-options.txt | 98 +-
Documentation/x86/x86_64/mm.txt | 212 +-
Documentation/x86/x86_64/uefi.txt | 21 +-
Documentation/x86/zero-page.txt | 67 +-
Documentation/xilinx/eemi.txt | 8 +-
Documentation/zorro.txt | 5 +-
MAINTAINERS | 2 +-
arch/arm64/kernel/kexec_image.c | 2 +-
arch/s390/include/asm/debug.h | 231 ++
drivers/cdrom/cdrom.c | 2 +-
include/linux/connector.h | 63 +-
433 files changed, 21459 insertions(+), 16370 deletions(-)
rename Documentation/{extcon/intel-int3496.txt => acpi/drivers/extcon-intel-int3496.txt} (66%)
delete mode 100644 Documentation/arm/SA1100/empeg
delete mode 100644 Documentation/cdrom/Makefile
delete mode 100644 Documentation/cdrom/cdrom-standard.tex
create mode 100644 Documentation/cdrom/cdrom-standard.txtSignature · 1 line
2.20.1
PATCH 1/57 docs: trace: fix some Sphinx warnings
There are some warnings produced when building trace. Fix them.
--- Documentation/trace/ftrace.rst | 1 + Documentation/trace/histogram.rst | 86 ++++++++++++++++--------------- 2 files changed, 45 insertions(+), 42 deletions(-)
Documentation/trace/ftrace.rst +1 -0
@@ -1435,6 +1435,7 @@ trace has provided some very helpful debugging information. If we prefer function graph output instead of function, we can set display-graph option:: + with echo 1 > options/display-graph # tracer: irqsoff
Documentation/trace/histogram.rst +44 -42
118 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 2/57 docs: acpi: convert text files to ReST
In reply to Mauro Carvalho ChehabMost of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.
--- Documentation/acpi/DSD-properties-rules.txt | 4 +- Documentation/acpi/acpi-lid.txt | 37 +- Documentation/acpi/aml-debugger.txt | 31 +- Documentation/acpi/apei/einj.txt | 59 ++-- Documentation/acpi/apei/output_format.txt | 247 +++++++------- Documentation/acpi/cppc_sysfs.txt | 52 +-- Documentation/acpi/debug.txt | 20 +- .../acpi/dsd/data-node-references.txt | 11 +- Documentation/acpi/dsd/graph.txt | 24 +- Documentation/acpi/dsd/leds.txt | 18 +- Documentation/acpi/dsdt-override.txt | 4 +- Documentation/acpi/enumeration.txt | 42 +-- Documentation/acpi/gpio-properties.txt | 42 +-- Documentation/acpi/i2c-muxes.txt | 21 +- Documentation/acpi/initrd_table_override.txt | 90 ++--- Documentation/acpi/linuxized-acpica.txt | 58 ++-- Documentation/acpi/lpit.txt | 8 +- Documentation/acpi/method-customizing.txt | 48 ++- Documentation/acpi/method-tracing.txt | 132 ++++--- Documentation/acpi/namespace.txt | 323 +++++++++--------- Documentation/acpi/osi.txt | 3 +- Documentation/acpi/scan_handlers.txt | 9 +- Documentation/acpi/ssdt-overlays.txt | 128 +++---- Documentation/acpi/video_extension.txt | 16 +- 24 files changed, 794 insertions(+), 633 deletions(-)
Documentation/acpi/DSD-properties-rules.txt +3 -1
@@ -1,5 +1,6 @@ +================================== _DSD Device Properties Usage Rules ----------------------------------- +================================== Properties, Property Sets and Property Subsets ----------------------------------------------
@@ -94,4 +95,5 @@ References ---------- [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf + [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
Documentation/acpi/acpi-lid.txt +27 -10
@@ -1,10 +1,14 @@ +========================================================= Special Usage Model of the ACPI Control Method Lid Device +========================================================= Copyright (C) 2016, Intel Corporation -Author: Lv Zheng <[email protected]> +:Author: Lv Zheng <[email protected]> -Abstract: + +Abstract +======== Platforms containing lids convey lid state (open/close) to OSPMs using a control method lid device. To implement this, the AML tables issue
@@ -20,6 +24,7 @@ expections of the Linux ACPI lid device driver. 1. Restrictions of the returning value of the _LID control method +================================================================= The _LID control method is described to return the "current" lid state. However the word of "current" has ambiguity, some buggy AML tables return
@@ -31,6 +36,8 @@ with cached value, the initial returning value is likely not reliable. There are platforms always retun "closed" as initial lid state. 2. Restrictions of the lid state change notifications +===================================================== + There are buggy AML tables never notifying when the lid device state is changed to "opened". Thus the "opened" notification is not guaranteed. But
@@ -40,26 +47,32 @@ trigger some system power saving operations on Windows. Since it is fully tested, it is reliable from all AML tables. 3. Expections for the userspace users of the ACPI lid device driver +=================================================================== The ACPI button driver exports the lid state to the userspace via the following file: + /proc/acpi/button/lid/LID0/state + This file actually calls the _LID control method described above. And given the previous explanation, it is not reliable enough on some platforms. So it is advised for the userspace program to not to solely rely on this file to determine the actual lid state. The ACPI button driver emits the following input event to the userspace: - SW_LID -The ACPI lid device driver is implemented to try to deliver the platform -triggered events to the userspace. However, given the fact that the buggy -firmware cannot make sure "opened"/"closed" events are paired, the ACPI -button driver uses the following 3 modes in order not to trigger issues. + +SW_LID + The ACPI lid device driver is implemented to try to deliver the platform + triggered events to the userspace. However, given the fact that the buggy + firmware cannot make sure "opened"/"closed" events are paired, the ACPI + button driver uses the following 3 modes in order not to trigger issues. If the userspace hasn't been prepared to ignore the unreliable "opened" events and the unreliable initial state notification, Linux users can use the following kernel parameters to handle the possible issues: -A. button.lid_init_state=method: + +A. `button.lid_init_state=method`: + When this option is specified, the ACPI button driver reports the initial lid state using the returning value of the _LID control method and whether the "opened"/"closed" events are paired fully relies on the
@@ -69,7 +82,9 @@ A. button.lid_init_state=method: notification is missing. This option is the default behavior during the period the userspace isn't ready to handle the buggy AML tables. -B. button.lid_init_state=open: + +B. `button.lid_init_state=open`: + When this option is specified, the ACPI button driver always reports the initial lid state as "opened" and whether the "opened"/"closed" events are paired fully relies on the firmware implementation.
@@ -80,7 +95,9 @@ B. button.lid_init_state=open: If the userspace has been prepared to ignore the unreliable "opened" events and the unreliable initial state notification, Linux users should always use the following kernel parameter: -C. button.lid_init_state=ignore: + +C. `button.lid_init_state=ignore`: + When this option is specified, the ACPI button driver never reports the initial lid state and there is a compensation mechanism implemented to ensure that the reliable "closed" notifications can always be delievered
Documentation/acpi/aml-debugger.txt +17 -14
@@ -1,6 +1,9 @@ +================ The AML Debugger +================ Copyright (C) 2016, Intel Corporation + Author: Lv Zheng <[email protected]>
@@ -10,16 +13,16 @@ kernel. 1. Build the debugger The following kernel configuration items are required to enable the AML - debugger interface from the Linux kernel: + debugger interface from the Linux kernel:: - CONFIG_ACPI_DEBUGGER=y - CONFIG_ACPI_DEBUGGER_USER=m + CONFIG_ACPI_DEBUGGER=y + CONFIG_ACPI_DEBUGGER_USER=m The userspace utilities can be built from the kernel source tree using - the following commands: + the following commands:: - $ cd tools - $ make acpi + $ cd tools + $ make acpi The resultant userspace tool binary is then located at:
@@ -31,11 +34,11 @@ kernel. 2. Start the userspace debugger interface After booting the kernel with the debugger built-in, the debugger can be - started by using the following commands: + started by using the following commands:: - # mount -t debugfs none /sys/kernel/debug - # modprobe acpi_dbg - # tools/power/acpi/acpidbg + # mount -t debugfs none /sys/kernel/debug + # modprobe acpi_dbg + # tools/power/acpi/acpidbg That spawns the interactive AML debugger environment where you can execute debugger commands.
@@ -51,9 +54,9 @@ kernel. 3. Stop the userspace debugger interface The interactive debugger interface can be closed by pressing Ctrl+C or using - the "quit" or "exit" commands. When finished, unload the module with: + the "quit" or "exit" commands. When finished, unload the module with:: - # rmmod acpi_dbg + # rmmod acpi_dbg The module unloading may fail if there is an acpidbg instance running.
@@ -61,6 +64,6 @@ kernel. It may be useful to run the AML debugger in a test script. "acpidbg" supports this in a special "batch" mode. For example, the following command outputs - the entire ACPI namespace: + the entire ACPI namespace:: - # acpidbg -b "namespace" + # acpidbg -b "namespace"
Documentation/acpi/apei/einj.txt +31 -28
109 lines not on this page · raw message
Documentation/acpi/apei/output_format.txt +124 -123
252 lines not on this page · raw message
Documentation/acpi/cppc_sysfs.txt +28 -24
77 lines not on this page · raw message
Documentation/acpi/debug.txt +11 -9
@@ -1,4 +1,6 @@ - ACPI Debug Output +================= +ACPI Debug Output +================= The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
@@ -33,7 +35,7 @@ to /sys/module/acpi/parameters/debug_layer. The possible components are defined in include/acpi/acoutput.h and include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer -shows the supported mask values, currently these: +shows the supported mask values, currently these:: ACPI_UTILITIES 0x00000001 ACPI_HARDWARE 0x00000002
@@ -81,7 +83,7 @@ to /sys/module/acpi/parameters/debug_level. The possible levels are defined in include/acpi/acoutput.h. Reading /sys/module/acpi/parameters/debug_level shows the supported mask values, -currently these: +currently these:: ACPI_LV_INIT 0x00000001 ACPI_LV_DEBUG_OBJECT 0x00000002
@@ -115,7 +117,7 @@ currently these: Examples -------- -For example, drivers/acpi/bus.c contains this: +For example, drivers/acpi/bus.c contains this:: #define _COMPONENT ACPI_BUS_COMPONENT ...
@@ -127,22 +129,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO definition.) Enable all AML "Debug" output (stores to the Debug object while interpreting -AML) during boot: +AML) during boot:: acpi.debug_layer=0xffffffff acpi.debug_level=0x2 -Enable PCI and PCI interrupt routing debug messages: +Enable PCI and PCI interrupt routing debug messages:: acpi.debug_layer=0x400000 acpi.debug_level=0x4 -Enable all ACPI hardware-related messages: +Enable all ACPI hardware-related messages:: acpi.debug_layer=0x2 acpi.debug_level=0xffffffff -Enable all ACPI_DB_INFO messages after boot: +Enable all ACPI_DB_INFO messages after boot:: # echo 0x4 > /sys/module/acpi/parameters/debug_level -Show all valid component values: +Show all valid component values:: # cat /sys/module/acpi/parameters/debug_layer
Documentation/acpi/dsd/data-node-references.txt +9 -2
@@ -1,4 +1,9 @@ +==================== +Data Node References +==================== + Copyright (C) 2018 Intel Corporation + Author: Sakari Ailus <[email protected]>
@@ -30,6 +35,8 @@ extension key. Example ------- +:: + In the ASL snippet below, the "reference" _DSD property [2] contains a device object reference to DEV0 and under that device object, a hierarchical data extension key "node@1" referring to the NOD1 object
@@ -81,9 +88,9 @@ References ---------- [1] Hierarchical Data Extension UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, + http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, referenced 2018-07-17. [2] Device Properties UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, referenced 2016-10-04.
Documentation/acpi/dsd/graph.txt +14 -10
@@ -1,4 +1,6 @@ +====== Graphs +====== _DSD
@@ -40,7 +42,7 @@ All port nodes are located under the device's "_DSD" node in the hierarchical data extension tree. The data extension related to each port node must begin with "port" and must be followed by the "@" character and the number of the port as its key. The target object it refers to should be called "PRTX", where "X" is -the number of the port. An example of such a package would be: +the number of the port. An example of such a package would be:: Package() { "port@4", PRT4 }
@@ -49,7 +51,7 @@ data extension key of the endpoint nodes must begin with "endpoint" and must be followed by the "@" character and the number of the endpoint. The object it refers to should be called "EPXY", where "X" is the number of the port and "Y" is the number of the endpoint. An example of such a -package would be: +package would be:: Package() { "endpoint@0", EP40 }
@@ -65,7 +67,7 @@ The endpoint reference uses property extension with "remote-endpoint" property name followed by a reference in the same package. Such references consist of the the remote device reference, the first package entry of the port data extension reference under the device and finally the first package entry of the endpoint -data extension reference under the port. Individual references thus appear as: +data extension reference under the port. Individual references thus appear as:: Package() { device, "port@X", "endpoint@Y" }
@@ -75,7 +77,7 @@ endpoint. The references to endpoints must be always done both ways, to the remote endpoint and back from the referred remote endpoint node. -A simple example of this is show below: +A simple example of this is show below:: Scope (\_SB.PCI0.I2C2) {
@@ -151,23 +153,25 @@ References ---------- [1] _DSD (Device Specific Data) Implementation Guide. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>, + http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, referenced 2016-10-03. -[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03. +[2] Devicetree. + http://www.devicetree.org, referenced 2016-10-03. -[3] Documentation/devicetree/bindings/graph.txt +[3] Linux Kernel device tree graph rules. + Documentation/devicetree/bindings/graph.txt [4] Device Properties UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, referenced 2016-10-04. [5] Hierarchical Data Extension UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, + URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, referenced 2016-10-04. [6] Advanced Configuration and Power Interface Specification. - <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>, + http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, referenced 2016-10-04. [7] _DSD Device Properties Usage Rules.
Documentation/acpi/dsd/leds.txt +12 -6
@@ -1,4 +1,6 @@ +======================================== Describing and referring to LEDs in ACPI +======================================== Individual LEDs are described by hierarchical data extension [6] nodes under the device node, the LED driver chip. The "reg" property in the LED specific nodes
@@ -26,7 +28,7 @@ followed by the referred object name. That object shall be named "LED" followed by the number of the LED. An ASL example of a camera sensor device and a LED driver device for two LEDs. -Objects not relevant for LEDs or the references to them have been omitted. +Objects not relevant for LEDs or the references to them have been omitted:: Device (LED) {
@@ -72,10 +74,14 @@ Objects not relevant for LEDs or the references to them have been omitted. where - LED LED driver device - LED0 First LED - LED1 Second LED - SEN Camera sensor device (or another device the LED is + LED + LED driver device + LED0 + First LED + LED1 + Second LED + SEN + Camera sensor device (or another device the LED is related to) [1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21.
@@ -96,4 +102,4 @@ where <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, referenced 2019-02-21. -[7] Documentation/acpi/dsd/data-node-reference.txt +[7] Documentation/acpi/dsd/data-node-references.txt
Documentation/acpi/dsdt-override.txt +3 -1
@@ -1,4 +1,6 @@ -Linux supports a method of overriding the BIOS DSDT: +=================================================== +Linux supports a method of overriding the BIOS DSDT +=================================================== CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel.
Documentation/acpi/enumeration.txt +22 -20
139 lines not on this page · raw message
Documentation/acpi/gpio-properties.txt +23 -19
111 lines not on this page · raw message
Documentation/acpi/i2c-muxes.txt +11 -10
@@ -1,20 +1,21 @@ +============== ACPI I2C Muxes --------------- +============== Describing an I2C device hierarchy that includes I2C muxes requires an ACPI Device () scope per mux channel. -Consider this topology: +Consider this topology:: -+------+ +------+ -| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50) -| | | 0x70 |--CH01--> i2c client B (0x50) -+------+ +------+ + +------+ +------+ + | SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50) + | | | 0x70 |--CH01--> i2c client B (0x50) + +------+ +------+ -which corresponds to the following ASL: +which corresponds to the following ASL:: -Device (SMB1) -{ + Device (SMB1) + { Name (_HID, ...) Device (MUX0) {
@@ -55,4 +56,4 @@ Device (SMB1) } } } -} + }
Documentation/acpi/initrd_table_override.txt +48 -42
116 lines not on this page · raw message
Documentation/acpi/linuxized-acpica.txt +38 -20
157 lines not on this page · raw message
Documentation/acpi/lpit.txt +7 -1
@@ -1,3 +1,7 @@ +===================== +Low Power Idle states +===================== + To enumerate platform Low Power Idle states, Intel platforms are using “Low Power Idle Table” (LPIT). More details about this table can be downloaded from:
@@ -8,11 +12,13 @@ Residencies for each low power state can be read via FFH On platforms supporting S0ix sleep states, there can be two types of residencies: + - CPU PKG C10 (Read via FFH interface) - Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface) The following attributes are added dynamically to the cpuidle -sysfs attribute group: +sysfs attribute group:: + /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
Documentation/acpi/method-customizing.txt +31 -17
93 lines not on this page · raw message
Documentation/acpi/method-tracing.txt +81 -51
193 lines not on this page · raw message
Documentation/acpi/namespace.txt +170 -153
414 lines not on this page · raw message
Documentation/acpi/osi.txt +2 -1
@@ -1,5 +1,6 @@ +========================== ACPI _OSI and _REV methods --------------------------- +========================== An ACPI BIOS can use the "Operating System Interfaces" method (_OSI) to find out what the operating system supports. Eg. If BIOS
Documentation/acpi/scan_handlers.txt +6 -3
@@ -1,6 +1,9 @@ +================== ACPI Scan Handlers +================== Copyright (C) 2012, Intel Corporation + Author: Rafael J. Wysocki <[email protected]> During system initialization and ACPI-based device hot-add, the ACPI namespace
@@ -30,14 +33,14 @@ to configure that link so that the kernel can use it. Those additional configuration tasks usually depend on the type of the hardware component represented by the given device node which can be determined on the basis of the device node's hardware ID (HID). They are performed by objects -called ACPI scan handlers represented by the following structure: +called ACPI scan handlers represented by the following structure:: -struct acpi_scan_handler { + struct acpi_scan_handler { const struct acpi_device_id *ids; struct list_head list_node; int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id); void (*detach)(struct acpi_device *dev); -}; + }; where ids is the list of IDs of device nodes the given handler is supposed to take care of, list_node is the hook to the global list of ACPI scan handlers
Documentation/acpi/ssdt-overlays.txt +67 -61
184 lines not on this page · raw message
Documentation/acpi/video_extension.txt +9 -7
@@ -1,5 +1,6 @@ +===================== ACPI video extensions -~~~~~~~~~~~~~~~~~~~~~ +===================== This driver implement the ACPI Extensions For Display Adapters for integrated graphics devices on motherboard, as specified in ACPI 2.0
@@ -32,10 +33,10 @@ type: firmware Note that ACPI video backlight driver will always use index for brightness, actual_brightness and max_brightness. So if we have -the following _BCL package: +the following _BCL package:: -Method (_BCL, 0, NotSerialized) -{ + Method (_BCL, 0, NotSerialized) + { Return (Package (0x0C) { 0x64,
@@ -51,7 +52,7 @@ Method (_BCL, 0, NotSerialized) 0x5A, 0x64 }) -} + } The first two levels are for when laptop are on AC or on battery and are not used by Linux currently. The remaining 10 levels are supported levels
@@ -65,10 +66,11 @@ inclusive. 2 Notify user space about hotkey event There are generally two cases for hotkey event reporting: + i) For some laptops, when user presses the hotkey, a scancode will be generated and sent to user space through the input device created by the keyboard driver as a key type input event, with proper remap, the - following key code will appear to user space: + following key code will appear to user space:: EV_KEY, KEY_BRIGHTNESSUP EV_KEY, KEY_BRIGHTNESSDOWN
@@ -82,7 +84,7 @@ ii) For some laptops, the press of the hotkey will not generate the about the event. The event value is defined in the ACPI spec. ACPI video driver will generate an key type input event according to the notify value it received and send the event to user space through the - input device it created: + input device it created:: event keycode 0x86 KEY_BRIGHTNESSUP
Signature · 1 line
2.20.1
Rafael J. Wysocki
maintainerRe: [PATCH 02/57] docs: acpi: convert text files to ReST
Quoted 5 lines · Mauro Carvalho Chehab
Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.
There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2
I'd prefer that one to continue, honestly.
Thanks,
Rafael
Re: [PATCH 02/57] docs: acpi: convert text files to ReST
Em Tue, 16 Apr 2019 10:17:11 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:
Quoted 8 lines
Quoted 5 lines · Mauro Carvalho Chehab
Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.
Quoted 4 lines
There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2I'd prefer that one to continue, honestly.
Agreed. I didn't notice the patchset.
Btw, please notice patch 11/57:
Subject: [PATCH 11/57] docs: extcon: move it to acpi dir and convert it to ReST
IMO, it makes sense to move the extcon driver to ACPI, as it sounds to be just another ACPI driver.
Thanks,
Mauro
Rafael J. Wysocki
maintainerRe: [PATCH 02/57] docs: acpi: convert text files to ReST
Quoted 17 lines · Mauro Carvalho Chehab
Em Tue, 16 Apr 2019 10:17:11 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:Quoted 8 lines
Quoted 5 lines · Mauro Carvalho Chehab
Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.
Quoted 4 lines
There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2I'd prefer that one to continue, honestly.
Quoted 8 lines
Agreed. I didn't notice the patchset.
Btw, please notice patch 11/57:
Subject: [PATCH 11/57] docs: extcon: move it to acpi dir and convert it to ReST
IMO, it makes sense to move the extcon driver to ACPI, as it sounds to be just another ACPI driver.
But that can be done later, on top of the Changbin Du's changes.
Thanks,
Rafael
Re: [PATCH 02/57] docs: acpi: convert text files to ReST
In reply to Rafael J. WysockiQuoted 11 lines · Rafael J. Wysocki
Quoted 5 lines · Mauro Carvalho Chehab
Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.
There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2
I will update the serias asap. I am just a little busy these days. My conversion includes pci, acpi and x86, others are not touched.
Quoted 4 lines
I'd prefer that one to continue, honestly.
Thanks,
Rafael
Signature · 2 lines
Cheers, Changbin Du
Re: [PATCH 02/57] docs: acpi: convert text files to ReST
Em Tue, 16 Apr 2019 14:55:19 +0000
Changbin Du <[email protected]> escreveu:
Quoted 9 lines · Rafael J. Wysocki
Quoted 8 lines
Quoted 5 lines · Mauro Carvalho Chehab
Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.
Quoted 5 lines
Quoted 3 lines
There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2I will update the serias asap. I am just a little busy these days. My conversion includes pci, acpi and x86, others are not touched.
Ok, I sent a new patch series without pci, acpi and x86.
While these aren't merged upstream, I'm keeping my old patches on my tree:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=805b16dd336dd3c27733f02ec8164b2a182972a3 https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=c950031ccb87ea14ff4c56f2433072d580db3572 https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=4f8afce866dcd8067206b3ee493ed0b682694f49
If you find anything there that would be interesting for your series, feel free to pick from them. Everything is based on linux-next.
Thanks,
Mauro
PATCH 3/57 docs: aoe: convert text files to ReST
In reply to Mauro Carvalho ChehabThere are only two files within Documentation/aoe dir that are documentation. The remaining ones are examples and shell scripts.
Convert the two AoE files to ReST format.
--- Documentation/aoe/aoe.txt | 63 +++++++++++++++++++++----------------- Documentation/aoe/todo.txt | 3 ++ Documentation/aoe/udev.txt | 2 +- 3 files changed, 39 insertions(+), 29 deletions(-)
Documentation/aoe/aoe.txt +35 -28
@@ -1,3 +1,6 @@ +Introduction +============ + ATA over Ethernet is a network protocol that provides simple access to block storage on the LAN.
@@ -22,7 +25,8 @@ document the use of the driver and are not necessary if you install the aoetools. -CREATING DEVICE NODES +Creating Device Nodes +===================== Users of udev should find the block device nodes created automatically, but to create all the necessary device nodes, use the
@@ -38,7 +42,8 @@ CREATING DEVICE NODES confusing when an AoE device is not present the first time the a command is run but appears a second later. -USING DEVICE NODES +Using Device Nodes +================== "cat /dev/etherd/err" blocks, waiting for error diagnostic output, like any retransmitted packets.
@@ -55,7 +60,7 @@ USING DEVICE NODES by sysfs counterparts. Using the commands in aoetools insulates users from these implementation details. - The block devices are named like this: + The block devices are named like this:: e{shelf}.{slot} e{shelf}.{slot}p{part}
@@ -64,7 +69,8 @@ USING DEVICE NODES first shelf (shelf address zero). That's the whole disk. The first partition on that disk would be "e0.2p1". -USING SYSFS +Using sysfs +=========== Each aoe block device in /sys/block has the extra attributes of state, mac, and netif. The state attribute is "up" when the device
@@ -78,29 +84,29 @@ USING SYSFS There is a script in this directory that formats this information in a convenient way. Users with aoetools should use the aoe-stat - command. + command:: - root@makki root# sh Documentation/aoe/status.sh - e10.0 eth3 up - e10.1 eth3 up - e10.2 eth3 up - e10.3 eth3 up - e10.4 eth3 up - e10.5 eth3 up - e10.6 eth3 up - e10.7 eth3 up - e10.8 eth3 up - e10.9 eth3 up - e4.0 eth1 up - e4.1 eth1 up - e4.2 eth1 up - e4.3 eth1 up - e4.4 eth1 up - e4.5 eth1 up - e4.6 eth1 up - e4.7 eth1 up - e4.8 eth1 up - e4.9 eth1 up + root@makki root# sh Documentation/aoe/status.sh + e10.0 eth3 up + e10.1 eth3 up + e10.2 eth3 up + e10.3 eth3 up + e10.4 eth3 up + e10.5 eth3 up + e10.6 eth3 up + e10.7 eth3 up + e10.8 eth3 up + e10.9 eth3 up + e4.0 eth1 up + e4.1 eth1 up + e4.2 eth1 up + e4.3 eth1 up + e4.4 eth1 up + e4.5 eth1 up + e4.6 eth1 up + e4.7 eth1 up + e4.8 eth1 up + e4.9 eth1 up Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver option discussed below) instead of /dev/etherd/interfaces to limit
@@ -113,12 +119,13 @@ USING SYSFS for this purpose. You can also directly use the /dev/etherd/discover special file described above. -DRIVER OPTIONS +Driver Options +============== There is a boot option for the built-in aoe driver and a corresponding module parameter, aoe_iflist. Without this option, all network interfaces may be used for ATA over Ethernet. Here is a - usage example for the module parameter. + usage example for the module parameter:: modprobe aoe_iflist="eth1 eth3"
Documentation/aoe/todo.txt +3 -0
@@ -1,3 +1,6 @@ +TODO +==== + There is a potential for deadlock when allocating a struct sk_buff for data that needs to be written out to aoe storage. If the data is being written from a dirty page in order to free that page, and if
Documentation/aoe/udev.txt +1 -1
@@ -11,7 +11,7 @@ # udev_rules="/etc/udev/rules.d/" # bash# ls /etc/udev/rules.d/ # 10-wacom.rules 50-udev.rules -# bash# cp /path/to/linux-2.6.xx/Documentation/aoe/udev.txt \ +# bash# cp /path/to/linux/Documentation/aoe/udev.txt \ # /etc/udev/rules.d/60-aoe.rules #
Signature · 1 line
2.20.1
PATCH 4/57 docs: arm64: convert documentation to ReST format
In reply to Mauro Carvalho ChehabThe documentation is in pretty much ReST format. Just some small adjustments in order to fix tables and to make Sphinx to recognize certain format blocks are required.
--- Documentation/arm64/acpi_object_usage.txt | 288 ++++++++++++------ Documentation/arm64/arm-acpi.txt | 153 +++++----- Documentation/arm64/booting.txt | 91 ++++-- Documentation/arm64/cpu-feature-registers.txt | 190 ++++++------ Documentation/arm64/elf_hwcaps.txt | 50 +-- Documentation/arm64/hugetlbpage.txt | 7 +- Documentation/arm64/legacy_instructions.txt | 43 ++- Documentation/arm64/memory.txt | 91 +++--- .../arm64/pointer-authentication.txt | 2 + Documentation/arm64/silicon-errata.txt | 63 +++- Documentation/arm64/sve.txt | 10 +- Documentation/arm64/tagged-pointers.txt | 6 +- arch/arm64/kernel/kexec_image.c | 2 +- 13 files changed, 595 insertions(+), 401 deletions(-)
Documentation/arm64/acpi_object_usage.txt +202 -86
@@ -1,5 +1,7 @@ +=========== ACPI Tables ------------ +=========== + The expectations of individual ACPI tables are discussed in the list that follows.
@@ -11,54 +13,71 @@ outside of the UEFI Forum (see Section 5.2.6 of the specification). For ACPI on arm64, tables also fall into the following categories: - -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT + - Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT - -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT + - Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT - -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT, + - Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT, MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO, TCPA, TPM2, UEFI, XENV - -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT, + - Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT, MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT +====== ======================================================================== Table Usage for ARMv8 Linux ------ ---------------------------------------------------------------- +====== ======================================================================== BERT Section 18.3 (signature == "BERT") - == Boot Error Record Table == + + **Boot Error Record Table** + Must be supplied if RAS support is provided by the platform. It is recommended this table be supplied. BOOT Signature Reserved (signature == "BOOT") - == simple BOOT flag table == + + **simple BOOT flag table** + Microsoft only table, will not be supported. BGRT Section 5.2.22 (signature == "BGRT") - == Boot Graphics Resource Table == + + **Boot Graphics Resource Table** + Optional, not currently supported, with no real use-case for an ARM server. CPEP Section 5.2.18 (signature == "CPEP") - == Corrected Platform Error Polling table == + + **Corrected Platform Error Polling table** + Optional, not currently supported, and not recommended until such time as ARM-compatible hardware is available, and the specification suitably modified. CSRT Signature Reserved (signature == "CSRT") - == Core System Resources Table == + + **Core System Resources Table** + Optional, not currently supported. DBG2 Signature Reserved (signature == "DBG2") - == DeBuG port table 2 == + + **DeBuG port table 2** + License has changed and should be usable. Optional if used instead of earlycon=<device> on the command line. DBGP Signature Reserved (signature == "DBGP") - == DeBuG Port table == + + **DeBuG Port table** + Microsoft only table, will not be supported. DSDT Section 5.2.11.1 (signature == "DSDT") - == Differentiated System Description Table == + + **Differentiated System Description Table** + A DSDT is required; see also SSDT. ACPI tables contain only one DSDT but can contain one or more SSDTs,
@@ -66,22 +85,30 @@ DSDT Section 5.2.11.1 (signature == "DSDT") but cannot modify or replace anything in the DSDT. DMAR Signature Reserved (signature == "DMAR") - == DMA Remapping table == + + **DMA Remapping table** + x86 only table, will not be supported. DRTM Signature Reserved (signature == "DRTM") - == Dynamic Root of Trust for Measurement table == + + **Dynamic Root of Trust for Measurement table** + Optional, not currently supported. ECDT Section 5.2.16 (signature == "ECDT") - == Embedded Controller Description Table == + + **Embedded Controller Description Table** + Optional, not currently supported, but could be used on ARM if and only if one uses the GPE_BIT field to represent an IRQ number, since there are no GPE blocks defined in hardware reduced mode. This would need to be modified in the ACPI specification. EINJ Section 18.6 (signature == "EINJ") - == Error Injection table == + + **Error Injection table** + This table is very useful for testing platform response to error conditions; it allows one to inject an error into the system as if it had actually occurred. However, this table should not be
@@ -89,27 +116,35 @@ EINJ Section 18.6 (signature == "EINJ") and executed with the ACPICA tools only during testing. ERST Section 18.5 (signature == "ERST") - == Error Record Serialization Table == + + **Error Record Serialization Table** + On a platform supports RAS, this table must be supplied if it is not UEFI-based; if it is UEFI-based, this table may be supplied. When this table is not present, UEFI run time service will be utilized to save and retrieve hardware error information to and from a persistent store. ETDT Signature Reserved (signature == "ETDT") - == Event Timer Description Table == + + **Event Timer Description Table** + Obsolete table, will not be supported. FACS Section 5.2.10 (signature == "FACS") - == Firmware ACPI Control Structure == + + **Firmware ACPI Control Structure** + It is unlikely that this table will be terribly useful. If it is provided, the Global Lock will NOT be used since it is not part of the hardware reduced profile, and only 64-bit address fields will be considered valid. FADT Section 5.2.9 (signature == "FACP") - == Fixed ACPI Description Table == + + **Fixed ACPI Description Table** Required for arm64. + The HW_REDUCED_ACPI flag must be set. All of the fields that are to be ignored when HW_REDUCED_ACPI is set are expected to be set to zero.
@@ -118,22 +153,28 @@ FADT Section 5.2.9 (signature == "FACP") used, not FIRMWARE_CTRL. If PSCI is used (as is recommended), make sure that ARM_BOOT_ARCH is - filled in properly -- that the PSCI_COMPLIANT flag is set and that + filled in properly - that the PSCI_COMPLIANT flag is set and that PSCI_USE_HVC is set or unset as needed (see table 5-37). For the DSDT that is also required, the X_DSDT field is to be used, not the DSDT field. FPDT Section 5.2.23 (signature == "FPDT") - == Firmware Performance Data Table == + + **Firmware Performance Data Table** + Optional, not currently supported. GTDT Section 5.2.24 (signature == "GTDT") - == Generic Timer Description Table == + + **Generic Timer Description Table** + Required for arm64. HEST Section 18.3.2 (signature == "HEST") - == Hardware Error Source Table == + + **Hardware Error Source Table** + ARM-specific error sources have been defined; please use those or the PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER Bridge), or use type 9 (Generic Hardware Error Source). Firmware first
@@ -144,122 +185,174 @@ HEST Section 18.3.2 (signature == "HEST") is recommended this table be supplied. HPET Signature Reserved (signature == "HPET") - == High Precision Event timer Table == + + **High Precision Event timer Table** + x86 only table, will not be supported. IBFT Signature Reserved (signature == "IBFT") - == iSCSI Boot Firmware Table == + + **iSCSI Boot Firmware Table** + Microsoft defined table, support TBD. IORT Signature Reserved (signature == "IORT") - == Input Output Remapping Table == + + **Input Output Remapping Table** + arm64 only table, required in order to describe IO topology, SMMUs, and GIC ITSs, and how those various components are connected together, such as identifying which components are behind which SMMUs/ITSs. This table will only be required on certain SBSA platforms (e.g., - when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it + when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it remains optional. IVRS Signature Reserved (signature == "IVRS") - == I/O Virtualization Reporting Structure == + + **I/O Virtualization Reporting Structure** + x86_64 (AMD) only table, will not be supported. LPIT Signature Reserved (signature == "LPIT") - == Low Power Idle Table == + + **Low Power Idle Table** + x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor descriptions and power states on ARM platforms should use the DSDT and define processor container devices (_HID ACPI0010, Section 8.4, and more specifically 8.4.3 and and 8.4.4). MADT Section 5.2.12 (signature == "APIC") - == Multiple APIC Description Table == + + **Multiple APIC Description Table** + Required for arm64. Only the GIC interrupt controller structures should be used (types 0xA - 0xF). MCFG Signature Reserved (signature == "MCFG") - == Memory-mapped ConFiGuration space == + + **Memory-mapped ConFiGuration space** + If the platform supports PCI/PCIe, an MCFG table is required. MCHI Signature Reserved (signature == "MCHI") - == Management Controller Host Interface table == + + **Management Controller Host Interface table** + Optional, not currently supported. MPST Section 5.2.21 (signature == "MPST") - == Memory Power State Table == + + **Memory Power State Table** + Optional, not currently supported. MSCT Section 5.2.19 (signature == "MSCT") - == Maximum System Characteristic Table == + + **Maximum System Characteristic Table** + Optional, not currently supported. MSDM Signature Reserved (signature == "MSDM") - == Microsoft Data Management table == + + **Microsoft Data Management table** + Microsoft only table, will not be supported. NFIT Section 5.2.25 (signature == "NFIT") - == NVDIMM Firmware Interface Table == + + **NVDIMM Firmware Interface Table** + Optional, not currently supported. OEMx Signature of "OEMx" only - == OEM Specific Tables == + + **OEM Specific Tables** + All tables starting with a signature of "OEM" are reserved for OEM use. Since these are not meant to be of general use but are limited to very specific end users, they are not recommended for use and are not supported by the kernel for arm64. PCCT Section 14.1 (signature == "PCCT) - == Platform Communications Channel Table == + + **Platform Communications Channel Table** + Recommend for use on arm64; use of PCC is recommended when using CPPC to control performance and power for platform processors. PMTT Section 5.2.21.12 (signature == "PMTT") - == Platform Memory Topology Table == + + **Platform Memory Topology Table** + Optional, not currently supported. PSDT Section 5.2.11.3 (signature == "PSDT") - == Persistent System Description Table == + + **Persistent System Description Table** + Obsolete table, will not be supported. RASF Section 5.2.20 (signature == "RASF") - == RAS Feature table == + + **RAS Feature table** + Optional, not currently supported. RSDP Section 5.2.5 (signature == "RSD PTR") - == Root System Description PoinTeR == + + **Root System Description PoinTeR** + Required for arm64. RSDT Section 5.2.7 (signature == "RSDT") - == Root System Description Table == + + **Root System Description Table** + Since this table can only provide 32-bit addresses, it is deprecated on arm64, and will not be used. If provided, it will be ignored. SBST Section 5.2.14 (signature == "SBST") - == Smart Battery Subsystem Table == + + **Smart Battery Subsystem Table** + Optional, not currently supported. SLIC Signature Reserved (signature == "SLIC") - == Software LIcensing table == + + **Software LIcensing table** + Microsoft only table, will not be supported. SLIT Section 5.2.17 (signature == "SLIT") - == System Locality distance Information Table == + + **System Locality distance Information Table** + Optional in general, but required for NUMA systems. SPCR Signature Reserved (signature == "SPCR") - == Serial Port Console Redirection table == + + **Serial Port Console Redirection table** + Required for arm64. SPMI Signature Reserved (signature == "SPMI") - == Server Platform Management Interface table == + + **Server Platform Management Interface table** + Optional, not currently supported. SRAT Section 5.2.16 (signature == "SRAT") - == System Resource Affinity Table == + + **System Resource Affinity Table** + Optional, but if used, only the GICC Affinity structures are read. To support arm64 NUMA, this table is required. SSDT Section 5.2.11.2 (signature == "SSDT") - == Secondary System Description Table == + + **Secondary System Description Table** + These tables are a continuation of the DSDT; these are recommended for use with devices that can be added to a running system, but can also serve the purpose of dividing up device descriptions into more
@@ -272,49 +365,69 @@ SSDT Section 5.2.11.2 (signature == "SSDT") one DSDT but can contain many SSDTs. STAO Signature Reserved (signature == "STAO") - == _STA Override table == + + **_STA Override table** + Optional, but only necessary in virtualized environments in order to hide devices from guest OSs. TCPA Signature Reserved (signature == "TCPA") - == Trusted Computing Platform Alliance table == + + **Trusted Computing Platform Alliance table** + Optional, not currently supported, and may need changes to fully interoperate with arm64. TPM2 Signature Reserved (signature == "TPM2") - == Trusted Platform Module 2 table == + + **Trusted Platform Module 2 table** + Optional, not currently supported, and may need changes to fully interoperate with arm64. UEFI Signature Reserved (signature == "UEFI") - == UEFI ACPI data table == + + **UEFI ACPI data table** + Optional, not currently supported. No known use case for arm64, at present. WAET Signature Reserved (signature == "WAET") - == Windows ACPI Emulated devices Table == + + **Windows ACPI Emulated devices Table** + Microsoft only table, will not be supported. WDAT Signature Reserved (signature == "WDAT") - == Watch Dog Action Table == + + **Watch Dog Action Table** + Microsoft only table, will not be supported. WDRT Signature Reserved (signature == "WDRT") - == Watch Dog Resource Table == + + **Watch Dog Resource Table** + Microsoft only table, will not be supported. WPBT Signature Reserved (signature == "WPBT") - == Windows Platform Binary Table == + + **Windows Platform Binary Table** + Microsoft only table, will not be supported. XENV Signature Reserved (signature == "XENV") - == Xen project table == + + **Xen project table** + Optional, used only by Xen at present. XSDT Section 5.2.8 (signature == "XSDT") - == eXtended System Description Table == + + **eXtended System Description Table** + Required for arm64. - +====== ======================================================================== ACPI Objects ------------
@@ -323,10 +436,11 @@ shown in the list that follows; any object not explicitly mentioned below should be used as needed for a particular platform or particular subsystem, such as power management or PCI. +===== ================ ======================================================== Name Section Usage for ARMv8 Linux ----- ------------ ------------------------------------------------- +===== ================ ======================================================== _CCA 6.2.17 This method must be defined for all bus masters - on arm64 -- there are no assumptions made about + on arm64 - there are no assumptions made about whether such devices are cache coherent or not. The _CCA value is inherited by all descendants of these devices so it does not need to be repeated.
@@ -422,8 +536,8 @@ _OSC 6.2.11 This method can be a global method in ACPI (i.e., by the kernel community, then register it with the UEFI Forum. -\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is - concerned, _OSI is not to be used to determine what +\_OSI 5.7.2 Deprecated on ARM64. As far as ACPI firmware is + concerned, _OSI is not to be used to determine what sort of system is being used or what functionality is provided. The _OSC method is to be used instead.
@@ -447,7 +561,7 @@ _PSx 7.3.2-5 Use as needed; power management specific. If _PS0 is usage, change them in these methods. _RDI 8.4.4.4 Recommended for use with processor definitions (_HID - ACPI0010) on arm64. This should only be used in + ACPI0010) on arm64. This should only be used in conjunction with _LPI. \_REV 5.7.4 Always returns the latest version of ACPI supported.
@@ -476,6 +590,7 @@ _SWS 7.4.3 Use as needed; power management specific; this may _UID 6.1.12 Recommended for distinguishing devices of the same class; define it if at all possible. +===== ================ ========================================================
@@ -488,7 +603,7 @@ platforms, ACPI events must be signaled differently. There are two options: GPIO-signaled interrupts (Section 5.6.5), and interrupt-signaled events (Section 5.6.9). Interrupt-signaled events are a -new feature in the ACPI 6.1 specification. Either -- or both -- can be used +new feature in the ACPI 6.1 specification. Either - or both - can be used on a given platform, and which to use may be dependent of limitations in any given SoC. If possible, interrupt-signaled events are recommended.
@@ -564,39 +679,40 @@ supported. The following classes of objects are not supported: - -- Section 9.2: ambient light sensor devices + - Section 9.2: ambient light sensor devices - -- Section 9.3: battery devices + - Section 9.3: battery devices - -- Section 9.4: lids (e.g., laptop lids) + - Section 9.4: lids (e.g., laptop lids) - -- Section 9.8.2: IDE controllers + - Section 9.8.2: IDE controllers - -- Section 9.9: floppy controllers + - Section 9.9: floppy controllers - -- Section 9.10: GPE block devices + - Section 9.10: GPE block devices - -- Section 9.15: PC/AT RTC/CMOS devices + - Section 9.15: PC/AT RTC/CMOS devices - -- Section 9.16: user presence detection devices + - Section 9.16: user presence detection devices - -- Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT + - Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT - -- Section 9.18: time and alarm devices (see 9.15) + - Section 9.18: time and alarm devices (see 9.15) - -- Section 10: power source and power meter devices + - Section 10: power source and power meter devices - -- Section 11: thermal management + - Section 11: thermal management - -- Section 12: embedded controllers interface + - Section 12: embedded controllers interface - -- Section 13: SMBus interfaces + - Section 13: SMBus interfaces This also means that there is no support for the following objects: +==== =========================== ==== ========== Name Section Name Section ----- ------------ ---- ------------ +==== =========================== ==== ========== _ALC 9.3.4 _FDM 9.10.3 _ALI 9.3.2 _FIX 6.2.7 _ALP 9.3.6 _GAI 10.4.5
@@ -619,4 +735,4 @@ _DCK 6.5.2 _UPD 9.16.1 _EC 12.12 _UPP 9.16.2 _FDE 9.10.1 _WPC 10.5.2 _FDI 9.10.2 _WPP 10.5.3 - +==== =========================== ==== ==========
Documentation/arm64/arm-acpi.txt +81 -72
272 lines not on this page · raw message
Documentation/arm64/booting.txt +59 -32
164 lines not on this page · raw message
Documentation/arm64/cpu-feature-registers.txt +99 -91
311 lines not on this page · raw message
Documentation/arm64/elf_hwcaps.txt +10 -40
169 lines not on this page · raw message
Documentation/arm64/hugetlbpage.txt +5 -2
@@ -1,3 +1,4 @@ +==================== HugeTLBpage on ARM64 ====================
@@ -31,8 +32,10 @@ and level of the page table. The following hugepage sizes are supported - - CONT PTE PMD CONT PMD PUD - -------- --- -------- --- + ====== ======== ==== ======== === + - CONT PTE PMD CONT PMD PUD + ====== ======== ==== ======== === 4K: 64K 2M 32M 1G 16K: 2M 32M 1G 64K: 2M 512M 16G + ====== ======== ==== ======== ===
Documentation/arm64/legacy_instructions.txt +27 -16
69 lines not on this page · raw message
Documentation/arm64/memory.txt +46 -45
120 lines not on this page · raw message
Documentation/arm64/pointer-authentication.txt +2 -0
@@ -1,7 +1,9 @@ +======================================= Pointer authentication in AArch64 Linux ======================================= Author: Mark Rutland <[email protected]> + Date: 2017-07-19 This document briefly describes the provision of pointer authentication
Documentation/arm64/silicon-errata.txt +52 -11
115 lines not on this page · raw message
Documentation/arm64/sve.txt +7 -3
@@ -1,7 +1,9 @@ - Scalable Vector Extension support for AArch64 Linux - =================================================== +=================================================== +Scalable Vector Extension support for AArch64 Linux +=================================================== Author: Dave Martin <[email protected]> + Date: 4 August 2017 This document outlines briefly the interface provided to userspace by Linux in
@@ -409,7 +411,7 @@ In A64 state, SVE adds the following: * FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point operations in a similar way to the way in which they interact with ARMv8 - floating-point operations. + floating-point operations:: 8VL-1 128 0 bit index +---- //// -----------------+
@@ -466,6 +468,8 @@ ARMv8-A defines the following floating-point / SIMD register state: * 32 128-bit vector registers V0..V31 * 2 32-bit status/control registers FPSR, FPCR +:: + 127 0 bit index +---------------+ V0 | |
Documentation/arm64/tagged-pointers.txt +4 -2
@@ -1,7 +1,9 @@ - Tagged virtual addresses in AArch64 Linux - ========================================= +========================================= +Tagged virtual addresses in AArch64 Linux +========================================= Author: Will Deacon <[email protected]> + Date : 12 June 2013 This document briefly describes the provision of tagged virtual
arch/arm64/kernel/kexec_image.c +1 -1
@@ -53,7 +53,7 @@ static void *image_load(struct kimage *image,/* * We require a kernel with an unambiguous Image header. Per -* Documentation/booting.txt, this is the case when image_size +* Documentation/arm64/booting.txt, this is the case when image_size * is non-zero (practically speaking, since v3.17). */ h = (struct arm64_image_header *)kernel;
Signature · 7 lines
2.20.1 _______________________________________________ linux-arm-kernel mailing list [email protected] http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
PATCH 5/57 docs: cdrom/cdrom-standard.tex: convert from LaTeX to ReST
In reply to Mauro Carvalho ChehabInstead of having a Latex document directly there, convert it to ReST format, as this is the Kernel format for docs.
For now, let's keep the extension as .txt in order to avoid warnings when building the documentation with Sphinx.
A later patch will rename it to .rst and add it to the building system.
--- Documentation/cdrom/Makefile | 21 - Documentation/cdrom/cdrom-standard.tex | 1026 ----------------------- Documentation/cdrom/cdrom-standard.txt | 1063 ++++++++++++++++++++++++ drivers/cdrom/cdrom.c | 2 +- 4 files changed, 1064 insertions(+), 1048 deletions(-) delete mode 100644 Documentation/cdrom/Makefile delete mode 100644 Documentation/cdrom/cdrom-standard.tex create mode 100644 Documentation/cdrom/cdrom-standard.txt
Documentation/cdrom/Makefile deleted +0 -21
@@ -1,21 +0,0 @@ -LATEXFILE = cdrom-standard - -all: - make clean - latex $(LATEXFILE) - latex $(LATEXFILE) - @if [ -x `which gv` ]; then \ - `dvips -q -t letter -o $(LATEXFILE).ps $(LATEXFILE).dvi` ;\ - `gv -antialias -media letter -nocenter $(LATEXFILE).ps` ;\ - else \ - `xdvi $(LATEXFILE).dvi &` ;\ - fi - make sortofclean - -clean: - rm -f $(LATEXFILE).ps $(LATEXFILE).dvi $(LATEXFILE).aux $(LATEXFILE).log - -sortofclean: - rm -f $(LATEXFILE).aux $(LATEXFILE).log - -
Documentation/cdrom/cdrom-standard.tex deleted +0 -1026
1,026 lines not on this page · raw message
Documentation/cdrom/cdrom-standard.txt new file +1063 -0
1,063 lines not on this page · raw message
drivers/cdrom/cdrom.c +1 -1
@@ -7,7 +7,7 @@ License. See linux/COPYING for more information. Uniform CD-ROM driver for Linux. - See Documentation/cdrom/cdrom-standard.tex for usage information. + See Documentation/cdrom/cdrom-standard.txt for usage information. The routines in the file provide a uniform interface between the software that uses CD-ROMs and the various low-level drivers that
Signature · 1 line
2.20.1
PATCH 6/57 docs: cdrom: convert remaining files to ReST
In reply to Mauro Carvalho ChehabThe stuff there is almost already at ReST format. A conversion for them is trivial: just add a missing titles and fix some scape codes for them to match ReST syntax.
--- Documentation/cdrom/ide-cd | 178 +++++++++++++------------ Documentation/cdrom/packet-writing.txt | 27 ++-- 2 files changed, 108 insertions(+), 97 deletions(-)
Documentation/cdrom/ide-cd +91 -87
@@ -1,18 +1,20 @@ IDE-CD driver documentation -Originally by scott snyder <[email protected]> (19 May 1996) -Carrying on the torch is: Erik Andersen <[email protected]> -New maintainers (19 Oct 1998): Jens Axboe <[email protected]> +=========================== + +:Originally by: scott snyder <[email protected]> (19 May 1996) +:Carrying on the torch is: Erik Andersen <[email protected]> +:New maintainers (19 Oct 1998): Jens Axboe <[email protected]> 1. Introduction --------------- -The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant +The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant CDROM drives which attach to an IDE interface. Note that some CDROM vendors (including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made both ATAPI-compliant drives and drives which use a proprietary interface. If your drive uses one of those proprietary interfaces, this driver will not work with it (but one of the other CDROM drivers -probably will). This driver will not work with `ATAPI' drives which +probably will). This driver will not work with `ATAPI` drives which attach to the parallel port. In addition, there is at least one drive (CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI; this driver will not work with drives like that either (but see the
@@ -31,7 +33,7 @@ This driver provides the following features: from audio tracks. The program cdda2wav can be used for this. Note, however, that only some drives actually support this. - - There is now support for CDROM changers which comply with the + - There is now support for CDROM changers which comply with the ATAPI 2.6 draft standard (such as the NEC CDR-251). This additional functionality includes a function call to query which slot is the currently selected slot, a function call to query which slots contain
@@ -49,11 +51,11 @@ This driver provides the following features: driver. 1. Make sure that the ide and ide-cd drivers are compiled into the - kernel you're using. When configuring the kernel, in the section - entitled "Floppy, IDE, and other block devices", say either `Y' - (which will compile the support directly into the kernel) or `M' + kernel you're using. When configuring the kernel, in the section + entitled "Floppy, IDE, and other block devices", say either `Y` + (which will compile the support directly into the kernel) or `M` (to compile support as a module which can be loaded and unloaded) - to the options: + to the options:: ATA/ATAPI/MFM/RLL support Include IDE/ATAPI CDROM support
@@ -72,35 +74,35 @@ This driver provides the following features: address and an IRQ number, the standard assignments being 0x1f0 and 14 for the primary interface and 0x170 and 15 for the secondary interface. Each interface can control up to two devices, - where each device can be a hard drive, a CDROM drive, a floppy drive, - or a tape drive. The two devices on an interface are called `master' - and `slave'; this is usually selectable via a jumper on the drive. + where each device can be a hard drive, a CDROM drive, a floppy drive, + or a tape drive. The two devices on an interface are called `master` + and `slave`; this is usually selectable via a jumper on the drive. Linux names these devices as follows. The master and slave devices - on the primary IDE interface are called `hda' and `hdb', + on the primary IDE interface are called `hda` and `hdb`, respectively. The drives on the secondary interface are called - `hdc' and `hdd'. (Interfaces at other locations get other letters + `hdc` and `hdd`. (Interfaces at other locations get other letters in the third position; see Documentation/ide/ide.txt.) If you want your CDROM drive to be found automatically by the driver, you should make sure your IDE interface uses either the primary or secondary addresses mentioned above. In addition, if the CDROM drive is the only device on the IDE interface, it should - be jumpered as `master'. (If for some reason you cannot configure + be jumpered as `master`. (If for some reason you cannot configure your system in this manner, you can probably still use the driver. You may have to pass extra configuration information to the kernel when you boot, however. See Documentation/ide/ide.txt for more information.) 4. Boot the system. If the drive is recognized, you should see a - message which looks like + message which looks like:: hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive If you do not see this, see section 5 below. 5. You may want to create a symbolic link /dev/cdrom pointing to the - actual device. You can do this with the command + actual device. You can do this with the command:: ln -s /dev/hdX /dev/cdrom
@@ -108,14 +110,14 @@ This driver provides the following features: drive is installed. 6. You should be able to see any error messages from the driver with - the `dmesg' command. + the `dmesg` command. 3. Basic usage -------------- -An ISO 9660 CDROM can be mounted by putting the disc in the drive and -typing (as root) +An ISO 9660 CDROM can be mounted by putting the disc in the drive and +typing (as root):: mount -t iso9660 /dev/cdrom /mnt/cdrom
@@ -123,7 +125,7 @@ where it is assumed that /dev/cdrom is a link pointing to the actual device (as described in step 5 of the last section) and /mnt/cdrom is an empty directory. You should now be able to see the contents of the CDROM under the /mnt/cdrom directory. If you want to eject the CDROM, -you must first dismount it with a command like +you must first dismount it with a command like:: umount /mnt/cdrom
@@ -148,7 +150,7 @@ such as cdda2wav. The only types of drive which I've heard support this are Sony and Toshiba drives. You will get errors if you try to use this function on a drive which does not support it. -For supported changers, you can use the `cdchange' program (appended to +For supported changers, you can use the `cdchange` program (appended to the end of this file) to switch between changer slots. Note that the drive should be unmounted before attempting this. The program takes two arguments: the CDROM device, and the slot number to which you wish
@@ -165,7 +167,7 @@ Documentation/ide/ide.txt for current information about the underlying IDE support code. Some of these items apply only to earlier versions of the driver, but are mentioned here for completeness. -In most cases, you should probably check with `dmesg' for any errors +In most cases, you should probably check with `dmesg` for any errors from the driver. a. Drive is not detected during booting.
@@ -184,9 +186,9 @@ a. Drive is not detected during booting. - If the autoprobing is not finding your drive, you can tell the driver to assume that one exists by using a lilo option of the - form `hdX=cdrom', where X is the drive letter corresponding to - where your drive is installed. Note that if you do this and you - see a boot message like + form `hdX=cdrom`, where X is the drive letter corresponding to + where your drive is installed. Note that if you do this and you + see a boot message like:: hdX: ATAPI cdrom (?)
@@ -220,7 +222,7 @@ b. Timeout/IRQ errors. probably not making it to the host. - IRQ problems may also be indicated by the message - `IRQ probe failed (<n>)' while booting. If <n> is zero, that + `IRQ probe failed (<n>)` while booting. If <n> is zero, that means that the system did not see an interrupt from the drive when it was expecting one (on any feasible IRQ). If <n> is negative, that means the system saw interrupts on multiple IRQ lines, when
@@ -240,27 +242,27 @@ b. Timeout/IRQ errors. there are hardware problems with the interrupt setup; they apparently don't use interrupts. - - If you own a Pioneer DR-A24X, you _will_ get nasty error messages + - If you own a Pioneer DR-A24X, you _will_ get nasty error messages on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }" The Pioneer DR-A24X CDROM drives are fairly popular these days. Unfortunately, these drives seem to become very confused when we perform the standard Linux ATA disk drive probe. If you own one of these drives, - you can bypass the ATA probing which confuses these CDROM drives, by - adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running - lilo (again where X is the drive letter corresponding to where your drive + you can bypass the ATA probing which confuses these CDROM drives, by + adding `append="hdX=noprobe hdX=cdrom"` to your lilo.conf file and running + lilo (again where X is the drive letter corresponding to where your drive is installed.) - + c. System hangups. - If the system locks up when you try to access the CDROM, the most likely cause is that you have a buggy IDE adapter which doesn't properly handle simultaneous transactions on multiple interfaces. The most notorious of these is the CMD640B chip. This problem can - be worked around by specifying the `serialize' option when + be worked around by specifying the `serialize` option when booting. Recent kernels should be able to detect the need for this automatically in most cases, but the detection is not foolproof. See Documentation/ide/ide.txt for more information - about the `serialize' option and the CMD640B. + about the `serialize` option and the CMD640B. - Note that many MS-DOS CDROM drivers will work with such buggy hardware, apparently because they never attempt to overlap CDROM
@@ -269,14 +271,14 @@ c. System hangups. d. Can't mount a CDROM. - - If you get errors from mount, it may help to check `dmesg' to see + - If you get errors from mount, it may help to check `dmesg` to see if there are any more specific errors from the driver or from the filesystem. - Make sure there's a CDROM loaded in the drive, and that's it's an ISO 9660 disc. You can't mount an audio CD. - - With the CDROM in the drive and unmounted, try something like + - With the CDROM in the drive and unmounted, try something like:: cat /dev/cdrom | od | more
@@ -284,9 +286,9 @@ d. Can't mount a CDROM. OK, and the problem is at the filesystem level (i.e., the CDROM is not ISO 9660 or has errors in the filesystem structure). - - If you see `not a block device' errors, check that the definitions + - If you see `not a block device` errors, check that the definitions of the device special files are correct. They should be as - follows: + follows:: brw-rw---- 1 root disk 3, 0 Nov 11 18:48 /dev/hda brw-rw---- 1 root disk 3, 64 Nov 11 18:48 /dev/hdb
@@ -301,7 +303,7 @@ d. Can't mount a CDROM. If you have a /dev/cdrom symbolic link, check that it is pointing to the correct device file. - If you hear people talking of the devices `hd1a' and `hd1b', these + If you hear people talking of the devices `hd1a` and `hd1b`, these were old names for what are now called hdc and hdd. Those names should be considered obsolete.
@@ -311,8 +313,8 @@ d. Can't mount a CDROM. always give meaningful error messages. -e. Directory listings are unpredictably truncated, and `dmesg' shows - `buffer botch' error messages from the driver. +e. Directory listings are unpredictably truncated, and `dmesg` shows + `buffer botch` error messages from the driver. - There was a bug in the version of the driver in 1.2.x kernels which could cause this. It was fixed in 1.3.0. If you can't
@@ -335,34 +337,36 @@ f. Data corruption. 5. cdchange.c ------------- -/* - * cdchange.c [-v] <device> [<slot>] - * - * This loads a CDROM from a specified slot in a changer, and displays - * information about the changer status. The drive should be unmounted before - * using this program. - * - * Changer information is displayed if either the -v flag is specified - * or no slot was specified. - * - * Based on code originally from Gerhard Zuber <[email protected]>. - * Changer status information, and rewrite for the new Uniform CDROM driver - * interface by Erik Andersen <[email protected]>. - */ +:: -#include <stdio.h> -#include <stdlib.h> -#include <errno.h> -#include <string.h> -#include <unistd.h> -#include <fcntl.h> -#include <sys/ioctl.h> -#include <linux/cdrom.h> + /* + * cdchange.c [-v] <device> [<slot>] + * + * This loads a CDROM from a specified slot in a changer, and displays + * information about the changer status. The drive should be unmounted before + * using this program. + * + * Changer information is displayed if either the -v flag is specified + * or no slot was specified. + * + * Based on code originally from Gerhard Zuber <[email protected]>. + * Changer status information, and rewrite for the new Uniform CDROM driver + * interface by Erik Andersen <[email protected]>. + */ + #include <stdio.h> + #include <stdlib.h> + #include <errno.h> + #include <string.h> + #include <unistd.h> + #include <fcntl.h> + #include <sys/ioctl.h> + #include <linux/cdrom.h> -int -main (int argc, char **argv) -{ + + int + main (int argc, char **argv) + { char *program; char *device; int fd; /* file descriptor for CD-ROM device */
@@ -382,30 +386,30 @@ main (int argc, char **argv) fprintf (stderr, " Slots are numbered 1 -- n.\n"); exit (1); } - + if (strcmp (argv[0], "-v") == 0) { verbose = 1; ++argv; --argc; } - + device = argv[0]; - + if (argc == 2) slot = atoi (argv[1]) - 1; - /* open device */ + /* open device */ fd = open(device, O_RDONLY | O_NONBLOCK); if (fd < 0) { - fprintf (stderr, "%s: open failed for `%s': %s\n", + fprintf (stderr, "%s: open failed for `%s`: %s\n", program, device, strerror (errno)); exit (1); } - /* Check CD player status */ + /* Check CD player status */ total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS); if (total_slots_available <= 1 ) { - fprintf (stderr, "%s: Device `%s' is not an ATAPI " + fprintf (stderr, "%s: Device `%s` is not an ATAPI " "compliant CD changer.\n", program, device); exit (1); }
@@ -418,7 +422,7 @@ main (int argc, char **argv) exit (1); } - /* load */ + /* load */ slot=ioctl (fd, CDROM_SELECT_DISC, slot); if (slot<0) { fflush(stdout);
@@ -462,14 +466,14 @@ main (int argc, char **argv) for (x_slot=0; x_slot<total_slots_available; x_slot++) { printf ("Slot %2d: ", x_slot+1); - status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot); - if (status<0) { - perror(" CDROM_DRIVE_STATUS"); - } else switch(status) { + status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot); + if (status<0) { + perror(" CDROM_DRIVE_STATUS"); + } else switch(status) { case CDS_DISC_OK: printf ("Disc present."); break; - case CDS_NO_DISC: + case CDS_NO_DISC: printf ("Empty slot."); break; case CDS_TRAY_OPEN:
@@ -507,11 +511,11 @@ main (int argc, char **argv) break; } } - status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot); - if (status<0) { + status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot); + if (status<0) { perror(" CDROM_MEDIA_CHANGED"); - } - switch (status) { + } + switch (status) { case 1: printf ("Changed.\n"); break;
@@ -525,10 +529,10 @@ main (int argc, char **argv) /* close device */ status = close (fd); if (status != 0) { - fprintf (stderr, "%s: close failed for `%s': %s\n", + fprintf (stderr, "%s: close failed for `%s`: %s\n", program, device, strerror (errno)); exit (1); } - + exit (0); -} + }
Documentation/cdrom/packet-writing.txt +17 -10
@@ -1,3 +1,7 @@ +============== +Packet writing +============== + Getting started quick ---------------------
@@ -10,13 +14,16 @@ Getting started quick Download from http://sourceforge.net/projects/linux-udf/ - Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute - as appropriate): + as appropriate):: + # cdrwtool -d /dev/hdc -q -- Setup your writer +- Setup your writer:: + # pktsetup dev_name /dev/hdc -- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy! +- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy:: + # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -25,11 +32,11 @@ Packet writing for DVD-RW media DVD-RW discs can be written to much like CD-RW discs if they are in the so called "restricted overwrite" mode. To put a disc in restricted -overwrite mode, run: +overwrite mode, run:: # dvd+rw-format /dev/hdc -You can then use the disc the same way you would use a CD-RW disc: +You can then use the disc the same way you would use a CD-RW disc:: # pktsetup dev_name /dev/hdc # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -41,7 +48,7 @@ Packet writing for DVD+RW media According to the DVD+RW specification, a drive supporting DVD+RW discs shall implement "true random writes with 2KB granularity", which means that it should be possible to put any filesystem with a block size >= -2KB on such a disc. For example, it should be possible to do: +2KB on such a disc. For example, it should be possible to do:: # dvd+rw-format /dev/hdc (only needed if the disc has never been formatted)
@@ -54,7 +61,7 @@ follow the specification, but suffer bad performance problems if the writes are not 32KB aligned. Both problems can be solved by using the pktcdvd driver, which always -generates aligned writes. +generates aligned writes:: # dvd+rw-format /dev/hdc # pktsetup dev_name /dev/hdc
@@ -83,7 +90,7 @@ Notes - Since the pktcdvd driver makes the disc appear as a regular block device with a 2KB block size, you can put any filesystem you like on - the disc. For example, run: + the disc. For example, run:: # /sbin/mke2fs /dev/pktcdvd/dev_name
@@ -97,7 +104,7 @@ Since Linux 2.6.20, the pktcdvd module has a sysfs interface and can be controlled by it. For example the "pktcdvd" tool uses this interface. (see http://tom.ist-im-web.de/download/pktcdvd ) -"pktcdvd" works similar to "pktsetup", e.g.: +"pktcdvd" works similar to "pktsetup", e.g.:: # pktcdvd -a dev_name /dev/hdc # mkudffs /dev/pktcdvd/dev_name
@@ -115,7 +122,7 @@ For a description of the sysfs interface look into the file: Using the pktcdvd debugfs interface ----------------------------------- -To read pktcdvd device infos in human readable form, do: +To read pktcdvd device infos in human readable form, do:: # cat /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/info
Signature · 1 line
2.20.1
PATCH 7/57 docs: cgroup-v1: convert to ReST file format
In reply to Mauro Carvalho ChehabConvert the cgroup-v1 files to ReST format, in order to allow a later addition to the admin-guide.
--- Documentation/cgroup-v1/blkio-controller.txt | 96 ++-- Documentation/cgroup-v1/cgroups.txt | 180 +++---- Documentation/cgroup-v1/cpuacct.txt | 15 +- Documentation/cgroup-v1/cpusets.txt | 203 ++++---- Documentation/cgroup-v1/devices.txt | 40 +- Documentation/cgroup-v1/freezer-subsystem.txt | 14 +- Documentation/cgroup-v1/hugetlb.txt | 31 +- Documentation/cgroup-v1/memcg_test.txt | 259 ++++++---- Documentation/cgroup-v1/memory.txt | 449 +++++++++++------- Documentation/cgroup-v1/net_cls.txt | 37 +- Documentation/cgroup-v1/net_prio.txt | 24 +- Documentation/cgroup-v1/pids.txt | 78 +-- Documentation/cgroup-v1/rdma.txt | 66 +-- 13 files changed, 890 insertions(+), 602 deletions(-)
Documentation/cgroup-v1/blkio-controller.txt +56 -40
@@ -1,5 +1,7 @@ - Block IO Controller - =================== +=================== +Block IO Controller +=================== + Overview ======== cgroup subsys "blkio" implements the block io controller. There seems to be
@@ -22,28 +24,35 @@ Proportional Weight division of bandwidth You can do a very simple testing of running two dd threads in two different cgroups. Here is what you can do. -- Enable Block IO controller +- Enable Block IO controller:: + CONFIG_BLK_CGROUP=y -- Enable group scheduling in CFQ +- Enable group scheduling in CFQ: + + CONFIG_CFQ_GROUP_IOSCHED=y - Compile and boot into kernel and mount IO controller (blkio); see cgroups.txt, Why are cgroups needed?. + :: + mount -t tmpfs cgroup_root /sys/fs/cgroup mkdir /sys/fs/cgroup/blkio mount -t cgroup -o blkio none /sys/fs/cgroup/blkio -- Create two cgroups +- Create two cgroups:: + mkdir -p /sys/fs/cgroup/blkio/test1/ /sys/fs/cgroup/blkio/test2 -- Set weights of group test1 and test2 +- Set weights of group test1 and test2:: + echo 1000 > /sys/fs/cgroup/blkio/test1/blkio.weight echo 500 > /sys/fs/cgroup/blkio/test2/blkio.weight - Create two same size files (say 512MB each) on same disk (file1, file2) and - launch two dd threads in different cgroup to read those files. + launch two dd threads in different cgroup to read those files:: sync echo 3 > /proc/sys/vm/drop_caches
@@ -65,24 +74,27 @@ cgroups. Here is what you can do. Throttling/Upper Limit policy ----------------------------- -- Enable Block IO controller +- Enable Block IO controller:: + CONFIG_BLK_CGROUP=y -- Enable throttling in block layer +- Enable throttling in block layer:: + CONFIG_BLK_DEV_THROTTLING=y -- Mount blkio controller (see cgroups.txt, Why are cgroups needed?) +- Mount blkio controller (see cgroups.txt, Why are cgroups needed?):: + mount -t cgroup -o blkio none /sys/fs/cgroup/blkio - Specify a bandwidth rate on particular device for root group. The format - for policy is "<major>:<minor> <bytes_per_second>". + for policy is "<major>:<minor> <bytes_per_second>":: echo "8:16 1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device Above will put a limit of 1MB/second on reads happening for root group on device having major/minor number 8:16. -- Run dd to read a file and see if rate is throttled to 1MB/s or not. +- Run dd to read a file and see if rate is throttled to 1MB/s or not:: # dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024 1024+0 records in
@@ -99,7 +111,7 @@ throttling's hierarchy support is enabled iff "sane_behavior" is enabled from cgroup side, which currently is a development option and not publicly available. -If somebody created a hierarchy like as follows. +If somebody created a hierarchy like as follows:: root / \
@@ -115,7 +127,7 @@ directly generated by tasks in that cgroup. Throttling without "sane_behavior" enabled from cgroup side will practically treat all groups at same level as if it looks like the -following. +following:: pivot / / \ \
@@ -152,27 +164,31 @@ Proportional weight policy files These rules override the default value of group weight as specified by blkio.weight. - Following is the format. + Following is the format:: - # echo dev_maj:dev_minor weight > blkio.weight_device - Configure weight=300 on /dev/sdb (8:16) in this cgroup - # echo 8:16 300 > blkio.weight_device - # cat blkio.weight_device - dev weight - 8:16 300 + # echo dev_maj:dev_minor weight > blkio.weight_device - Configure weight=500 on /dev/sda (8:0) in this cgroup - # echo 8:0 500 > blkio.weight_device - # cat blkio.weight_device - dev weight - 8:0 500 - 8:16 300 + Configure weight=300 on /dev/sdb (8:16) in this cgroup:: - Remove specific weight for /dev/sda in this cgroup - # echo 8:0 0 > blkio.weight_device - # cat blkio.weight_device - dev weight - 8:16 300 + # echo 8:16 300 > blkio.weight_device + # cat blkio.weight_device + dev weight + 8:16 300 + + Configure weight=500 on /dev/sda (8:0) in this cgroup:: + + # echo 8:0 500 > blkio.weight_device + # cat blkio.weight_device + dev weight + 8:0 500 + 8:16 300 + + Remove specific weight for /dev/sda in this cgroup:: + + # echo 8:0 0 > blkio.weight_device + # cat blkio.weight_device + dev weight + 8:16 300 - blkio.leaf_weight[_device] - Equivalents of blkio.weight[_device] for the purpose of
@@ -297,30 +313,30 @@ Throttling/Upper limit policy files - blkio.throttle.read_bps_device - Specifies upper limit on READ rate from the device. IO rate is specified in bytes per second. Rules are per device. Following is - the format. + the format:: - echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device + echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device - blkio.throttle.write_bps_device - Specifies upper limit on WRITE rate to the device. IO rate is specified in bytes per second. Rules are per device. Following is - the format. + the format:: - echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device + echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device - blkio.throttle.read_iops_device - Specifies upper limit on READ rate from the device. IO rate is specified in IO per second. Rules are per device. Following is - the format. + the format:: - echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device + echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device - blkio.throttle.write_iops_device - Specifies upper limit on WRITE rate to the device. IO rate is specified in io per second. Rules are per device. Following is - the format. + the format:: - echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device + echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device Note: If both BW and IOPS rules are specified for a device, then IO is subjected to both the constraints.
Documentation/cgroup-v1/cgroups.txt +99 -81
348 lines not on this page · raw message
Documentation/cgroup-v1/cpuacct.txt +8 -7
@@ -1,5 +1,6 @@ +========================= CPU Accounting Controller -------------------------- +========================= The CPU accounting controller is used to group tasks using cgroups and account the CPU usage of these groups of tasks.
@@ -8,9 +9,9 @@ The CPU accounting controller supports multi-hierarchy groups. An accounting group accumulates the CPU usage of all of its child groups and the tasks directly present in its group. -Accounting groups can be created by first mounting the cgroup filesystem. +Accounting groups can be created by first mounting the cgroup filesystem:: -# mount -t cgroup -ocpuacct none /sys/fs/cgroup + # mount -t cgroup -ocpuacct none /sys/fs/cgroup With the above step, the initial or the parent accounting group becomes visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
@@ -19,11 +20,11 @@ the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup. by this group which is essentially the CPU time obtained by all the tasks in the system. -New accounting groups can be created under the parent group /sys/fs/cgroup. +New accounting groups can be created under the parent group /sys/fs/cgroup:: -# cd /sys/fs/cgroup -# mkdir g1 -# echo $$ > g1/tasks + # cd /sys/fs/cgroup + # mkdir g1 + # echo $$ > g1/tasks The above steps create a new group g1 and move the current shell process (bash) into it. CPU time consumed by this bash and its children
Documentation/cgroup-v1/cpusets.txt +115 -88
336 lines not on this page · raw message
Documentation/cgroup-v1/devices.txt +28 -12
@@ -1,6 +1,9 @@ +=========================== Device Whitelist Controller +=========================== -1. Description: +1. Description +============== Implement a cgroup to track and enforce open and mknod restrictions on device files. A device cgroup associates a device access
@@ -16,24 +19,26 @@ devices from the whitelist or add new entries. A child cgroup can never receive a device access which is denied by its parent. 2. User Interface +================= An entry is added using devices.allow, and removed using -devices.deny. For instance +devices.deny. For instance:: echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow allows cgroup 1 to read and mknod the device usually known as -/dev/null. Doing +/dev/null. Doing:: echo a > /sys/fs/cgroup/1/devices.deny -will remove the default 'a *:* rwm' entry. Doing +will remove the default 'a *:* rwm' entry. Doing:: echo a > /sys/fs/cgroup/1/devices.allow will add the 'a *:* rwm' entry to the whitelist. 3. Security +=========== Any task can move itself between cgroups. This clearly won't suffice, but we can decide the best way to adequately restrict
@@ -50,6 +55,7 @@ A cgroup may not be granted more permissions than the cgroup's parent has. 4. Hierarchy +============ device cgroups maintain hierarchy by making sure a cgroup never has more access permissions than its parent. Every time an entry is written to
@@ -58,7 +64,8 @@ from their whitelist and all the locally set whitelist entries will be re-evaluated. In case one of the locally set whitelist entries would provide more access than the cgroup's parent, it'll be removed from the whitelist. -Example: +Example:: + A / \ B
@@ -67,10 +74,12 @@ Example: A allow "b 8:* rwm", "c 116:1 rw" B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm" -If a device is denied in group A: +If a device is denied in group A:: + # echo "c 116:* r" > A/devices.deny + it'll propagate down and after revalidating B's entries, the whitelist entry -"c 116:2 rwm" will be removed: +"c 116:2 rwm" will be removed:: group whitelist entries denied devices A all "b 8:* rwm", "c 116:* rw"
@@ -79,7 +88,8 @@ it'll propagate down and after revalidating B's entries, the whitelist entry In case parent's exceptions change and local exceptions are not allowed anymore, they'll be deleted. -Notice that new whitelist entries will not be propagated: +Notice that new whitelist entries will not be propagated:: + A / \ B
@@ -88,24 +98,30 @@ Notice that new whitelist entries will not be propagated: A "c 1:3 rwm", "c 1:5 r" all the rest B "c 1:3 rwm", "c 1:5 r" all the rest -when adding "c *:3 rwm": +when adding `c *:3 rwm`:: + # echo "c *:3 rwm" >A/devices.allow -the result: +the result:: + group whitelist entries denied devices A "c *:3 rwm", "c 1:5 r" all the rest B "c 1:3 rwm", "c 1:5 r" all the rest -but now it'll be possible to add new entries to B: +but now it'll be possible to add new entries to B:: + # echo "c 2:3 rwm" >B/devices.allow # echo "c 50:3 r" >B/devices.allow -or even + +or even:: + # echo "c *:3 rwm" >B/devices.allow Allowing or denying all by writing 'a' to devices.allow or devices.deny will not be possible once the device cgroups has children. 4.1 Hierarchy (internal implementation) +--------------------------------------- device cgroups is implemented internally using a behavior (ALLOW, DENY) and a list of exceptions. The internal state is controlled using the same user
Documentation/cgroup-v1/freezer-subsystem.txt +9 -5
@@ -1,3 +1,7 @@ +============== +Cgroup Freezer +============== + The cgroup freezer is useful to batch job management system which start and stop sets of tasks in order to schedule the resources of a machine according to the desires of a system administrator. This sort of program
@@ -23,7 +27,7 @@ blocked, or ignored it can be seen by waiting or ptracing parent tasks. SIGCONT is especially unsuitable since it can be caught by the task. Any programs designed to watch for SIGSTOP and SIGCONT could be broken by attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can -demonstrate this problem using nested bash shells: +demonstrate this problem using nested bash shells:: $ echo $$ 16644
@@ -93,19 +97,19 @@ The following cgroupfs files are created by cgroup freezer. The root cgroup is non-freezable and the above interface files don't exist. -* Examples of usage : +* Examples of usage:: # mkdir /sys/fs/cgroup/freezer # mount -t cgroup -ofreezer freezer /sys/fs/cgroup/freezer # mkdir /sys/fs/cgroup/freezer/0 # echo $some_pid > /sys/fs/cgroup/freezer/0/tasks -to get status of the freezer subsystem : +to get status of the freezer subsystem:: # cat /sys/fs/cgroup/freezer/0/freezer.state THAWED -to freeze all tasks in the container : +to freeze all tasks in the container:: # echo FROZEN > /sys/fs/cgroup/freezer/0/freezer.state # cat /sys/fs/cgroup/freezer/0/freezer.state
@@ -113,7 +117,7 @@ to freeze all tasks in the container : # cat /sys/fs/cgroup/freezer/0/freezer.state FROZEN -to unfreeze all tasks in the container : +to unfreeze all tasks in the container:: # echo THAWED > /sys/fs/cgroup/freezer/0/freezer.state # cat /sys/fs/cgroup/freezer/0/freezer.state
Documentation/cgroup-v1/hugetlb.txt +16 -15
@@ -1,5 +1,6 @@ +================== HugeTLB Controller -------------------- +================== The HugeTLB controller allows to limit the HugeTLB usage per control group and enforces the controller limit during page fault. Since HugeTLB doesn't
@@ -16,16 +17,16 @@ With the above step, the initial or the parent HugeTLB group becomes visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup. -New groups can be created under the parent group /sys/fs/cgroup. +New groups can be created under the parent group /sys/fs/cgroup:: -# cd /sys/fs/cgroup -# mkdir g1 -# echo $$ > g1/tasks + # cd /sys/fs/cgroup + # mkdir g1 + # echo $$ > g1/tasks The above steps create a new group g1 and move the current shell process (bash) into it. -Brief summary of control files +Brief summary of control files:: hugetlb.<hugepagesize>.limit_in_bytes # set/show limit of "hugepagesize" hugetlb usage hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded
@@ -33,13 +34,13 @@ Brief summary of control files hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB limit For a system supporting two hugepage size (16M and 16G) the control -files include: +files include:: -hugetlb.16GB.limit_in_bytes -hugetlb.16GB.max_usage_in_bytes -hugetlb.16GB.usage_in_bytes -hugetlb.16GB.failcnt -hugetlb.16MB.limit_in_bytes -hugetlb.16MB.max_usage_in_bytes -hugetlb.16MB.usage_in_bytes -hugetlb.16MB.failcnt + hugetlb.16GB.limit_in_bytes + hugetlb.16GB.max_usage_in_bytes + hugetlb.16GB.usage_in_bytes + hugetlb.16GB.failcnt + hugetlb.16MB.limit_in_bytes + hugetlb.16MB.max_usage_in_bytes + hugetlb.16MB.usage_in_bytes + hugetlb.16MB.failcnt
Documentation/cgroup-v1/memcg_test.txt +167 -92
408 lines not on this page · raw message
Documentation/cgroup-v1/memory.txt +280 -169
851 lines not on this page · raw message
Documentation/cgroup-v1/net_cls.txt +21 -16
@@ -1,5 +1,6 @@ +========================= Network classifier cgroup -------------------------- +========================= The Network classifier cgroup provides an interface to tag network packets with a class identifier (classid).
@@ -17,23 +18,27 @@ values is 0xAAAABBBB; AAAA is the major handle number and BBBB is the minor handle number. Reading net_cls.classid yields a decimal result. -Example: -mkdir /sys/fs/cgroup/net_cls -mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls -mkdir /sys/fs/cgroup/net_cls/0 -echo 0x100001 > /sys/fs/cgroup/net_cls/0/net_cls.classid - - setting a 10:1 handle. +Example:: -cat /sys/fs/cgroup/net_cls/0/net_cls.classid -1048577 + mkdir /sys/fs/cgroup/net_cls + mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls + mkdir /sys/fs/cgroup/net_cls/0 + echo 0x100001 > /sys/fs/cgroup/net_cls/0/net_cls.classid -configuring tc: -tc qdisc add dev eth0 root handle 10: htb +- setting a 10:1 handle:: -tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit - - creating traffic class 10:1 + cat /sys/fs/cgroup/net_cls/0/net_cls.classid + 1048577 -tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup +- configuring tc:: -configuring iptables, basic example: -iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP + tc qdisc add dev eth0 root handle 10: htb + tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit + +- creating traffic class 10:1:: + + tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup + +configuring iptables, basic example:: + + iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP
Documentation/cgroup-v1/net_prio.txt +13 -11
@@ -1,5 +1,6 @@ +======================= Network priority cgroup -------------------------- +======================= The Network priority cgroup provides an interface to allow an administrator to dynamically set the priority of network traffic generated by various
@@ -14,9 +15,9 @@ SO_PRIORITY socket option. This however, is not always possible because: This cgroup allows an administrator to assign a process to a group which defines the priority of egress traffic on a given interface. Network priority groups can -be created by first mounting the cgroup filesystem. +be created by first mounting the cgroup filesystem:: -# mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio + # mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio With the above step, the initial group acting as the parent accounting group becomes visible at '/sys/fs/cgroup/net_prio'. This group includes all tasks in
@@ -25,17 +26,18 @@ the system. '/sys/fs/cgroup/net_prio/tasks' lists the tasks in this cgroup. Each net_prio cgroup contains two files that are subsystem specific net_prio.prioidx -This file is read-only, and is simply informative. It contains a unique integer -value that the kernel uses as an internal representation of this cgroup. + This file is read-only, and is simply informative. It contains a unique + integer value that the kernel uses as an internal representation of this + cgroup. net_prio.ifpriomap -This file contains a map of the priorities assigned to traffic originating from -processes in this group and egressing the system on various interfaces. It -contains a list of tuples in the form <ifname priority>. Contents of this file -can be modified by echoing a string into the file using the same tuple format. -for example: + This file contains a map of the priorities assigned to traffic originating + from processes in this group and egressing the system on various interfaces. + It contains a list of tuples in the form <ifname priority>. Contents of this + file can be modified by echoing a string into the file using the same tuple + format. For example:: -echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap + echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap This command would force any traffic originating from processes belonging to the iscsi net_prio cgroup and egressing on interface eth0 to have the priority of
Documentation/cgroup-v1/pids.txt +41 -37
101 lines not on this page · raw message
Documentation/cgroup-v1/rdma.txt +37 -29
80 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 8/57 docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
In reply to Mauro Carvalho ChehabThe CFQ scheduler was removed on this changeset:
commit f382fb0bcef4c37dc049e9f6963e3baf204d815c
Author: Jens Axboe <[email protected]>
Date: Fri Oct 12 10:14:46 2018 -0600
block: remove legacy IO schedulers
Retain the deadline documentation, as that carries over to mq-deadline as well.
However, the cgroups-v1 documentation still mentions it and points to a removed file that used to belong to such scheduler.
Add a note about that, as someone needs to fix the document pointing to another scheduler, if cgroups-v1 blockio is not dependent of CFQ scheduler.
--- Documentation/cgroup-v1/blkio-controller.txt | 7 +++++++ 1 file changed, 7 insertions(+)
Documentation/cgroup-v1/blkio-controller.txt +7 -0
@@ -17,6 +17,13 @@ one is throttling policy which can be used to specify upper IO rate limits on devices. This policy is implemented in generic block layer and can be used on leaf nodes as well as higher level logical devices like device mapper. +.. note:: + + While this document mentions the CFQ scheduler, it got removed at + Kernel 4.20, as there are other schedulers that are more efficient. + + Someone needs to update this file in order to reflect such change. + HOWTO ===== Proportional Weight division of bandwidth
Signature · 1 line
2.20.1
PATCH 9/57 docs: cpu-freq: convert files to ReST
In reply to Mauro Carvalho ChehabIn order to be able to build html and pdf files, convert the documentation to ReST format.
--- Documentation/cpu-freq/amd-powernow.txt | 11 +- Documentation/cpu-freq/core.txt | 66 +++---- Documentation/cpu-freq/cpu-drivers.txt | 217 +++++++++++---------- Documentation/cpu-freq/cpufreq-nforce2.txt | 12 +- Documentation/cpu-freq/cpufreq-stats.txt | 141 ++++++------- Documentation/cpu-freq/pcc-cpufreq.txt | 102 +++++----- 6 files changed, 281 insertions(+), 268 deletions(-)
Documentation/cpu-freq/amd-powernow.txt +9 -2
@@ -1,3 +1,7 @@ +============================= +AMD powernow driver specifics +============================= + PowerNow! and Cool'n'Quiet are AMD names for frequency management capabilities in AMD processors. As the hardware
@@ -23,16 +27,19 @@ not supply these tables. 7th Generation: powernow-k7: Athlon, Duron, Geode. 8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron. + Documentation on this functionality in 8th generation processors is available in the "BIOS and Kernel Developer's Guide", publication -26094, in chapter 9, available for download from www.amd.com. +26094, in chapter 9, available for download from www.amd.com. BIOS supplied data, for powernow-k7 and for powernow-k8, may be from either the PSB table or from ACPI objects. The ACPI support is only available if the kernel config sets CONFIG_ACPI_PROCESSOR. + The powernow-k8 driver will attempt to use ACPI if so configured, and fall back to PST if that fails. + The powernow-k7 driver will try to use the PSB support first, and fall back to ACPI if the PSB support fails. A module parameter, -acpi_force, is provided to force ACPI support to be used instead +acpi_force, is provided to force ACPI support to be used instead of PSB support.
Documentation/cpu-freq/core.txt +31 -35
107 lines not on this page · raw message
Documentation/cpu-freq/cpu-drivers.txt +113 -104
301 lines not on this page · raw message
Documentation/cpu-freq/cpufreq-nforce2.txt +8 -4
@@ -1,3 +1,6 @@ +================================= +nVidia nForce2 platform specifics +================================= The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms.
@@ -6,14 +9,15 @@ can be controlled independently from the PCI/AGP clock. The module has two options: + ======== ====================================== fid: multiplier * 10 (for example 8.5 = 85) min_fsb: minimum FSB + ======== ====================================== If not set, fid is calculated from the current CPU speed and the FSB. min_fsb defaults to FSB at boot time - 50 MHz. -IMPORTANT: The available range is limited downwards! - Also the minimum available FSB can differ, for systems +IMPORTANT: + The available range is limited downwards! + Also the minimum available FSB can differ, for systems booting with 200 MHz, 150 should always work. - -
Documentation/cpu-freq/cpufreq-stats.txt +71 -70
176 lines not on this page · raw message
Documentation/cpu-freq/pcc-cpufreq.txt +49 -53
138 lines not on this page · raw message
Signature · 1 line
2.20.1
Rafael J. Wysocki
maintainerRe: [PATCH 09/57] docs: cpu-freq: convert files to ReST
Quoted 5 lines · Mauro Carvalho Chehab
In order to be able to build html and pdf files, convert the documentation to ReST format.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Please don't convert these files.
They need more work than just semi-automatic conversion and the material in them needs to go under driver-api.
This is quite hight in my TODO list.
Thanks,
Rafael
Re: [PATCH 09/57] docs: cpu-freq: convert files to ReST
Em Tue, 16 Apr 2019 10:21:31 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:
Quoted 11 lines
Quoted 5 lines · Mauro Carvalho Chehab
In order to be able to build html and pdf files, convert the documentation to ReST format.
Signed-off-by Mauro Carvalho Chehab <[email protected]>Please don't convert these files.
They need more work than just semi-automatic conversion
Except for one exception (at patch 32/57), the ReST conversion on this patch set was manually made. I basically renamed the files to .rst, checked the errors and fixed, trying to preserve the original document style as much as possible, while providing a good visual for the html output.
I suspect that trying to write a script for such kind of conversion is not an easy task, as some documents within the Kernel tree have their own personal style, (there was even one written in LaTeX at the CDROM docs), and I suspect that a script would end by adding extra unwanted markups.
Quoted 1 line
and the material in them needs to go under driver-api.
Yeah, those documents make sense to be at the driver-api set.
The rationale why I placed the patch with actually renames on a separate patchset (already on my devel tree, but yet to be submitted) is that, this way, it should be easy for maintainers to pick the conversion patch, apply on their trees, and, if they're not ready yet, postpone the actual rename/move thing.
Quoted 1 line
This is quite hight in my TODO list.
OK. Feel free to use this patch as a starting point if you want.
Regards,
Mauro
PATCH 10/57 docs: device-mapper: convert it to ReST format
In reply to Mauro Carvalho ChehabConvert the Device Mapper documentation to ReST.
--- .../device-mapper/cache-policies.txt | 24 +- Documentation/device-mapper/cache.txt | 206 +++++++++------- Documentation/device-mapper/delay.txt | 29 ++- Documentation/device-mapper/dm-crypt.txt | 57 +++-- Documentation/device-mapper/dm-flakey.txt | 45 ++-- Documentation/device-mapper/dm-init.txt | 75 +++--- Documentation/device-mapper/dm-integrity.txt | 55 +++-- Documentation/device-mapper/dm-io.txt | 14 +- Documentation/device-mapper/dm-log.txt | 5 +- .../device-mapper/dm-queue-length.txt | 25 +- Documentation/device-mapper/dm-raid.txt | 225 +++++++++++------- .../device-mapper/dm-service-time.txt | 68 +++--- Documentation/device-mapper/dm-uevent.txt | 143 ++++++----- Documentation/device-mapper/dm-zoned.txt | 10 +- Documentation/device-mapper/era.txt | 36 +-- Documentation/device-mapper/kcopyd.txt | 10 +- Documentation/device-mapper/linear.txt | 100 ++++---- Documentation/device-mapper/log-writes.txt | 91 +++---- .../device-mapper/persistent-data.txt | 4 + Documentation/device-mapper/snapshot.txt | 116 ++++----- Documentation/device-mapper/statistics.txt | 62 ++--- Documentation/device-mapper/striped.txt | 68 +++--- Documentation/device-mapper/switch.txt | 47 ++-- .../device-mapper/thin-provisioning.txt | 68 ++++-- Documentation/device-mapper/unstriped.txt | 111 +++++---- Documentation/device-mapper/verity.txt | 20 +- Documentation/device-mapper/writecache.txt | 13 +- Documentation/device-mapper/zero.txt | 14 +- 28 files changed, 1012 insertions(+), 729 deletions(-)
Documentation/device-mapper/cache-policies.txt +17 -7
@@ -1,3 +1,4 @@ +============================= Guidance for writing policies =============================
@@ -30,7 +31,7 @@ multiqueue (mq) This policy is now an alias for smq (see below). -The following tunables are accepted, but have no effect: +The following tunables are accepted, but have no effect:: 'sequential_threshold <#nr_sequential_ios>' 'random_threshold <#nr_random_ios>'
@@ -56,7 +57,9 @@ mq policy's hints to be dropped. Also, performance of the cache may degrade slightly until smq recalculates the origin device's hotspots that should be cached. -Memory usage: +Memory usage +^^^^^^^^^^^^ + The mq policy used a lot of memory; 88 bytes per cache block on a 64 bit machine.
@@ -69,7 +72,9 @@ cache block). All this means smq uses ~25bytes per cache block. Still a lot of memory, but a substantial improvement nontheless. -Level balancing: +Level balancing +^^^^^^^^^^^^^^^ + mq placed entries in different levels of the multiqueue structures based on their hit count (~ln(hit count)). This meant the bottom levels generally had the most entries, and the top ones had very
@@ -94,7 +99,9 @@ is used to decide which blocks to promote. If the hotspot queue is performing badly then it starts moving entries more quickly between levels. This lets it adapt to new IO patterns very quickly. -Performance: +Performance +^^^^^^^^^^^ + Testing smq shows substantially better performance than mq. cleaner
@@ -105,16 +112,19 @@ The cleaner writes back all dirty blocks in a cache to decommission it. Examples ======== -The syntax for a table is: +The syntax for a table is:: + cache <metadata dev> <cache dev> <origin dev> <block size> <#feature_args> [<feature arg>]* <policy> <#policy_args> [<policy arg>]* -The syntax to send a message using the dmsetup command is: +The syntax to send a message using the dmsetup command is:: + dmsetup message <mapped device> 0 sequential_threshold 1024 dmsetup message <mapped device> 0 random_threshold 8 -Using dmsetup: +Using dmsetup:: + dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \ /dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8" creates a 128GB large mapped device named 'blah' with the
Documentation/device-mapper/cache.txt +116 -90
258 lines not on this page · raw message
Documentation/device-mapper/delay.txt +16 -13
@@ -1,10 +1,12 @@ +======== dm-delay ======== Device-Mapper's "delay" target delays reads and/or writes and maps them to different devices. -Parameters: +Parameters:: + <device> <offset> <delay> [<write_device> <write_offset> <write_delay> [<flush_device> <flush_offset> <flush_delay>]]
@@ -14,15 +16,16 @@ Delays are specified in milliseconds. Example scripts =============== -[[ -#!/bin/sh -# Create device delaying rw operation for 500ms -echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed -]] - -[[ -#!/bin/sh -# Create device delaying only write operation for 500ms and -# splitting reads and writes to different devices $1 $2 -echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed -]] + +:: + + #!/bin/sh + # Create device delaying rw operation for 500ms + echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed + +:: + + #!/bin/sh + # Create device delaying only write operation for 500ms and + # splitting reads and writes to different devices $1 $2 + echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed
Documentation/device-mapper/dm-crypt.txt +34 -23
87 lines not on this page · raw message
Documentation/device-mapper/dm-flakey.txt +31 -14
68 lines not on this page · raw message
Documentation/device-mapper/dm-init.txt +43 -32
140 lines not on this page · raw message
Documentation/device-mapper/dm-integrity.txt +40 -15
123 lines not on this page · raw message
Documentation/device-mapper/dm-io.txt +7 -7
@@ -1,3 +1,4 @@ +===== dm-io =====
@@ -7,7 +8,7 @@ version. The user must set up an io_region structure to describe the desired location of the I/O. Each io_region indicates a block-device along with the starting -sector and size of the region. +sector and size of the region:: struct io_region { struct block_device *bdev;
@@ -19,7 +20,7 @@ Dm-io can read from one io_region or write to one or more io_regions. Writes to multiple regions are specified by an array of io_region structures. The first I/O service type takes a list of memory pages as the data buffer for -the I/O, along with an offset into the first page. +the I/O, along with an offset into the first page:: struct page_list { struct page_list *next;
@@ -35,7 +36,7 @@ the I/O, along with an offset into the first page. The second I/O service type takes an array of bio vectors as the data buffer for the I/O. This service can be handy if the caller has a pre-assembled bio, -but wants to direct different portions of the bio to different devices. +but wants to direct different portions of the bio to different devices:: int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where, int rw, struct bio_vec *bvec,
@@ -47,7 +48,7 @@ but wants to direct different portions of the bio to different devices. The third I/O service type takes a pointer to a vmalloc'd memory buffer as the data buffer for the I/O. This service can be handy if the caller needs to do I/O to a large region but doesn't want to allocate a large number of individual -memory pages. +memory pages:: int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw, void *data, unsigned long *error_bits);
@@ -55,11 +56,11 @@ memory pages. void *data, io_notify_fn fn, void *context); Callers of the asynchronous I/O services must include the name of a completion -callback routine and a pointer to some context data for the I/O. +callback routine and a pointer to some context data for the I/O:: typedef void (*io_notify_fn)(unsigned long error, void *context); -The "error" parameter in this callback, as well as the "*error" parameter in +The "error" parameter in this callback, as well as the `*error` parameter in all of the synchronous versions, is a bitset (instead of a simple error value). In the case of an write-I/O to multiple regions, this bitset allows dm-io to indicate success or failure on each individual region.
@@ -72,4 +73,3 @@ always available in order to avoid unnecessary waiting while performing I/O. When the user is finished using the dm-io services, they should call dm_io_put() and specify the same number of pages that were given on the dm_io_get() call. -
Documentation/device-mapper/dm-log.txt +4 -1
@@ -1,3 +1,4 @@ +===================== Device-Mapper Logging ===================== The device-mapper logging code is used by some of the device-mapper
@@ -16,11 +17,13 @@ dm_dirty_log_type in include/linux/dm-dirty-log.h). Various different logging implementations are available and provide different capabilities. The list includes: +============== ============================================================== Type Files -==== ===== +============== ============================================================== disk drivers/md/dm-log.c core drivers/md/dm-log.c userspace drivers/md/dm-log-userspace* include/linux/dm-log-userspace.h +============== ============================================================== The "disk" log type -------------------
Documentation/device-mapper/dm-queue-length.txt +17 -8
@@ -1,3 +1,4 @@ +=============== dm-queue-length ===============
@@ -6,12 +7,18 @@ which selects a path with the least number of in-flight I/Os. The path selector name is 'queue-length'. Table parameters for each path: [<repeat_count>] + +:: + <repeat_count>: The number of I/Os to dispatch using the selected path before switching to the next path. If not given, internal default is used. To check the default value, see the activated table. Status for each path: <status> <fail-count> <in-flight> + +:: + <status>: 'A' if the path is active, 'F' if the path is failed. <fail-count>: The number of path failures. <in-flight>: The number of in-flight I/Os on the path.
@@ -29,11 +36,13 @@ Examples ======== In case that 2 paths (sda and sdb) are used with repeat_count == 128. -# echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \ - dmsetup create test -# -# dmsetup table -test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128 -# -# dmsetup status -test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0 +:: + + # echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \ + dmsetup create test + # + # dmsetup table + test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128 + # + # dmsetup status + test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0
Documentation/device-mapper/dm-raid.txt +145 -80
401 lines not on this page · raw message
Documentation/device-mapper/dm-service-time.txt +39 -29
99 lines not on this page · raw message
Documentation/device-mapper/dm-uevent.txt +78 -65
173 lines not on this page · raw message
Documentation/device-mapper/dm-zoned.txt +6 -4
@@ -1,3 +1,4 @@ +======== dm-zoned ========
@@ -133,12 +134,13 @@ A zoned block device must first be formatted using the dmzadm tool. This will analyze the device zone configuration, determine where to place the metadata sets on the device and initialize the metadata sets. -Ex: +Ex:: -dmzadm --format /dev/sdxx + dmzadm --format /dev/sdxx For a formatted device, the target can be created normally with the dmsetup utility. The only parameter that dm-zoned requires is the -underlying zoned block device name. Ex: +underlying zoned block device name. Ex:: -echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | dmsetup create dmz-`basename ${dev}` + echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | \ + dmsetup create dmz-`basename ${dev}`
Documentation/device-mapper/era.txt +22 -14
@@ -1,3 +1,7 @@ +====== +dm-era +====== + Introduction ============
@@ -14,12 +18,14 @@ coherency after rolling back a vendor snapshot. Constructor =========== - era <metadata dev> <origin dev> <block size> +era <metadata dev> <origin dev> <block size> - metadata dev : fast device holding the persistent metadata - origin dev : device holding data blocks that may change - block size : block size of origin data device, granularity that is - tracked by the target + ================ ====================================================== + metadata dev fast device holding the persistent metadata + origin dev device holding data blocks that may change + block size block size of origin data device, granularity that is + tracked by the target + ================ ====================================================== Messages ========
@@ -49,14 +55,16 @@ Status <metadata block size> <#used metadata blocks>/<#total metadata blocks> <current era> <held metadata root | '-'> -metadata block size : Fixed block size for each metadata block in - sectors -#used metadata blocks : Number of metadata blocks used -#total metadata blocks : Total number of metadata blocks -current era : The current era -held metadata root : The location, in blocks, of the metadata root - that has been 'held' for userspace read - access. '-' indicates there is no held root +========================= ============================================== +metadata block size Fixed block size for each metadata block in + sectors +#used metadata blocks Number of metadata blocks used +#total metadata blocks Total number of metadata blocks +current era The current era +held metadata root The location, in blocks, of the metadata root + that has been 'held' for userspace read + access. '-' indicates there is no held root +========================= ============================================== Detailed use case =================
@@ -88,7 +96,7 @@ Memory usage The target uses a bitset to record writes in the current era. It also has a spare bitset ready for switching over to a new era. Other than -that it uses a few 4k blocks for updating metadata. +that it uses a few 4k blocks for updating metadata:: (4 * nr_blocks) bytes + buffers
Documentation/device-mapper/kcopyd.txt +5 -5
@@ -1,3 +1,4 @@ +====== kcopyd ======
@@ -7,7 +8,7 @@ notification. It is used by dm-snapshot and dm-mirror. Users of kcopyd must first create a client and indicate how many memory pages to set aside for their copy jobs. This is done with a call to -kcopyd_client_create(). +kcopyd_client_create():: int kcopyd_client_create(unsigned int num_pages, struct kcopyd_client **result);
@@ -16,7 +17,7 @@ To start a copy job, the user must set up io_region structures to describe the source and destinations of the copy. Each io_region indicates a block-device along with the starting sector and size of the region. The source of the copy is given as one io_region structure, and the destinations of the -copy are given as an array of io_region structures. +copy are given as an array of io_region structures:: struct io_region { struct block_device *bdev;
@@ -26,7 +27,7 @@ copy are given as an array of io_region structures. To start the copy, the user calls kcopyd_copy(), passing in the client pointer, pointers to the source and destination io_regions, the name of a -completion callback routine, and a pointer to some context data for the copy. +completion callback routine, and a pointer to some context data for the copy:: int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from, unsigned int num_dests, struct io_region *dests,
@@ -41,7 +42,6 @@ write error occurred during the copy. When a user is done with all their copy jobs, they should call kcopyd_client_destroy() to delete the kcopyd client, which will release the -associated memory pages. +associated memory pages:: void kcopyd_client_destroy(struct kcopyd_client *kc); -
Documentation/device-mapper/linear.txt +51 -49
110 lines not on this page · raw message
Documentation/device-mapper/log-writes.txt +48 -43
145 lines not on this page · raw message
Documentation/device-mapper/persistent-data.txt +4 -0
@@ -1,3 +1,7 @@ +=============== +Persistent data +=============== + Introduction ============
Documentation/device-mapper/snapshot.txt +60 -56
176 lines not on this page · raw message
Documentation/device-mapper/statistics.txt +32 -30
161 lines not on this page · raw message
Documentation/device-mapper/striped.txt +36 -32
87 lines not on this page · raw message
Documentation/device-mapper/switch.txt +25 -22
72 lines not on this page · raw message
Documentation/device-mapper/thin-provisioning.txt +42 -26
190 lines not on this page · raw message
Documentation/device-mapper/unstriped.txt +61 -50
134 lines not on this page · raw message
Documentation/device-mapper/verity.txt +15 -5
@@ -1,5 +1,6 @@ +========= dm-verity -========== +========= Device-Mapper's "verity" target provides transparent integrity checking of block devices using a cryptographic digest provided by the kernel crypto API.
@@ -7,6 +8,9 @@ This target is read-only. Construction Parameters ======================= + +:: + <version> <dev> <hash_dev> <data_block_size> <hash_block_size> <num_data_blocks> <hash_start_block>
@@ -160,7 +164,9 @@ calculating the parent node. The tree looks something like: -alg = sha256, num_blocks = 32768, block_size = 4096 + alg = sha256, num_blocks = 32768, block_size = 4096 + +:: [ root ] / . . . \
@@ -189,6 +195,7 @@ block boundary) are the hash blocks which are stored a depth at a time The full specification of kernel parameters and on-disk metadata format is available at the cryptsetup project's wiki page + https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity Status
@@ -198,7 +205,8 @@ If any check failed, C (for Corruption) is returned. Example ======= -Set up a device: +Set up a device:: + # dmsetup create vroot --readonly --table \ "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\ "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
@@ -209,11 +217,13 @@ the hash tree or activate the kernel device. This is available from the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/ (as a libcryptsetup extension). -Create hash on the device: +Create hash on the device:: + # veritysetup format /dev/sda1 /dev/sda2 ... Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 -Activate the device: +Activate the device:: + # veritysetup create vroot /dev/sda1 /dev/sda2 \ 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
Documentation/device-mapper/writecache.txt +11 -2
@@ -1,3 +1,7 @@ +================= +Writecache target +================= + The writecache target caches writes on persistent memory or on SSD. It doesn't cache reads because reads are supposed to be cached in page cache in normal RAM.
@@ -6,15 +10,18 @@ When the device is constructed, the first sector should be zeroed or the first sector should contain valid superblock from previous invocation. Constructor parameters: + 1. type of the cache device - "p" or "s" - p - persistent memory - s - SSD + + - p - persistent memory + - s - SSD 2. the underlying device that will be cached 3. the cache device 4. block size (4096 is recommended; the maximum block size is the page size) 5. the number of optional parameters (the parameters with an argument count as two) + start_sector n (default: 0) offset from the start of cache device in 512-byte sectors high_watermark n (default: 50)
@@ -43,6 +50,7 @@ Constructor parameters: applicable only to persistent memory - don't use the FUA flag when writing back data and send the FLUSH request afterwards + - some underlying devices perform better with fua, some with nofua. The user should test it
@@ -60,6 +68,7 @@ Messages: flush the cache device on next suspend. Use this message when you are going to remove the cache device. The proper sequence for removing the cache device is: + 1. send the "flush_on_suspend" message 2. load an inactive table with a linear target that maps to the underlying device
Documentation/device-mapper/zero.txt +7 -7
@@ -1,3 +1,4 @@ +======= dm-zero =======
@@ -18,20 +19,19 @@ filesystem limitations. To create a sparse device, start by creating a dm-zero device that's the desired size of the sparse device. For this example, we'll assume a 10TB -sparse device. +sparse device:: -TEN_TERABYTES=`expr 10 \* 1024 \* 1024 \* 1024 \* 2` # 10 TB in sectors -echo "0 $TEN_TERABYTES zero" | dmsetup create zero1 + TEN_TERABYTES=`expr 10 \* 1024 \* 1024 \* 1024 \* 2` # 10 TB in sectors + echo "0 $TEN_TERABYTES zero" | dmsetup create zero1 Then create a snapshot of the zero device, using any available block-device as the COW device. The size of the COW device will determine the amount of real space available to the sparse device. For this example, we'll assume /dev/sdb1 -is an available 10GB partition. +is an available 10GB partition:: -echo "0 $TEN_TERABYTES snapshot /dev/mapper/zero1 /dev/sdb1 p 128" | \ - dmsetup create sparse1 + echo "0 $TEN_TERABYTES snapshot /dev/mapper/zero1 /dev/sdb1 p 128" | \ + dmsetup create sparse1 This will create a 10TB sparse device called /dev/mapper/sparse1 that has 10GB of actual storage space available. If more than 10GB of data is written to this device, it will start returning I/O errors. -
Signature · 1 line
2.20.1
Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
Quoted 1 line · Mauro Carvalho Chehab
Convert the Device Mapper documentation to ReST.
Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.
Please advise, thanks.
Mike
Jonathan Corbet
maintainerRe: [PATCH 10/57] docs: device-mapper: convert it to ReST format
Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:
Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.
This is a discussion that was mostly resolved some years ago...
Classic Documentation/ is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.
The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:
https://www.kernel.org/doc/html/latest/
Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.
Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.
Thanks,
jon
Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
Em Tue, 16 Apr 2019 08:00:24 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 15 lines
Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:
Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.
This is a discussion that was mostly resolved some years ago...
Classic
Documentation/is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.
Quoted 6 lines
The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:
Just to mention, in the specific case of the device-mapper patch, this is the result of those changes (after renaming the files to .rst, and adding an index file):
https://www.infradead.org/~mchehab/rst_conversion/device-mapper/index.html
Quoted 14 lines
Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.
Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.
Quoted 3 lines
Thanks,
jon
Thanks,
Mauro
Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
In reply to Jonathan CorbetQuoted 27 lines · Jonathan Corbet
Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:
Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.
This is a discussion that was mostly resolved some years ago...
Classic
Documentation/is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:
https://www.kernel.org/doc/html/latest/
Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.
Quoted 5 lines
Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.
Thanks for the context. I clearly just haven't followed the evolution. Certainly looks like a solid improvement.
Think the last piece I'm missing is: how does one edit a .rst document without having to know to sprinkle syntactic sugar around? Does emacs have a ReST mode? If not what client interface are people using to properly change these documents?
(apologies if this is all spelled out nicely in Documentation/ somewhere, but please help this man learn to fish).
Thanks,
Mike
Jonathan Corbet
maintainerRe: [PATCH 10/57] docs: device-mapper: convert it to ReST format
Quoted 4 lines · On Tue, 16 Apr 2019 11:48:59 -0400 Mike Snitzer <[email protected]> wrote:
Think the last piece I'm missing is: how does one edit a .rst document without having to know to sprinkle syntactic sugar around? Does emacs have a ReST mode? If not what client interface are people using to properly change these documents?
There is an RST mode for Emacs, yes. But you likely don't really need it. RST is a simple format and, in general, we try to keep the markup to a minimum so that the plain-text files remain as readable as possible. Most of our documents are 99% RST before anybody gets around to formally converting them.
Quoted 2 lines
(apologies if this is all spelled out nicely in
Documentation/somewhere, but please help this man learn to fish).
Basics in Documentation/doc-guide (or
https://www.kernel.org/doc/html/latest/doc-guide/index.html). There's also some history and overview in:
https://lwn.net/Articles/692704/ https://lwn.net/Articles/692705/
Thanks,
jon
Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format
In reply to Mike SnitzerEm Tue, 16 Apr 2019 11:48:59 -0400
Mike Snitzer <[email protected]> escreveu:
Quoted 36 lines
Quoted 27 lines · Jonathan Corbet
Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:
Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.
This is a discussion that was mostly resolved some years ago...
Classic
Documentation/is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:
https://www.kernel.org/doc/html/latest/
Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.
Quoted 5 lines
Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.
Quoted 7 lines
Thanks for the context. I clearly just haven't followed the evolution. Certainly looks like a solid improvement.
Think the last piece I'm missing is: how does one edit a .rst document without having to know to sprinkle syntactic sugar around? Does emacs have a ReST mode? If not what client interface are people using to properly change these documents?
I guess the main point is that, after writing a .rst file, run "make htmldocs" and see how it fits :-)
As Jon mentioned, a large number of documents (even some written lots of years ago) already fits into ReST, and keeping it simpler makes easier for plain text file readers.
We do have some documents (like the media book), were we use a lot of the markup stuff, as those documents came from DocBook and it is full of cross-references, complex tables, images, examples, etc, but for most subsystems, you're safe with the usual stuff.
Quoted 3 lines
(apologies if this is all spelled out nicely in
Documentation/somewhere, but please help this man learn to fish).
A few tips if you want to write documents that are easy to read as text files and produce nice output after parsed:
1) it is written to document Python. So, it is indentation sensitive. Usually most of the fixes are just to properly indent things;
2) By default, it identifies line breaks with two \n. The exceptions are literal blocks like:
::
foo
bar
and things like:
foo
bar
(in this case, it will bold **foo**)
Another trick that I use to avoid the need of adding an extra \n is to convert itemized lists into a table, with:
=== foo bar ===
3) Things like "struct *foo" usually produces error, as a single
* is interpreted as italic. The parser will look for another *. As it won't find, it will produce an error. So, this need to be escaped somehow.
While you can escape such special characters like * and _ with an inverted bar, like "struct \*foo", that looks ugly for casual text file readers.
Instead, I do either::
struct *foo
or, if I want it in the middle of a text, I use struct *foo. IMO, placing it on a literal block (::) looks visually better for both text and html modes.
Thanks,
Mauro
PATCH 11/57 docs: extcon: move it to acpi dir and convert it to ReST
In reply to Mauro Carvalho ChehabThe 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.
For now, keep it with .txt extension, in order to avoid Sphinx build noise. A later patch should change it to .rst and movin it to be together with other acpi docs.
---
.../drivers/extcon-intel-int3496.txt} | 14 ++++++++++----
MAINTAINERS | 2 +-
2 files changed, 11 insertions(+), 5 deletions(-)
rename Documentation/{extcon/intel-int3496.txt => acpi/drivers/extcon-intel-int3496.txt} (66%)Documentation/acpi/drivers/extcon-intel-int3496.txt renamed from Documentation/extcon/intel-int3496.txt +10 -4
@@ -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 + ======= =======
MAINTAINERS +1 -1
@@ -5958,7 +5958,7 @@ S: Maintained F: drivers/extcon/ F: include/linux/extcon/ F: include/linux/extcon.h -F: Documentation/extcon/ +F: Documentation/acpi/drivers/extcon-intel-int3496.txt F: Documentation/devicetree/bindings/extcon/ EXYNOS DP DRIVER
Signature · 1 line
2.20.1
PATCH 12/57 docs: fault-injection: convert it to ReST format
In reply to Mauro Carvalho ChehabInstead of using plain text, convert it to ReST format, in order for the docs to be parsed and produce html and pdf output.
--- .../fault-injection/fault-injection.txt | 265 +++++++++--------- .../fault-injection/notifier-error-inject.txt | 18 +- .../fault-injection/nvme-fault-injection.txt | 174 ++++++------ .../fault-injection/provoke-crashes.txt | 40 ++- 4 files changed, 263 insertions(+), 234 deletions(-)
Documentation/fault-injection/fault-injection.txt +138 -127
@@ -1,3 +1,4 @@ +=========================================== Fault injection capabilities infrastructure ===========================================
@@ -7,36 +8,36 @@ See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug. Available fault injection capabilities -------------------------------------- -o failslab +- failslab injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...) -o fail_page_alloc +- fail_page_alloc injects page allocation failures. (alloc_pages(), get_free_pages(), ...) -o fail_futex +- fail_futex injects futex deadlock and uaddr fault errors. -o fail_make_request +- fail_make_request injects disk IO errors on devices permitted by setting /sys/block/<device>/make-it-fail or /sys/block/<device>/<partition>/make-it-fail. (generic_make_request()) -o fail_mmc_request +- fail_mmc_request injects MMC data errors on devices permitted by setting debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request -o fail_function +- fail_function injects error return on specific functions, which are marked by ALLOW_ERROR_INJECTION() macro, by setting debugfs entries under /sys/kernel/debug/fail_function. No boot option supported. -o NVMe fault injection +- NVMe fault injection inject NVMe status code and retry flag on devices permitted by setting debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default
@@ -47,7 +48,8 @@ o NVMe fault injection Configure fault-injection capabilities behavior ----------------------------------------------- -o debugfs entries +debugfs entries +^^^^^^^^^^^^^^^ fault-inject-debugfs kernel module provides some debugfs entries for runtime configuration of fault-injection capabilities.
@@ -55,6 +57,7 @@ configuration of fault-injection capabilities. - /sys/kernel/debug/fail*/probability: likelihood of failure injection, in percent. + Format: <percent> Note that one-failure-per-hundred is a very high error rate
@@ -83,6 +86,7 @@ configuration of fault-injection capabilities. - /sys/kernel/debug/fail*/verbose Format: { 0 | 1 | 2 } + specifies the verbosity of the messages when failure is injected. '0' means no messages; '1' will print only a single log line per failure; '2' will print a call trace too -- useful
@@ -91,14 +95,15 @@ configuration of fault-injection capabilities. - /sys/kernel/debug/fail*/task-filter: Format: { 'Y' | 'N' } + A value of 'N' disables filtering by process (default). Any positive value limits failures to only processes indicated by /proc/<pid>/make-it-fail==1. -- /sys/kernel/debug/fail*/require-start: -- /sys/kernel/debug/fail*/require-end: -- /sys/kernel/debug/fail*/reject-start: -- /sys/kernel/debug/fail*/reject-end: +- /sys/kernel/debug/fail*/require-start, + /sys/kernel/debug/fail*/require-end, + /sys/kernel/debug/fail*/reject-start, + /sys/kernel/debug/fail*/reject-end: specifies the range of virtual addresses tested during stacktrace walking. Failure is injected only if some caller
@@ -116,6 +121,7 @@ configuration of fault-injection capabilities. - /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem: Format: { 'Y' | 'N' } + default is 'N', setting it to 'Y' won't inject failures into highmem/user allocations.
@@ -123,6 +129,7 @@ configuration of fault-injection capabilities. - /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait: Format: { 'Y' | 'N' } + default is 'N', setting it to 'Y' will inject failures only into non-sleep allocations (GFP_ATOMIC allocations).
@@ -134,12 +141,14 @@ configuration of fault-injection capabilities. - /sys/kernel/debug/fail_futex/ignore-private: Format: { 'Y' | 'N' } + default is 'N', setting it to 'Y' will disable failure injections when dealing with private (address space) futexes. - /sys/kernel/debug/fail_function/inject: Format: { 'function-name' | '!function-name' | '' } + specifies the target function of error injection by name. If the function name leads '!' prefix, given function is removed from injection list. If nothing specified ('')
@@ -160,10 +169,11 @@ configuration of fault-injection capabilities. function for given function. This will be created when user specifies new injection entry. -o Boot option +Boot option +^^^^^^^^^^^ In order to inject faults while debugfs is not available (early boot time), -use the boot option: +use the boot option:: failslab= fail_page_alloc=
@@ -171,10 +181,11 @@ use the boot option: fail_futex= mmc_core.fail_request=<interval>,<probability>,<space>,<times> -o proc entries +proc entries +^^^^^^^^^^^^ -- /proc/<pid>/fail-nth: -- /proc/self/task/<tid>/fail-nth: +- /proc/<pid>/fail-nth, + /proc/self/task/<tid>/fail-nth: Write to this file of integer N makes N-th call in the task fail. Read from this file returns a integer value. A value of '0' indicates
@@ -191,16 +202,16 @@ o proc entries How to add new fault injection capability ----------------------------------------- -o #include <linux/fault-inject.h> +- #include <linux/fault-inject.h> -o define the fault attributes +- define the fault attributes DECLARE_FAULT_ATTR(name); Please see the definition of struct fault_attr in fault-inject.h for details. -o provide a way to configure fault attributes +- provide a way to configure fault attributes - boot option
@@ -222,126 +233,126 @@ o provide a way to configure fault attributes single kernel module, it is better to provide module parameters to configure the fault attributes. -o add a hook to insert failures +- add a hook to insert failures - Upon should_fail() returning true, client code should inject a failure. + Upon should_fail() returning true, client code should inject a failure: should_fail(attr, size); Application Examples -------------------- -o Inject slab allocation failures into module init/exit code +- Inject slab allocation failures into module init/exit code:: -#!/bin/bash + #!/bin/bash -FAILTYPE=failslab -echo Y > /sys/kernel/debug/$FAILTYPE/task-filter -echo 10 > /sys/kernel/debug/$FAILTYPE/probability -echo 100 > /sys/kernel/debug/$FAILTYPE/interval -echo -1 > /sys/kernel/debug/$FAILTYPE/times -echo 0 > /sys/kernel/debug/$FAILTYPE/space -echo 2 > /sys/kernel/debug/$FAILTYPE/verbose -echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait + FAILTYPE=failslab + echo Y > /sys/kernel/debug/$FAILTYPE/task-filter + echo 10 > /sys/kernel/debug/$FAILTYPE/probability + echo 100 > /sys/kernel/debug/$FAILTYPE/interval + echo -1 > /sys/kernel/debug/$FAILTYPE/times + echo 0 > /sys/kernel/debug/$FAILTYPE/space + echo 2 > /sys/kernel/debug/$FAILTYPE/verbose + echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait -faulty_system() -{ + faulty_system() + { bash -c "echo 1 > /proc/self/make-it-fail && exec $*" -} + } -if [ $# -eq 0 ] -then + if [ $# -eq 0 ] + then echo "Usage: $0 modulename [ modulename ... ]" exit 1 -fi + fi -for m in $* -do + for m in $* + do echo inserting $m... faulty_system modprobe $m echo removing $m... faulty_system modprobe -r $m -done + done ------------------------------------------------------------------------------ -o Inject page allocation failures only for a specific module +- Inject page allocation failures only for a specific module:: -#!/bin/bash + #!/bin/bash -FAILTYPE=fail_page_alloc -module=$1 + FAILTYPE=fail_page_alloc + module=$1 -if [ -z $module ] -then + if [ -z $module ] + then echo "Usage: $0 <modulename>" exit 1 -fi + fi -modprobe $module + modprobe $module -if [ ! -d /sys/module/$module/sections ] -then + if [ ! -d /sys/module/$module/sections ] + then echo Module $module is not loaded exit 1 -fi + fi -cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start -cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end + cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start + cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end -echo N > /sys/kernel/debug/$FAILTYPE/task-filter -echo 10 > /sys/kernel/debug/$FAILTYPE/probability -echo 100 > /sys/kernel/debug/$FAILTYPE/interval -echo -1 > /sys/kernel/debug/$FAILTYPE/times -echo 0 > /sys/kernel/debug/$FAILTYPE/space -echo 2 > /sys/kernel/debug/$FAILTYPE/verbose -echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait -echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem -echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth + echo N > /sys/kernel/debug/$FAILTYPE/task-filter + echo 10 > /sys/kernel/debug/$FAILTYPE/probability + echo 100 > /sys/kernel/debug/$FAILTYPE/interval + echo -1 > /sys/kernel/debug/$FAILTYPE/times + echo 0 > /sys/kernel/debug/$FAILTYPE/space + echo 2 > /sys/kernel/debug/$FAILTYPE/verbose + echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait + echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem + echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth -trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT + trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT -echo "Injecting errors into the module $module... (interrupt to stop)" -sleep 1000000 + echo "Injecting errors into the module $module... (interrupt to stop)" + sleep 1000000 ------------------------------------------------------------------------------ -o Inject open_ctree error while btrfs mount +- Inject open_ctree error while btrfs mount:: -#!/bin/bash + #!/bin/bash -rm -f testfile.img -dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1 -DEVICE=$(losetup --show -f testfile.img) -mkfs.btrfs -f $DEVICE -mkdir -p tmpmnt + rm -f testfile.img + dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1 + DEVICE=$(losetup --show -f testfile.img) + mkfs.btrfs -f $DEVICE + mkdir -p tmpmnt -FAILTYPE=fail_function -FAILFUNC=open_ctree -echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject -echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval -echo N > /sys/kernel/debug/$FAILTYPE/task-filter -echo 100 > /sys/kernel/debug/$FAILTYPE/probability -echo 0 > /sys/kernel/debug/$FAILTYPE/interval -echo -1 > /sys/kernel/debug/$FAILTYPE/times -echo 0 > /sys/kernel/debug/$FAILTYPE/space -echo 1 > /sys/kernel/debug/$FAILTYPE/verbose + FAILTYPE=fail_function + FAILFUNC=open_ctree + echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject + echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval + echo N > /sys/kernel/debug/$FAILTYPE/task-filter + echo 100 > /sys/kernel/debug/$FAILTYPE/probability + echo 0 > /sys/kernel/debug/$FAILTYPE/interval + echo -1 > /sys/kernel/debug/$FAILTYPE/times + echo 0 > /sys/kernel/debug/$FAILTYPE/space + echo 1 > /sys/kernel/debug/$FAILTYPE/verbose -mount -t btrfs $DEVICE tmpmnt -if [ $? -ne 0 ] -then + mount -t btrfs $DEVICE tmpmnt + if [ $? -ne 0 ] + then echo "SUCCESS!" -else + else echo "FAILED!" umount tmpmnt -fi + fi -echo > /sys/kernel/debug/$FAILTYPE/inject + echo > /sys/kernel/debug/$FAILTYPE/inject -rmdir tmpmnt -losetup -d $DEVICE -rm testfile.img + rmdir tmpmnt + losetup -d $DEVICE + rm testfile.img Tool to run command with failslab or fail_page_alloc
@@ -354,43 +365,43 @@ see the following examples. Examples: Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab -allocation failure. +allocation failure:: # ./tools/testing/fault-injection/failcmd.sh \ -- make -C tools/testing/selftests/ run_tests Same as above except to specify 100 times failures at most instead of one time -at most by default. +at most by default:: # ./tools/testing/fault-injection/failcmd.sh --times=100 \ -- make -C tools/testing/selftests/ run_tests Same as above except to inject page allocation failure instead of slab -allocation failure. +allocation failure:: # env FAILCMD_TYPE=fail_page_alloc \ ./tools/testing/fault-injection/failcmd.sh --times=100 \ - -- make -C tools/testing/selftests/ run_tests + -- make -C tools/testing/selftests/ run_tests Systematic faults using fail-nth --------------------------------- The following code systematically faults 0-th, 1-st, 2-nd and so on -capabilities in the socketpair() system call. +capabilities in the socketpair() system call:: -#include <sys/types.h> -#include <sys/stat.h> -#include <sys/socket.h> -#include <sys/syscall.h> -#include <fcntl.h> -#include <unistd.h> -#include <string.h> -#include <stdlib.h> -#include <stdio.h> -#include <errno.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <sys/socket.h> + #include <sys/syscall.h> + #include <fcntl.h> + #include <unistd.h> + #include <string.h> + #include <stdlib.h> + #include <stdio.h> + #include <errno.h> -int main() -{ + int main() + { int i, err, res, fail_nth, fds[2]; char buf[128];
@@ -413,23 +424,23 @@ int main() break; } return 0; -} + } -An example output: +An example output:: -1-th fault Y: res=-1/23 -2-th fault Y: res=-1/23 -3-th fault Y: res=-1/12 -4-th fault Y: res=-1/12 -5-th fault Y: res=-1/23 -6-th fault Y: res=-1/23 -7-th fault Y: res=-1/23 -8-th fault Y: res=-1/12 -9-th fault Y: res=-1/12 -10-th fault Y: res=-1/12 -11-th fault Y: res=-1/12 -12-th fault Y: res=-1/12 -13-th fault Y: res=-1/12 -14-th fault Y: res=-1/12 -15-th fault Y: res=-1/12 -16-th fault N: res=0/12 + 1-th fault Y: res=-1/23 + 2-th fault Y: res=-1/23 + 3-th fault Y: res=-1/12 + 4-th fault Y: res=-1/12 + 5-th fault Y: res=-1/23 + 6-th fault Y: res=-1/23 + 7-th fault Y: res=-1/23 + 8-th fault Y: res=-1/12 + 9-th fault Y: res=-1/12 + 10-th fault Y: res=-1/12 + 11-th fault Y: res=-1/12 + 12-th fault Y: res=-1/12 + 13-th fault Y: res=-1/12 + 14-th fault Y: res=-1/12 + 15-th fault Y: res=-1/12 + 16-th fault N: res=0/12
Documentation/fault-injection/notifier-error-inject.txt +11 -7
@@ -14,7 +14,8 @@ modules that can be used to test the following notifiers. PM notifier error injection module ---------------------------------- This feature is controlled through debugfs interface -/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error + + /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error Possible PM notifier events to be failed are:
@@ -22,7 +23,7 @@ Possible PM notifier events to be failed are: * PM_SUSPEND_PREPARE * PM_RESTORE_PREPARE -Example: Inject PM suspend error (-12 = -ENOMEM) +Example: Inject PM suspend error (-12 = -ENOMEM):: # cd /sys/kernel/debug/notifier-error-inject/pm/ # echo -12 > actions/PM_SUSPEND_PREPARE/error
@@ -32,14 +33,15 @@ Example: Inject PM suspend error (-12 = -ENOMEM) Memory hotplug notifier error injection module ---------------------------------------------- This feature is controlled through debugfs interface -/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error + + /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error Possible memory notifier events to be failed are: * MEM_GOING_ONLINE * MEM_GOING_OFFLINE -Example: Inject memory hotplug offline error (-12 == -ENOMEM) +Example: Inject memory hotplug offline error (-12 == -ENOMEM):: # cd /sys/kernel/debug/notifier-error-inject/memory # echo -12 > actions/MEM_GOING_OFFLINE/error
@@ -49,7 +51,8 @@ Example: Inject memory hotplug offline error (-12 == -ENOMEM) powerpc pSeries reconfig notifier error injection module -------------------------------------------------------- This feature is controlled through debugfs interface -/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error + + /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error Possible pSeries reconfig notifier events to be failed are:
@@ -61,7 +64,8 @@ Possible pSeries reconfig notifier events to be failed are: Netdevice notifier error injection module ---------------------------------------------- This feature is controlled through debugfs interface -/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error + + /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error Netdevice notifier events which can be failed are:
@@ -75,7 +79,7 @@ Netdevice notifier events which can be failed are: * NETDEV_PRECHANGEUPPER * NETDEV_CHANGEUPPER -Example: Inject netdevice mtu change error (-22 == -EINVAL) +Example: Inject netdevice mtu change error (-22 == -EINVAL):: # cd /sys/kernel/debug/notifier-error-inject/netdev # echo -22 > actions/NETDEV_CHANGEMTU/error
Documentation/fault-injection/nvme-fault-injection.txt +89 -85
190 lines not on this page · raw message
Documentation/fault-injection/provoke-crashes.txt +25 -15
@@ -1,3 +1,7 @@ +=============== +Provoke crashes +=============== + The lkdtm module provides an interface to crash or injure the kernel at predefined crashpoints to evaluate the reliability of crash dumps obtained using different dumping solutions. The module uses KPROBEs to instrument
@@ -8,31 +12,37 @@ support. You can provide the way either through module arguments when inserting the module, or through a debugfs interface. -Usage: insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<> - [cpoint_count={>0}] +Usage:: - recur_count : Recursion level for the stack overflow test. Default is 10. + insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<> + [cpoint_count={>0}] - cpoint_name : Crash point where the kernel is to be crashed. It can be - one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY, - FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD, - IDE_CORE_CP, DIRECT +recur_count + Recursion level for the stack overflow test. Default is 10. - cpoint_type : Indicates the action to be taken on hitting the crash point. - It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW, - CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION, - WRITE_AFTER_FREE, +cpoint_name + Crash point where the kernel is to be crashed. It can be + one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY, + FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD, + IDE_CORE_CP, DIRECT - cpoint_count : Indicates the number of times the crash point is to be hit - to trigger an action. The default is 10. +cpoint_type + Indicates the action to be taken on hitting the crash point. + It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW, + CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION, + WRITE_AFTER_FREE, + +cpoint_count + Indicates the number of times the crash point is to be hit + to trigger an action. The default is 10. You can also induce failures by mounting debugfs and writing the type to -<mountpoint>/provoke-crash/<crashpoint>. E.g., +<mountpoint>/provoke-crash/<crashpoint>. E.g.:: mount -t debugfs debugfs /mnt echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY -A special file is `DIRECT' which will induce the crash directly without +A special file is `DIRECT` which will induce the crash directly without KPROBE instrumentation. This mode is the only one available when the module is built on a kernel without KPROBEs support.
Signature · 1 line
2.20.1
PATCH 13/57 docs: fb: convert documentation to ReST format
In reply to Mauro Carvalho ChehabConvert all documents here from plain txt to ReST format, in order to allow parsing them with the documentation build system.
--- Documentation/fb/api.txt | 29 +- Documentation/fb/arkfb.txt | 8 +- Documentation/fb/aty128fb.txt | 31 +- Documentation/fb/cirrusfb.txt | 47 ++- Documentation/fb/cmap_xfbdev.txt | 57 ++-- Documentation/fb/deferred_io.txt | 28 +- Documentation/fb/efifb.txt | 18 +- Documentation/fb/ep93xx-fb.txt | 25 +- Documentation/fb/fbcon.txt | 177 ++++++----- Documentation/fb/framebuffer.txt | 79 +++-- Documentation/fb/gxfb.txt | 22 +- Documentation/fb/intel810.txt | 77 +++-- Documentation/fb/intelfb.txt | 62 ++-- Documentation/fb/internals.txt | 24 +- Documentation/fb/lxfb.txt | 23 +- Documentation/fb/matroxfb.txt | 526 ++++++++++++++++--------------- Documentation/fb/metronomefb.txt | 8 +- Documentation/fb/modedb.txt | 44 +-- Documentation/fb/pvr2fb.txt | 55 ++-- Documentation/fb/pxafb.txt | 81 +++-- Documentation/fb/s3fb.txt | 8 +- Documentation/fb/sa1100fb.txt | 23 +- Documentation/fb/sh7760fb.txt | 153 +++++---- Documentation/fb/sisfb.txt | 40 +-- Documentation/fb/sm501.txt | 7 +- Documentation/fb/sm712fb.txt | 18 +- Documentation/fb/sstfb.txt | 231 ++++++++------ Documentation/fb/tgafb.txt | 30 +- Documentation/fb/tridentfb.txt | 34 +- Documentation/fb/udlfb.txt | 55 ++-- Documentation/fb/uvesafb.txt | 128 ++++---- Documentation/fb/vesafb.txt | 121 +++---- Documentation/fb/viafb.txt | 393 +++++++++++++---------- Documentation/fb/vt8623fb.txt | 10 +- 34 files changed, 1455 insertions(+), 1217 deletions(-)
Documentation/fb/api.txt +15 -14
@@ -1,5 +1,6 @@ - The Frame Buffer Device API - --------------------------- +=========================== +The Frame Buffer Device API +=========================== Last revised: June 21, 2011
@@ -21,13 +22,13 @@ deal with different behaviours. --------------- Device and driver capabilities are reported in the fixed screen information -capabilities field. +capabilities field:: -struct fb_fix_screeninfo { + struct fb_fix_screeninfo { ... __u16 capabilities; /* see FB_CAP_* */ ... -}; + }; Application should use those capabilities to find out what features they can expect from the device and driver.
@@ -151,9 +152,9 @@ fb_fix_screeninfo and fb_var_screeninfo structure respectively. struct fb_fix_screeninfo stores device independent unchangeable information about the frame buffer device and the current format. Those information can't be directly modified by applications, but can be changed by the driver when an -application modifies the format. +application modifies the format:: -struct fb_fix_screeninfo { + struct fb_fix_screeninfo { char id[16]; /* identification string eg "TT Builtin" */ unsigned long smem_start; /* Start of frame buffer mem */ /* (physical address) */
@@ -172,13 +173,13 @@ struct fb_fix_screeninfo { /* specific chip/card we have */ __u16 capabilities; /* see FB_CAP_* */ __u16 reserved[2]; /* Reserved for future compatibility */ -}; + }; struct fb_var_screeninfo stores device independent changeable information about a frame buffer device, its current format and video mode, as well as -other miscellaneous parameters. +other miscellaneous parameters:: -struct fb_var_screeninfo { + struct fb_var_screeninfo { __u32 xres; /* visible resolution */ __u32 yres; __u32 xres_virtual; /* virtual resolution */
@@ -216,7 +217,7 @@ struct fb_var_screeninfo { __u32 rotate; /* angle we rotate counter clockwise */ __u32 colorspace; /* colorspace for FOURCC-based modes */ __u32 reserved[4]; /* Reserved for future compatibility */ -}; + }; To modify variable information, applications call the FBIOPUT_VSCREENINFO ioctl with a pointer to a fb_var_screeninfo structure. If the call is
@@ -255,14 +256,14 @@ monochrome, grayscale or pseudocolor visuals, although this is not required. - For truecolor and directcolor formats, applications set the grayscale field to zero, and the red, blue, green and transp fields to describe the layout of - color components in memory. + color components in memory:: -struct fb_bitfield { + struct fb_bitfield { __u32 offset; /* beginning of bitfield */ __u32 length; /* length of bitfield */ __u32 msb_right; /* != 0 : Most significant bit is */ /* right */ -}; + }; Pixel values are bits_per_pixel wide and are split in non-overlapping red, green, blue and alpha (transparency) components. Location and size of each
Documentation/fb/arkfb.txt +4 -4
@@ -1,6 +1,6 @@ - - arkfb - fbdev driver for ARK Logic chips - ======================================== +======================================== +arkfb - fbdev driver for ARK Logic chips +======================================== Supported Hardware
@@ -47,7 +47,7 @@ Missing Features (alias TODO list) * secondary (not initialized by BIOS) device support - * big endian support + * big endian support * DPMS support * MMIO support * interlaced mode variant
Documentation/fb/aty128fb.txt +17 -14
@@ -1,8 +1,9 @@ -[This file is cloned from VesaFB/matroxfb] - +================= What is aty128fb? ================= +.. [This file is cloned from VesaFB/matroxfb] + This is a driver for a graphic framebuffer for ATI Rage128 based devices on Intel and PPC boxes.
@@ -24,14 +25,14 @@ How to use it? ============== Switching modes is done using the video=aty128fb:<resolution>... modedb -boot parameter or using `fbset' program. +boot parameter or using `fbset` program. See Documentation/fb/modedb.txt for more information on modedb resolutions. You should compile in both vgacon (to boot if you remove your Rage128 from box) and aty128fb (for graphics mode). You should not compile-in vesafb -unless you have primary display on non-Rage128 VBE2.0 device (see +unless you have primary display on non-Rage128 VBE2.0 device (see Documentation/fb/vesafb.txt for details).
@@ -48,16 +49,18 @@ Configuration ============= You can pass kernel command line options to vesafb with -`video=aty128fb:option1,option2:value2,option3' (multiple options should -be separated by comma, values are separated from options by `:'). +`video=aty128fb:option1,option2:value2,option3` (multiple options should +be separated by comma, values are separated from options by `:`). Accepted options: -noaccel - do not use acceleration engine. It is default. -accel - use acceleration engine. Not finished. -vmode:x - chooses PowerMacintosh video mode <x>. Deprecated. -cmode:x - chooses PowerMacintosh colour mode <x>. Deprecated. -<XxX@X> - selects startup videomode. See modedb.txt for detailed - explanation. Default is 640x480x8bpp. +========= ======================================================= +noaccel do not use acceleration engine. It is default. +accel use acceleration engine. Not finished. +vmode:x chooses PowerMacintosh video mode <x>. Deprecated. +cmode:x chooses PowerMacintosh colour mode <x>. Deprecated. +<XxX@X> selects startup videomode. See modedb.txt for detailed + explanation. Default is 640x480x8bpp. +========= ======================================================= Limitations
@@ -65,8 +68,8 @@ Limitations There are known and unknown bugs, features and misfeatures. Currently there are following known bugs: - + This driver is still experimental and is not finished. Too many + + - This driver is still experimental and is not finished. Too many bugs/errata to list here. --- Brad Douglas <[email protected]>
Documentation/fb/cirrusfb.txt +22 -25
69 lines not on this page · raw message
Documentation/fb/cmap_xfbdev.txt +30 -27
82 lines not on this page · raw message
Documentation/fb/deferred_io.txt +16 -12
@@ -1,5 +1,6 @@ +=========== Deferred IO ------------ +=========== Deferred IO is a way to delay and repurpose IO. It uses host memory as a buffer and the MMU pagefault as a pretrigger for when to perform the device
@@ -16,7 +17,7 @@ works: - app continues writing to that page with no additional cost. this is the key benefit. - the workqueue task comes in and mkcleans the pages on the list, then - completes the work associated with updating the framebuffer. this is + completes the work associated with updating the framebuffer. this is the real work talking to the device. - app tries to write to the address (that has now been mkcleaned) - get pagefault and the above sequence occurs again
@@ -47,29 +48,32 @@ How to use it: (for fbdev drivers) ---------------------------------- The following example may be helpful. -1. Setup your structure. Eg: +1. Setup your structure. Eg:: -static struct fb_deferred_io hecubafb_defio = { - .delay = HZ, - .deferred_io = hecubafb_dpy_deferred_io, -}; + static struct fb_deferred_io hecubafb_defio = { + .delay = HZ, + .deferred_io = hecubafb_dpy_deferred_io, + }; The delay is the minimum delay between when the page_mkwrite trigger occurs and when the deferred_io callback is called. The deferred_io callback is explained below. -2. Setup your deferred IO callback. Eg: -static void hecubafb_dpy_deferred_io(struct fb_info *info, - struct list_head *pagelist) +2. Setup your deferred IO callback. Eg:: + + static void hecubafb_dpy_deferred_io(struct fb_info *info, + struct list_head *pagelist) The deferred_io callback is where you would perform all your IO to the display device. You receive the pagelist which is the list of pages that were written to during the delay. You must not modify this list. This callback is called from a workqueue. -3. Call init +3. Call init:: + info->fbdefio = &hecubafb_defio; fb_deferred_io_init(info); -4. Call cleanup +4. Call cleanup:: + fb_deferred_io_cleanup(info);
Documentation/fb/efifb.txt +10 -8
@@ -1,6 +1,6 @@ - +============== What is efifb? -=============== +============== This is a generic EFI platform driver for Intel based Apple computers. efifb is only for EFI booted Intel Macs.
@@ -8,16 +8,17 @@ efifb is only for EFI booted Intel Macs. Supported Hardware ================== -iMac 17"/20" -Macbook -Macbook Pro 15"/17" -MacMini +- iMac 17"/20" +- Macbook +- Macbook Pro 15"/17" +- MacMini How to use it? ============== efifb does not have any kind of autodetection of your machine. -You have to add the following kernel parameters in your elilo.conf: +You have to add the following kernel parameters in your elilo.conf:: + Macbook : video=efifb:macbook MacMini :
@@ -29,9 +30,10 @@ You have to add the following kernel parameters in your elilo.conf: Accepted options: +======= =========================================================== nowc Don't map the framebuffer write combined. This can be used to workaround side-effects and slowdowns on other CPU cores when large amounts of console data are written. +======= =========================================================== --- Edgar Hucek <[email protected]>
Documentation/fb/ep93xx-fb.txt +15 -10
@@ -4,7 +4,7 @@ Driver for EP93xx LCD controller The EP93xx LCD controller can drive both standard desktop monitors and embedded LCD displays. If you have a standard desktop monitor then you -can use the standard Linux video mode database. In your board file: +can use the standard Linux video mode database. In your board file:: static struct ep93xxfb_mach_info some_board_fb_info = { .num_modes = EP93XXFB_USE_MODEDB,
@@ -12,7 +12,7 @@ can use the standard Linux video mode database. In your board file: }; If you have an embedded LCD display then you need to define a video -mode for it as follows: +mode for it as follows:: static struct fb_videomode some_board_video_modes[] = { {
@@ -27,7 +27,7 @@ are in pixel clocks. See Documentation/fb/framebuffer.txt for further details. The ep93xxfb_mach_info structure for your board should look like the -following: +following:: static struct ep93xxfb_mach_info some_board_fb_info = { .num_modes = ARRAY_SIZE(some_board_video_modes),
@@ -37,7 +37,7 @@ following: }; The framebuffer device can be registered by adding the following to -your board initialisation function: +your board initialisation function:: ep93xx_register_fb(&some_board_fb_info);
@@ -50,6 +50,7 @@ to configure the controller. The video attributes flags are fully documented in section 7 of the EP93xx users' guide. The following flags are available: +=============================== ========================================== EP93XXFB_PCLK_FALLING Clock data on the falling edge of the pixel clock. The default is to clock data on the rising edge.
@@ -62,10 +63,12 @@ EP93XXFB_SYNC_HORIZ_HIGH Horizontal sync is active high. By EP93XXFB_SYNC_VERT_HIGH Vertical sync is active high. By default the vertical sync is active high. +=============================== ========================================== The physical address of the framebuffer can be controlled using the following flags: +=============================== ====================================== EP93XXFB_USE_SDCSN0 Use SDCSn[0] for the framebuffer. This is the default setting.
@@ -74,6 +77,7 @@ EP93XXFB_USE_SDCSN1 Use SDCSn[1] for the framebuffer. EP93XXFB_USE_SDCSN2 Use SDCSn[2] for the framebuffer. EP93XXFB_USE_SDCSN3 Use SDCSn[3] for the framebuffer. +=============================== ====================================== ================== Platform callbacks
@@ -87,7 +91,7 @@ blanked or unblanked. The setup and teardown devices pass the platform_device structure as an argument. The fb_info and ep93xxfb_mach_info structures can be -obtained as follows: +obtained as follows:: static int some_board_fb_setup(struct platform_device *pdev) {
@@ -101,17 +105,17 @@ obtained as follows: Setting the video mode ====================== -The video mode is set using the following syntax: +The video mode is set using the following syntax:: video=XRESxYRES[-BPP][@REFRESH] If the EP93xx video driver is built-in then the video mode is set on -the Linux kernel command line, for example: +the Linux kernel command line, for example:: video=ep93xx-fb:800x600-16@60 If the EP93xx video driver is built as a module then the video mode is -set when the module is installed: +set when the module is installed:: modprobe ep93xx-fb video=320x240
@@ -121,13 +125,14 @@ Screenpage bug At least on the EP9315 there is a silicon bug which causes bit 27 of the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is -an unofficial errata for this bug at: +an unofficial errata for this bug at:: + http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2 By default the EP93xx framebuffer driver checks if the allocated physical address has bit 27 set. If it does, then the memory is freed and an error is returned. The check can be disabled by adding the following -option when loading the driver: +option when loading the driver:: ep93xx-fb.check_screenpage_bug=0
Documentation/fb/fbcon.txt +90 -87
326 lines not on this page · raw message
Documentation/fb/framebuffer.txt +45 -34
202 lines not on this page · raw message
Documentation/fb/gxfb.txt +12 -10
@@ -1,7 +1,8 @@ -[This file is cloned from VesaFB/aty128fb] - +============= What is gxfb? -================= +============= + +.. [This file is cloned from VesaFB/aty128fb] This is a graphics framebuffer driver for AMD Geode GX2 based processors.
@@ -23,7 +24,7 @@ How to use it? ============== Switching modes is done using gxfb.mode_option=<resolution>... boot -parameter or using `fbset' program. +parameter or using `fbset` program. See Documentation/fb/modedb.txt for more information on modedb resolutions.
@@ -42,11 +43,12 @@ You can pass kernel command line options to gxfb with gxfb.<option>. For example, gxfb.mode_option=800x600@75. Accepted options: -mode_option - specify the video mode. Of the form - <x>x<y>[-<bpp>][@<refresh>] -vram - size of video ram (normally auto-detected) -vt_switch - enable vt switching during suspend/resume. The vt - switch is slow, but harmless. +================ ================================================== +mode_option specify the video mode. Of the form + <x>x<y>[-<bpp>][@<refresh>] +vram size of video ram (normally auto-detected) +vt_switch enable vt switching during suspend/resume. The vt + switch is slow, but harmless. +================ ================================================== --- Andres Salomon <[email protected]>
Documentation/fb/intel810.txt +43 -34
172 lines not on this page · raw message
Documentation/fb/intelfb.txt +34 -28
124 lines not on this page · raw message
Documentation/fb/internals.txt +14 -10
@@ -1,13 +1,19 @@ +============================= +Frame Buffer device internals +============================= This is a first start for some documentation about frame buffer device internals. -Geert Uytterhoeven <[email protected]>, 21 July 1998 -James Simmons <[email protected]>, Nov 26 2002 +Authors: + +- Geert Uytterhoeven <[email protected]>, 21 July 1998 +- James Simmons <[email protected]>, Nov 26 2002 -------------------------------------------------------------------------------- - *** STRUCTURES USED BY THE FRAME BUFFER DEVICE API *** +Structures used by the frame buffer device API +============================================== The following structures play a role in the game of frame buffer devices. They are defined in <linux/fb.h>.
@@ -40,19 +46,18 @@ are defined in <linux/fb.h>. Generic information, API and low level information about a specific frame buffer device instance (slot number, board address, ...). - - struct `par' + - struct `par` Device dependent information that uniquely defines the video mode for this particular piece of hardware. --------------------------------------------------------------------------------- - - *** VISUALS USED BY THE FRAME BUFFER DEVICE API *** +Visuals used by the frame buffer device API +=========================================== Monochrome (FB_VISUAL_MONO01 and FB_VISUAL_MONO10) -------------------------------------------------- +-------------------------------------------------- Each pixel is either black or white.
@@ -70,7 +75,7 @@ The pixel value is broken up into red, green, and blue fields. Direct color (FB_VISUAL_DIRECTCOLOR) ------------------------------------ -The pixel value is broken up into red, green, and blue fields, each of which +The pixel value is broken up into red, green, and blue fields, each of which are looked up in separate red, green, and blue lookup tables.
@@ -79,4 +84,3 @@ Grayscale displays Grayscale and static grayscale are special variants of pseudo color and static pseudo color, where the red, green and blue components are always equal to each other. -
Documentation/fb/lxfb.txt +13 -10
@@ -1,7 +1,9 @@ -[This file is cloned from VesaFB/aty128fb] - +============= What is lxfb? -================= +============= + +.. [This file is cloned from VesaFB/aty128fb] + This is a graphics framebuffer driver for AMD Geode LX based processors.
@@ -23,7 +25,7 @@ How to use it? ============== Switching modes is done using lxfb.mode_option=<resolution>... boot -parameter or using `fbset' program. +parameter or using `fbset` program. See Documentation/fb/modedb.txt for more information on modedb resolutions.
@@ -42,11 +44,12 @@ You can pass kernel command line options to lxfb with lxfb.<option>. For example, lxfb.mode_option=800x600@75. Accepted options: -mode_option - specify the video mode. Of the form - <x>x<y>[-<bpp>][@<refresh>] -vram - size of video ram (normally auto-detected) -vt_switch - enable vt switching during suspend/resume. The vt - switch is slow, but harmless. +================ ================================================== +mode_option specify the video mode. Of the form + <x>x<y>[-<bpp>][@<refresh>] +vram size of video ram (normally auto-detected) +vt_switch enable vt switching during suspend/resume. The vt + switch is slow, but harmless. +================ ================================================== --- Andres Salomon <[email protected]>
Documentation/fb/matroxfb.txt +278 -248
631 lines not on this page · raw message
Documentation/fb/metronomefb.txt +5 -3
@@ -1,6 +1,9 @@ - Metronomefb - ----------- +=========== +Metronomefb +=========== + Maintained by Jaya Kumar <jayakumar.lkml.gmail.com> + Last revised: Mar 10, 2008 Metronomefb is a driver for the Metronome display controller. The controller
@@ -33,4 +36,3 @@ the physical media. Metronomefb uses the deferred IO interface so that it can provide a memory mappable frame buffer. It has been tested with tinyx (Xfbdev). It is known to work at this time with xeyes, xclock, xloadimage, xpdf. -
Documentation/fb/modedb.txt +24 -20
93 lines not on this page · raw message
Documentation/fb/pvr2fb.txt +28 -27
77 lines not on this page · raw message
Documentation/fb/pxafb.txt +56 -25
178 lines not on this page · raw message
Documentation/fb/s3fb.txt +4 -4
@@ -1,6 +1,6 @@ - - s3fb - fbdev driver for S3 Trio/Virge chips - =========================================== +=========================================== +s3fb - fbdev driver for S3 Trio/Virge chips +=========================================== Supported Hardware
@@ -56,7 +56,7 @@ Missing Features (alias TODO list) * secondary (not initialized by BIOS) device support - * big endian support + * big endian support * Zorro bus support * MMIO support * 24 bpp mode support on more cards
Documentation/fb/sa1100fb.txt +12 -11
@@ -1,17 +1,19 @@ -[This file is cloned from VesaFB/matroxfb] - +================= What is sa1100fb? ================= +.. [This file is cloned from VesaFB/matroxfb] + + This is a driver for a graphic framebuffer for the SA-1100 LCD controller. Configuration ============== -For most common passive displays, giving the option +For most common passive displays, giving the option:: -video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value> + video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value> on the kernel command line should be enough to configure the controller. The bits per pixel (bpp) value should be 4, 8, 12, or
@@ -27,13 +29,12 @@ sa1100fb_init_fbinfo(), sa1100fb_activate_var(), sa1100fb_disable_lcd_controller(), and sa1100fb_enable_lcd_controller() will probably be necessary. -Accepted options: +Accepted options:: -bpp:<value> Configure for <value> bits per pixel -lccr0:<value> Configure LCD control register 0 (11.7.3) -lccr1:<value> Configure LCD control register 1 (11.7.4) -lccr2:<value> Configure LCD control register 2 (11.7.5) -lccr3:<value> Configure LCD control register 3 (11.7.6) + bpp:<value> Configure for <value> bits per pixel + lccr0:<value> Configure LCD control register 0 (11.7.3) + lccr1:<value> Configure LCD control register 1 (11.7.4) + lccr2:<value> Configure LCD control register 2 (11.7.5) + lccr3:<value> Configure LCD control register 3 (11.7.6) --- Mark Huang <[email protected]>
Documentation/fb/sh7760fb.txt +76 -77
176 lines not on this page · raw message
Documentation/fb/sisfb.txt +21 -19
@@ -1,4 +1,4 @@ - +============== What is sisfb? ==============
@@ -41,11 +41,11 @@ statement to add the parameters to the kernel command line. Please see lilo's parameters are given with the modprobe (or insmod) command. Example for sisfb as part of the static kernel: Add the following line to your -lilo.conf: +lilo.conf:: append="video=sisfb:mode:1024x768x16,mem:12288,rate:75" -Example for sisfb as a module: Start sisfb by typing +Example for sisfb as a module: Start sisfb by typing:: modprobe sisfb mode=1024x768x16 rate=75 mem=12288
@@ -57,7 +57,7 @@ described above or the vesa keyword instead of mode). If compiled as a module, the parameter format reads mode=none or mode=1024x768x16 (or whatever mode you want to use). Using a "=" for a ":" (and vice versa) is a huge difference! Additionally: If you give more than one argument to the in-kernel sisfb, the -arguments are separated with ",". For example: +arguments are separated with ",". For example:: video=sisfb:mode:1024x768x16,rate:75,mem:12288
@@ -73,6 +73,7 @@ supported options including some explanation. The desired display mode can be specified using the keyword "mode" with a parameter in one of the following formats: + - XxYxDepth or - XxY-Depth or - XxY-Depth@Rate or
@@ -130,29 +131,30 @@ Configuration (Some) accepted options: -off - Disable sisfb. This option is only understood if sisfb is - in-kernel, not a module. -mem:X - size of memory for the console, rest will be used for DRI/DRM. X - is in kilobytes. On 300 series, the default is 4096, 8192 or +========= ================================================================== +off Disable sisfb. This option is only understood if sisfb is + in-kernel, not a module. +mem:X size of memory for the console, rest will be used for DRI/DRM. X + is in kilobytes. On 300 series, the default is 4096, 8192 or 16384 (each in kilobyte) depending on how much video ram the card - has. On 315/330 series, the default is the maximum available ram + has. On 315/330 series, the default is the maximum available ram (since DRI/DRM is not supported for these chipsets). -noaccel - do not use 2D acceleration engine. (Default: use acceleration) -noypan - disable y-panning and scroll by redrawing the entire screen. - This is much slower than y-panning. (Default: use y-panning) -vesa:X - selects startup videomode. X is number from 0 to 0x1FF and - represents the VESA mode number (can be given in decimal or +noaccel do not use 2D acceleration engine. (Default: use acceleration) +noypan disable y-panning and scroll by redrawing the entire screen. + This is much slower than y-panning. (Default: use y-panning) +vesa:X selects startup videomode. X is number from 0 to 0x1FF and + represents the VESA mode number (can be given in decimal or hexadecimal form, the latter prefixed with "0x"). -mode:X - selects startup videomode. Please see above for the format of - "X". +mode:X selects startup videomode. Please see above for the format of + "X". +========= ================================================================== Boolean options such as "noaccel" or "noypan" are to be given without a parameter if sisfb is in-kernel (for example "video=sisfb:noypan). If sisfb is a module, these are to be set to 1 (for example "modprobe sisfb noypan=1"). --- + Thomas Winischhofer <[email protected]> + May 27, 2004 - -
Documentation/fb/sm501.txt +6 -1
@@ -1,6 +1,11 @@ +======= +sm501fb +======= + Configuration: -You can pass the following kernel command line options to sm501 videoframebuffer: +You can pass the following kernel command line options to sm501 +videoframebuffer:: sm501fb.bpp= SM501 Display driver: Specify bits-per-pixel if not specified by 'mode'
Documentation/fb/sm712fb.txt +11 -7
@@ -1,5 +1,6 @@ +================ What is sm712fb? -================= +================ This is a graphics framebuffer driver for Silicon Motion SM712 based processors.
@@ -15,13 +16,16 @@ You should not compile-in vesafb. Currently supported video modes are: -[Graphic modes] +Graphic modes +------------- -bpp | 640x480 800x600 1024x768 1280x1024 -----+-------------------------------------------- - 8 | 0x301 0x303 0x305 0x307 - 16 | 0x311 0x314 0x317 0x31A - 24 | 0x312 0x315 0x318 0x31B +=== ======= ======= ======== ========= +bpp 640x480 800x600 1024x768 1280x1024 +=== ======= ======= ======== ========= + 8 0x301 0x303 0x305 0x307 + 16 0x311 0x314 0x317 0x31A + 24 0x312 0x315 0x318 0x31B +=== ======= ======= ======== ========= Missing Features ================
Documentation/fb/sstfb.txt +132 -99
189 lines not on this page · raw message
Documentation/fb/udlfb.txt +29 -26
55 lines not on this page · raw message
Documentation/fb/uvesafb.txt +66 -62
128 lines not on this page · raw message
Documentation/fb/vesafb.txt +66 -55
121 lines not on this page · raw message
Documentation/fb/viafb.txt +219 -174
393 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 6 lines
2.20.1 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Part of the diff is not shown here. View the raw message.
Re: [PATCH 13/57] docs: fb: convert documentation to ReST format
Quoted 5 lines · Mauro Carvalho Chehab
Convert all documents here from plain txt to ReST format, in order to allow parsing them with the documentation build system.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Best regards,
--
Bartlomiej Zolnierkiewicz
Samsung R&D Institute Poland
Samsung Electronics
PATCH 14/57 docs: fpga: convert it to ReST
In reply to Mauro Carvalho ChehabThe dfl.txt file is almost there. It needs just a few adjustments to be properly parsed.
--- Documentation/fpga/dfl.txt | 58 +++++++++++++++++++++----------------- 1 file changed, 32 insertions(+), 26 deletions(-)
Documentation/fpga/dfl.txt +32 -26
@@ -1,9 +1,12 @@ -=============================================================================== - FPGA Device Feature List (DFL) Framework Overview -------------------------------------------------------------------------------- - Enno Luebbers <[email protected]> - Xiao Guangrong <[email protected]> - Wu Hao <[email protected]> +================================================= +FPGA Device Feature List (DFL) Framework Overview +================================================= + +Authors: + +- Enno Luebbers <[email protected]> +- Xiao Guangrong <[email protected]> +- Wu Hao <[email protected]> The Device Feature List (DFL) FPGA framework (and drivers according to this this framework) hides the very details of low layer hardwares and provides
@@ -19,7 +22,7 @@ Device Feature List (DFL) defines a linked list of feature headers within the device MMIO space to provide an extensible way of adding features. Software can walk through these predefined data structures to enumerate FPGA features: FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features, -as illustrated below: +as illustrated below:: Header Header Header Header +----------+ +-->+----------+ +-->+----------+ +-->+----------+
@@ -81,9 +84,9 @@ and release it using close(). The following functions are exposed through ioctls: - Get driver API version (DFL_FPGA_GET_API_VERSION) - Check for extensions (DFL_FPGA_CHECK_EXTENSION) - Program bitstream (DFL_FPGA_FME_PORT_PR) +- Get driver API version (DFL_FPGA_GET_API_VERSION) +- Check for extensions (DFL_FPGA_CHECK_EXTENSION) +- Program bitstream (DFL_FPGA_FME_PORT_PR) More functions are exposed through sysfs (/sys/class/fpga_region/regionX/dfl-fme.n/):
@@ -118,18 +121,19 @@ port by using open() on the port device node and release it using close(). The following functions are exposed through ioctls: - Get driver API version (DFL_FPGA_GET_API_VERSION) - Check for extensions (DFL_FPGA_CHECK_EXTENSION) - Get port info (DFL_FPGA_PORT_GET_INFO) - Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO) - Map DMA buffer (DFL_FPGA_PORT_DMA_MAP) - Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP) - Reset AFU (*DFL_FPGA_PORT_RESET) +- Get driver API version (DFL_FPGA_GET_API_VERSION) +- Check for extensions (DFL_FPGA_CHECK_EXTENSION) +- Get port info (DFL_FPGA_PORT_GET_INFO) +- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO) +- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP) +- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP) +- Reset AFU (DFL_FPGA_PORT_RESET) -*DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port -reset at any time, e.g. during DMA or Partial Reconfiguration. But it should -never cause any system level issue, only functional failure (e.g. DMA or PR -operation failure) and be recoverable from the failure. +DFL_FPGA_PORT_RESET: + reset the FPGA Port and its AFU. Userspace can do Port + reset at any time, e.g. during DMA or Partial Reconfiguration. But it should + never cause any system level issue, only functional failure (e.g. DMA or PR + operation failure) and be recoverable from the failure. User-space applications can also mmap() accelerator MMIO regions.
@@ -143,6 +147,8 @@ More functions are exposed through sysfs: DFL Framework Overview ====================== +:: + +----------+ +--------+ +--------+ +--------+ | FME | | AFU | | AFU | | AFU | | Module | | Module | | Module | | Module |
@@ -151,7 +157,7 @@ DFL Framework Overview | FPGA Container Device | Device Feature List | (FPGA Base Region) | Framework +-----------------------+ --------------------------------------------------------------------- + ------------------------------------------------------------------ +----------------------------+ | FPGA DFL Device Module | | (e.g. PCIE/Platform Device)|
@@ -220,7 +226,7 @@ the sysfs hierarchy under /sys/class/fpga_region. In the example below, two DFL based FPGA devices are installed in the host. Each fpga device has one FME and two ports (AFUs). -FPGA regions are created under /sys/class/fpga_region/ +FPGA regions are created under /sys/class/fpga_region/:: /sys/class/fpga_region/region0 /sys/class/fpga_region/region1
@@ -231,7 +237,7 @@ Application needs to search each regionX folder, if feature device is found, (e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base fpga region which represents the FPGA device. -Each base region has one FME and two ports (AFUs) as child devices: +Each base region has one FME and two ports (AFUs) as child devices:: /sys/class/fpga_region/region0/dfl-fme.0 /sys/class/fpga_region/region0/dfl-port.0
@@ -243,7 +249,7 @@ Each base region has one FME and two ports (AFUs) as child devices: /sys/class/fpga_region/region3/dfl-port.3 ... -In general, the FME/AFU sysfs interfaces are named as follows: +In general, the FME/AFU sysfs interfaces are named as follows:: /sys/class/fpga_region/<regionX>/<dfl-fme.n>/ /sys/class/fpga_region/<regionX>/<dfl-port.m>/
@@ -251,7 +257,7 @@ In general, the FME/AFU sysfs interfaces are named as follows: with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all ports. -The device nodes used for ioctl() or mmap() can be referenced through: +The device nodes used for ioctl() or mmap() can be referenced through:: /sys/class/fpga_region/<regionX>/<dfl-fme.n>/dev /sys/class/fpga_region/<regionX>/<dfl-port.n>/dev
Signature · 1 line
2.20.1
PATCH 15/57 docs: gpio: convert it to ReST
In reply to Mauro Carvalho ChehabThe API described at sysfs.txt is deprecated.
Still, as it is still part of the Kernel (and will likely be there for some time, as we don't simply remove APIs). So, it makes sense to keep it there.
The conversion of this file is trivial.
--- Documentation/gpio/sysfs.txt | 39 +++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 14 deletions(-)
Documentation/gpio/sysfs.txt +25 -14
@@ -1,10 +1,12 @@ GPIO Sysfs Interface for Userspace ================================== -THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO -Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS -ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL -NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. +.. warning:: + + THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO + Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS + ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL + NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. Refer to the examples in tools/gpio/* for an introduction to the new character device ABI. Also see the userspace header in
@@ -51,13 +53,15 @@ The control interfaces are write-only: /sys/class/gpio/ - "export" ... Userspace may ask the kernel to export control of + "export" ... + Userspace may ask the kernel to export control of a GPIO to userspace by writing its number to this file. Example: "echo 19 > export" will create a "gpio19" node for GPIO #19, if that's not requested by kernel code. - "unexport" ... Reverses the effect of exporting to userspace. + "unexport" ... + Reverses the effect of exporting to userspace. Example: "echo 19 > unexport" will remove a "gpio19" node exported using the "export" file.
@@ -67,7 +71,8 @@ and have the following read/write attributes: /sys/class/gpio/gpioN/ - "direction" ... reads as either "in" or "out". This value may + "direction" ... + reads as either "in" or "out". This value may normally be written. Writing as "out" defaults to initializing the value as low. To ensure glitch free operation, values "low" and "high" may be written to
@@ -78,7 +83,8 @@ and have the following read/write attributes: it was exported by kernel code that didn't explicitly allow userspace to reconfigure this GPIO's direction. - "value" ... reads as either 0 (low) or 1 (high). If the GPIO + "value" ... + reads as either 0 (low) or 1 (high). If the GPIO is configured as an output, this value may be written; any nonzero value is treated as high.
@@ -92,14 +98,16 @@ and have the following read/write attributes: file and read the new value or close the file and re-open it to read the value. - "edge" ... reads as either "none", "rising", "falling", or + "edge" ... + reads as either "none", "rising", "falling", or "both". Write these strings to select the signal edge(s) that will make poll(2) on the "value" file return. This file exists only if the pin can be configured as an interrupt generating input pin. - "active_low" ... reads as either 0 (false) or 1 (true). Write + "active_low" ... + reads as either 0 (false) or 1 (true). Write any nonzero value to invert the value attribute both for reading and writing. Existing and subsequent poll(2) support configuration via the edge attribute
@@ -112,11 +120,14 @@ read-only attributes: /sys/class/gpio/gpiochipN/ - "base" ... same as N, the first GPIO managed by this chip + "base" ... + same as N, the first GPIO managed by this chip - "label" ... provided for diagnostics (not always unique) + "label" ... + provided for diagnostics (not always unique) - "ngpio" ... how many GPIOs this manages (N to N + ngpio - 1) + "ngpio" ... + how many GPIOs this manages (N to N + ngpio - 1) Board documentation should in most cases cover what GPIOs are used for what purposes. However, those numbers are not always stable; GPIOs on
@@ -129,7 +140,7 @@ the correct GPIO number to use for a given signal. Exporting from Kernel code -------------------------- Kernel code can explicitly manage exports of GPIOs which have already been -requested using gpio_request(): +requested using gpio_request():: /* export the GPIO to userspace */ int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
Signature · 1 line
2.20.1
Re: [PATCH 15/57] docs: gpio: convert it to ReST
Quoted 9 lines · Mauro Carvalho Chehab
The API described at sysfs.txt is deprecated.
Still, as it is still part of the Kernel (and will likely be there for some time, as we don't simply remove APIs). So, it makes sense to keep it there.
The conversion of this file is trivial.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Mauro will you merge this or do you want me to merge it?
Yours,
Linus Walleij
Re: [PATCH 15/57] docs: gpio: convert it to ReST
Em Tue, 23 Apr 2019 12:52:04 +0200
Linus Walleij <[email protected]> escreveu:
Quoted 9 lines
Quoted 6 lines · Mauro Carvalho Chehab
The API described at sysfs.txt is deprecated.
Still, as it is still part of the Kernel (and will likely be there for some time, as we don't simply remove APIs). So, it makes sense to keep it there.
Quoted 7 lines
Quoted 3 lines
The conversion of this file is trivial.
Signed-off-by Mauro Carvalho Chehab <[email protected]>Acked-by Linus Walleij <[email protected]>Mauro will you merge this or do you want me to merge it?
Linus,
Just answered on the other e-mail: better to merge via your tree. Just notice that this version was superseded by
[PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst
As it also does the rename to .rst.
Thanks,
Mauro
PATCH 16/57 docs: ide: convert it to ReST format
In reply to Mauro Carvalho ChehabConvert the IDE documentation to ReST format, in order to prepare for its addition inside a book.
--- Documentation/ide/ide-tape.txt | 23 ++-- Documentation/ide/ide.txt | 147 ++++++++++++++------------ Documentation/ide/warm-plug-howto.txt | 10 +- 3 files changed, 96 insertions(+), 84 deletions(-)
Documentation/ide/ide-tape.txt +13 -10
@@ -1,4 +1,6 @@ -IDE ATAPI streaming tape driver. +=============================== +IDE ATAPI streaming tape driver +=============================== This driver is a part of the Linux ide driver.
@@ -10,14 +12,14 @@ to the request-list of the block device, and waits for their completion. The block device major and minor numbers are determined from the tape's relative position in the ide interfaces, as explained in ide.c. -The character device interface consists of the following devices: +The character device interface consists of the following devices:: -ht0 major 37, minor 0 first IDE tape, rewind on close. -ht1 major 37, minor 1 second IDE tape, rewind on close. -... -nht0 major 37, minor 128 first IDE tape, no rewind on close. -nht1 major 37, minor 129 second IDE tape, no rewind on close. -... + ht0 major 37, minor 0 first IDE tape, rewind on close. + ht1 major 37, minor 1 second IDE tape, rewind on close. + ... + nht0 major 37, minor 128 first IDE tape, no rewind on close. + nht1 major 37, minor 129 second IDE tape, no rewind on close. + ... The general magnetic tape commands compatible interface, as defined by include/linux/mtio.h, is accessible through the character device.
@@ -40,9 +42,10 @@ Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive. Here are some words from the first releases of hd.c, which are quoted in ide.c and apply here as well: -| Special care is recommended. Have Fun! +* Special care is recommended. Have Fun! -Possible improvements: +Possible improvements +===================== 1. Support for the ATAPI overlap protocol.
Documentation/ide/ide.txt +78 -69
227 lines not on this page · raw message
Documentation/ide/warm-plug-howto.txt +5 -5
@@ -1,14 +1,14 @@ - +=================== IDE warm-plug HOWTO =================== -To warm-plug devices on a port 'idex': +To warm-plug devices on a port 'idex':: -# echo -n "1" > /sys/class/ide_port/idex/delete_devices + # echo -n "1" > /sys/class/ide_port/idex/delete_devices -unplug old device(s) and plug new device(s) +unplug old device(s) and plug new device(s):: -# echo -n "1" > /sys/class/ide_port/idex/scan + # echo -n "1" > /sys/class/ide_port/idex/scan done
Signature · 1 line
2.20.1
PATCH 17/57 docs: infiniband: convert it to ReST format
In reply to Mauro Carvalho ChehabThe 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.
--- Documentation/infiniband/core_locking.txt | 64 +++++++------ Documentation/infiniband/ipoib.txt | 24 +++-- Documentation/infiniband/opa_vnic.txt | 108 ++++++++++++---------- Documentation/infiniband/sysfs.txt | 4 +- Documentation/infiniband/tag_matching.txt | 5 + Documentation/infiniband/user_mad.txt | 33 +++++-- Documentation/infiniband/user_verbs.txt | 12 ++- 7 files changed, 149 insertions(+), 101 deletions(-)
Documentation/infiniband/core_locking.txt +35 -29
@@ -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
Documentation/infiniband/ipoib.txt +17 -7
@@ -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
Documentation/infiniband/opa_vnic.txt +57 -51
137 lines not on this page · raw message
Documentation/infiniband/sysfs.txt +3 -1
@@ -1,4 +1,6 @@ -SYSFS FILES +=========== +Sysfs files +=========== The sysfs interface has moved to Documentation/ABI/stable/sysfs-class-infiniband.
Documentation/infiniband/tag_matching.txt +5 -0
@@ -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
Documentation/infiniband/user_mad.txt +23 -10
@@ -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
Documentation/infiniband/user_verbs.txt +9 -3
@@ -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
Signature · 1 line
2.20.1
PATCH 18/57 docs: kbuild: convert it to ReST output
In reply to Mauro Carvalho ChehabThe kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections.
Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups.
--- Documentation/kbuild/headers_install.txt | 5 +- Documentation/kbuild/kbuild.txt | 119 ++-- Documentation/kbuild/kconfig-language.txt | 232 ++++---- .../kbuild/kconfig-macro-language.txt | 37 +- Documentation/kbuild/kconfig.txt | 136 +++-- Documentation/kbuild/makefiles.txt | 518 +++++++++++------- Documentation/kbuild/modules.txt | 166 +++--- 7 files changed, 720 insertions(+), 493 deletions(-)
Documentation/kbuild/headers_install.txt +3 -2
@@ -1,3 +1,4 @@ +============================================= Exporting kernel headers for use by userspace =============================================
@@ -22,14 +23,14 @@ older kernel. The "make headers_install" command can be run in the top level directory of the kernel source code (or using a standard out-of-tree build). It takes two -optional arguments: +optional arguments:: make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr ARCH indicates which architecture to produce headers for, and defaults to the current architecture. The linux/asm directory of the exported kernel headers is platform-specific, to see a complete list of supported architectures use -the command: +the command:: ls -d include/asm-* | sed 's/.*-//'
Documentation/kbuild/kbuild.txt +68 -51
305 lines not on this page · raw message
Documentation/kbuild/kconfig-language.txt +126 -106
487 lines not on this page · raw message
Documentation/kbuild/kconfig-macro-language.txt +21 -16
@@ -1,3 +1,7 @@ +====================== +Kconfig macro language +====================== + Concept -------
@@ -7,7 +11,7 @@ targets and prerequisites. The other is a macro language for performing textual substitution. There is clear distinction between the two language stages. For example, you -can write a makefile like follows: +can write a makefile like follows:: APP := foo SRC := foo.c
@@ -17,7 +21,7 @@ can write a makefile like follows: $(CC) -o $(APP) $(SRC) The macro language replaces the variable references with their expanded form, -and handles as if the source file were input like follows: +and handles as if the source file were input like follows:: foo: foo.c gcc -o foo foo.c
@@ -26,7 +30,7 @@ Then, Make analyzes the dependency graph and determines the targets to be updated. The idea is quite similar in Kconfig - it is possible to describe a Kconfig -file like this: +file like this:: CC := gcc
@@ -34,7 +38,7 @@ file like this: def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC)) The macro language in Kconfig processes the source file into the following -intermediate: +intermediate:: config CC_HAS_FOO def_bool y
@@ -69,7 +73,7 @@ variable. The righthand side of += is expanded immediately if the lefthand side was originally defined as a simple variable. Otherwise, its evaluation is deferred. -The variable reference can take parameters, in the following form: +The variable reference can take parameters, in the following form:: $(name,arg1,arg2,arg3)
@@ -141,7 +145,7 @@ Make vs Kconfig Kconfig adopts Make-like macro language, but the function call syntax is slightly different. -A function call in Make looks like this: +A function call in Make looks like this:: $(func-name arg1,arg2,arg3)
@@ -149,14 +153,14 @@ The function name and the first argument are separated by at least one whitespace. Then, leading whitespaces are trimmed from the first argument, while whitespaces in the other arguments are kept. You need to use a kind of trick to start the first parameter with spaces. For example, if you want -to make "info" function print " hello", you can write like follows: +to make "info" function print " hello", you can write like follows:: empty := space := $(empty) $(empty) $(info $(space)$(space)hello) Kconfig uses only commas for delimiters, and keeps all whitespaces in the -function call. Some people prefer putting a space after each comma delimiter: +function call. Some people prefer putting a space after each comma delimiter:: $(func-name, arg1, arg2, arg3)
@@ -166,7 +170,7 @@ Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it replaces ".c" with " .o". In Make, a user-defined function is referenced by using a built-in function, -'call', like this: +'call', like this:: $(call my-func,arg1,arg2,arg3)
@@ -179,12 +183,12 @@ Likewise, $(info hello, world) prints "hello, world" to stdout. You could say this is _useful_ inconsistency. In Kconfig, for simpler implementation and grammatical consistency, commas that -appear in the $( ) context are always delimiters. It means +appear in the $( ) context are always delimiters. It means:: $(shell, echo hello, world) is an error because it is passing two parameters where the 'shell' function -accepts only one. To pass commas in arguments, you can use the following trick: +accepts only one. To pass commas in arguments, you can use the following trick:: comma := , $(shell, echo hello$(comma) world)
@@ -195,7 +199,7 @@ Caveats A variable (or function) cannot be expanded across tokens. So, you cannot use a variable as a shorthand for an expression that consists of multiple tokens. -The following works: +The following works:: RANGE_MIN := 1 RANGE_MAX := 3
@@ -204,7 +208,7 @@ The following works: int "foo" range $(RANGE_MIN) $(RANGE_MAX) -But, the following does not work: +But, the following does not work:: RANGES := 1 3
@@ -213,7 +217,7 @@ But, the following does not work: range $(RANGES) A variable cannot be expanded to any keyword in Kconfig. The following does -not work: +not work:: MY_TYPE := tristate
@@ -223,7 +227,8 @@ not work: Obviously from the design, $(shell command) is expanded in the textual substitution phase. You cannot pass symbols to the 'shell' function. -The following does not work as expected. + +The following does not work as expected:: config ENDIAN_FLAG string
@@ -234,7 +239,7 @@ The following does not work as expected. def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG) Instead, you can do like follows so that any function call is statically -expanded. +expanded:: config CC_HAS_ENDIAN_FLAG bool
Documentation/kbuild/kconfig.txt +82 -54
307 lines not on this page · raw message
Documentation/kbuild/makefiles.txt +322 -196
1,268 lines not on this page · raw message
Documentation/kbuild/modules.txt +98 -68
405 lines not on this page · raw message
Signature · 1 line
2.20.1
Re: [PATCH 18/57] docs: kbuild: convert it to ReST output
Quoted 7 lines · Mauro Carvalho Chehab
The kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections.
Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups.
Sorry for my ignorance, but shouldn't ReST use
the extension '.rst' instead of '.txt' ?
Quoted 11 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/kbuild/headers_install.txt | 5 +- Documentation/kbuild/kbuild.txt | 119 ++-- Documentation/kbuild/kconfig-language.txt | 232 ++++---- .../kbuild/kconfig-macro-language.txt | 37 +- Documentation/kbuild/kconfig.txt | 136 +++-- Documentation/kbuild/makefiles.txt | 518 +++++++++++------- Documentation/kbuild/modules.txt | 166 +++--- 7 files changed, 720 insertions(+), 493 deletions(-)
Signature · 2 lines
Best Regards Masahiro Yamada
Re: [PATCH 18/57] docs: kbuild: convert it to ReST output
Em Thu, 18 Apr 2019 18:25:45 +0900
Masahiro Yamada <[email protected]> escreveu:
Quoted 7 lines
Quoted 5 lines · Mauro Carvalho Chehab
The kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections.
Quoted 5 lines
Quoted 2 lines
Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups.
Sorry for my ignorance, but shouldn't ReST use
the extension '.rst' instead of '.txt' ?
Yes. I have a patch with the rename step, but the problem is that doing such renames on 57 different subdirs and then adding all of them to the existing index.rst files (in order to add into a bookset) would cause huge merge conflicts - and keeping them renamed without adding into an index would cause a *lot* new warnings when building them.
So, IMO, the best would be to have the fixup stuff merged first, and then do the renames/merges at once, after subsystem maintainers pick the patches from this rst fixup series.
If you want to see the renaming patch, it is at:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=all_with_indexes-v3&id=9cfeb3eb6d48d1aeff9d2ddd84880ab1dc782b00
(I'll probably split it later into per-subdir renames)
The results of this patch, plus the rename one, is at:
https://www.infradead.org/~mchehab/rst_conversion/kbuild/index.html
Quoted 15 lines
Quoted 4 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>Quoted 10 lines
--- Documentation/kbuild/headers_install.txt | 5 +- Documentation/kbuild/kbuild.txt | 119 ++-- Documentation/kbuild/kconfig-language.txt | 232 ++++---- .../kbuild/kconfig-macro-language.txt | 37 +- Documentation/kbuild/kconfig.txt | 136 +++-- Documentation/kbuild/makefiles.txt | 518 +++++++++++------- Documentation/kbuild/modules.txt | 166 +++--- 7 files changed, 720 insertions(+), 493 deletions(-)
Thanks,
Mauro
PATCH 19/57 docs: kdump: convert it to ReST
In reply to Mauro Carvalho ChehabConvert kdump documentation to ReST and add it to the user faced manual, as the documents are mainly focused on sysadmins that would be enabling kdump.
Note: the vmcoreinfo.rst has one very long title for sub-sections. I opted to break this one, in order to make it easier to display in html.
--- Documentation/kdump/kdump.txt | 131 +++++++++++++++++------------ Documentation/kdump/vmcoreinfo.txt | 59 ++++++------- 2 files changed, 104 insertions(+), 86 deletions(-)
Documentation/kdump/kdump.txt +78 -53
@@ -71,9 +71,8 @@ This is a symlink to the latest version. The latest kexec-tools git tree is available at: -git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git -and -http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git +- git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git +- http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git There is also a gitweb interface available at http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
@@ -81,25 +80,25 @@ http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git More information about kexec-tools can be found at http://horms.net/projects/kexec/ -3) Unpack the tarball with the tar command, as follows: +3) Unpack the tarball with the tar command, as follows:: - tar xvpzf kexec-tools.tar.gz + tar xvpzf kexec-tools.tar.gz -4) Change to the kexec-tools directory, as follows: +4) Change to the kexec-tools directory, as follows:: - cd kexec-tools-VERSION + cd kexec-tools-VERSION -5) Configure the package, as follows: +5) Configure the package, as follows:: - ./configure + ./configure -6) Compile the package, as follows: +6) Compile the package, as follows:: - make + make -7) Install the package, as follows: +7) Install the package, as follows:: - make install + make install Build the system and dump-capture kernels
@@ -126,25 +125,25 @@ dump-capture kernels for enabling kdump support. System kernel config options ---------------------------- -1) Enable "kexec system call" in "Processor type and features." +1) Enable "kexec system call" in "Processor type and features.":: - CONFIG_KEXEC=y + CONFIG_KEXEC=y 2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo - filesystems." This is usually enabled by default. + filesystems." This is usually enabled by default:: - CONFIG_SYSFS=y + CONFIG_SYSFS=y Note that "sysfs file system support" might not appear in the "Pseudo filesystems" menu if "Configure standard kernel features (for small systems)" is not enabled in "General Setup." In this case, check the - .config file itself to ensure that sysfs is turned on, as follows: + .config file itself to ensure that sysfs is turned on, as follows:: - grep 'CONFIG_SYSFS' .config + grep 'CONFIG_SYSFS' .config -3) Enable "Compile the kernel with debug info" in "Kernel hacking." +3) Enable "Compile the kernel with debug info" in "Kernel hacking.":: - CONFIG_DEBUG_INFO=Y + CONFIG_DEBUG_INFO=Y This causes the kernel to be built with debug symbols. The dump analysis tools require a vmlinux with debug symbols in order to read
@@ -154,29 +153,32 @@ Dump-capture kernel config options (Arch Independent) ----------------------------------------------------- 1) Enable "kernel crash dumps" support under "Processor type and - features": + features":: - CONFIG_CRASH_DUMP=y + CONFIG_CRASH_DUMP=y -2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems". +2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems":: + + CONFIG_PROC_VMCORE=y - CONFIG_PROC_VMCORE=y (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.) Dump-capture kernel config options (Arch Dependent, i386 and x86_64) -------------------------------------------------------------------- 1) On i386, enable high memory support under "Processor type and - features": + features":: - CONFIG_HIGHMEM64G=y - or - CONFIG_HIGHMEM4G + CONFIG_HIGHMEM64G=y + + or:: + + CONFIG_HIGHMEM4G 2) On i386 and x86_64, disable symmetric multi-processing support - under "Processor type and features": + under "Processor type and features":: - CONFIG_SMP=n + CONFIG_SMP=n (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line when loading the dump-capture kernel, see section "Load the Dump-capture
@@ -184,9 +186,9 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64) 3) If one wants to build and use a relocatable kernel, Enable "Build a relocatable kernel" support under "Processor type and - features" + features":: - CONFIG_RELOCATABLE=y + CONFIG_RELOCATABLE=y 4) Use a suitable value for "Physical address where the kernel is loaded" (under "Processor type and features"). This only appears when
@@ -211,13 +213,13 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64) Dump-capture kernel config options (Arch Dependent, ppc64) ---------------------------------------------------------- -1) Enable "Build a kdump crash kernel" support under "Kernel" options: +1) Enable "Build a kdump crash kernel" support under "Kernel" options:: - CONFIG_CRASH_DUMP=y + CONFIG_CRASH_DUMP=y -2) Enable "Build a relocatable kernel" support +2) Enable "Build a relocatable kernel" support:: - CONFIG_RELOCATABLE=y + CONFIG_RELOCATABLE=y Make and install the kernel and its modules.
@@ -231,11 +233,13 @@ Dump-capture kernel config options (Arch Dependent, ia64) The crashkernel region can be automatically placed by the system kernel at run time. This is done by specifying the base address as 0, - or omitting it all together. + or omitting it all together:: - crashkernel=256M@0 - or - crashkernel=256M + crashkernel=256M@0 + + or:: + + crashkernel=256M If the start address is specified, note that the start address of the kernel will be aligned to 64Mb, so if the start address is not then
@@ -245,9 +249,9 @@ Dump-capture kernel config options (Arch Dependent, arm) ---------------------------------------------------------- - To use a relocatable kernel, - Enable "AUTO_ZRELADDR" support under "Boot" options: + Enable "AUTO_ZRELADDR" support under "Boot" options:: - AUTO_ZRELADDR=y + AUTO_ZRELADDR=y Dump-capture kernel config options (Arch Dependent, arm64) ----------------------------------------------------------
@@ -265,12 +269,12 @@ on the value of System RAM -- that's mostly for distributors that pre-setup the kernel command line to avoid a unbootable system after some memory has been removed from the machine. -The syntax is: +The syntax is:: crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset] range=start-[end] -For example: +For example:: crashkernel=512M-2G:64M,2G-:128M
@@ -326,35 +330,46 @@ can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz of dump-capture kernel. Following is the summary. For i386 and x86_64: + - Use vmlinux if kernel is not relocatable. - Use bzImage/vmlinuz if kernel is relocatable. + For ppc64: + - Use vmlinux + For ia64: + - Use vmlinux or vmlinuz.gz + For s390x: + - Use image or bzImage + For arm: + - Use zImage + For arm64: + - Use vmlinux or Image If you are using an uncompressed vmlinux image then use following command -to load dump-capture kernel. +to load dump-capture kernel:: kexec -p <dump-capture-kernel-vmlinux-image> \ --initrd=<initrd-for-dump-capture-kernel> --args-linux \ --append="root=<root-dev> <arch-specific-options>" If you are using a compressed bzImage/vmlinuz, then use following command -to load dump-capture kernel. +to load dump-capture kernel:: kexec -p <dump-capture-kernel-bzImage> \ --initrd=<initrd-for-dump-capture-kernel> \ --append="root=<root-dev> <arch-specific-options>" If you are using a compressed zImage, then use following command -to load dump-capture kernel. +to load dump-capture kernel:: kexec --type zImage -p <dump-capture-kernel-bzImage> \ --initrd=<initrd-for-dump-capture-kernel> \
@@ -362,7 +377,7 @@ to load dump-capture kernel. --append="root=<root-dev> <arch-specific-options>" If you are using an uncompressed Image, then use following command -to load dump-capture kernel. +to load dump-capture kernel:: kexec -p <dump-capture-kernel-Image> \ --initrd=<initrd-for-dump-capture-kernel> \
@@ -376,18 +391,23 @@ Following are the arch specific command line options to be used while loading dump-capture kernel. For i386, x86_64 and ia64: + "1 irqpoll maxcpus=1 reset_devices" For ppc64: + "1 maxcpus=1 noirqdistrib reset_devices" For s390x: + "1 maxcpus=1 cgroup_disable=memory" For arm: + "1 maxcpus=1 reset_devices" For arm64: + "1 maxcpus=1 reset_devices" Notes on loading the dump-capture kernel:
@@ -464,7 +484,7 @@ Write Out the Dump File ======================= After the dump-capture kernel is booted, write out the dump file with -the following command: +the following command:: cp /proc/vmcore <dump-file>
@@ -476,7 +496,7 @@ Before analyzing the dump image, you should reboot into a stable kernel. You can do limited analysis using GDB on the dump file copied out of /proc/vmcore. Use the debug vmlinux built with -g and run the following -command: +command:: gdb vmlinux <dump-file>
@@ -504,6 +524,11 @@ to achieve the same behaviour. Contact ======= -Vivek Goyal ([email protected]) -Maneesh Soni ([email protected]) +- Vivek Goyal ([email protected]) +- Maneesh Soni ([email protected]) +GDB macros +========== + +.. include:: gdbmacros.txt + :literal:
Documentation/kdump/vmcoreinfo.txt +26 -33
155 lines not on this page · raw message
Signature · 7 lines
2.20.1 _______________________________________________ kexec mailing list [email protected] http://lists.infradead.org/mailman/listinfo/kexec
PATCH 20/57 docs: livepatch: convert it to ReST format
In reply to Mauro Carvalho ChehabConvert livepatch documentation to ReST format. The changes are mostly trivial, as the documents are already on a good shape. Just a few markup changes are needed for Sphinx to properly parse the docs.
--- Documentation/livepatch/callbacks.txt | 12 +- .../livepatch/cumulative-patches.txt | 14 +- Documentation/livepatch/livepatch.txt | 56 ++--- Documentation/livepatch/module-elf-format.txt | 211 ++++++++++-------- Documentation/livepatch/shadow-vars.txt | 65 ++++-- 5 files changed, 199 insertions(+), 159 deletions(-)
Documentation/livepatch/callbacks.txt +8 -4
@@ -30,16 +30,20 @@ be patched, irrespective of the target klp_object's current state. Callbacks can be registered for the following livepatch actions: - * Pre-patch - before a klp_object is patched + * Pre-patch + - before a klp_object is patched - * Post-patch - after a klp_object has been patched and is active + * Post-patch + - after a klp_object has been patched and is active across all tasks - * Pre-unpatch - before a klp_object is unpatched (ie, patched code is + * Pre-unpatch + - before a klp_object is unpatched (ie, patched code is active), used to clean up post-patch callback resources - * Post-unpatch - after a klp_object has been patched, all code has + * Post-unpatch + - after a klp_object has been patched, all code has been restored and no tasks are running patched code, used to cleanup pre-patch callback resources
Documentation/livepatch/cumulative-patches.txt +7 -7
@@ -18,7 +18,7 @@ Usage ----- The atomic replace can be enabled by setting "replace" flag in struct klp_patch, -for example: +for example:: static struct klp_patch patch = { .mod = THIS_MODULE,
@@ -49,19 +49,19 @@ Features The atomic replace allows: - + Atomically revert some functions in a previous patch while + - Atomically revert some functions in a previous patch while upgrading other functions. - + Remove eventual performance impact caused by core redirection + - Remove eventual performance impact caused by core redirection for functions that are no longer patched. - + Decrease user confusion about dependencies between livepatches. + - Decrease user confusion about dependencies between livepatches. Limitations: ------------ - + Once the operation finishes, there is no straightforward way + - Once the operation finishes, there is no straightforward way to reverse it and restore the replaced patches atomically. A good practice is to set .replace flag in any released livepatch.
@@ -74,7 +74,7 @@ Limitations: only when the transition was not forced. - + Only the (un)patching callbacks from the _new_ cumulative livepatch are + - Only the (un)patching callbacks from the _new_ cumulative livepatch are executed. Any callbacks from the replaced patches are ignored. In other words, the cumulative patch is responsible for doing any actions
@@ -93,7 +93,7 @@ Limitations: enabled patches were called. - + There is no special handling of shadow variables. Livepatch authors + - There is no special handling of shadow variables. Livepatch authors must create their own rules how to pass them from one cumulative patch to the other. Especially that they should not blindly remove them in module_exit() functions.
Documentation/livepatch/livepatch.txt +29 -27
128 lines not on this page · raw message
Documentation/livepatch/module-elf-format.txt +114 -97
272 lines not on this page · raw message
Documentation/livepatch/shadow-vars.txt +41 -24
143 lines not on this page · raw message
Signature · 1 line
2.20.1
Re: [PATCH 20/57] docs: livepatch: convert it to ReST format
Quoted 6 lines · Mauro Carvalho Chehab
Convert livepatch documentation to ReST format. The changes are mostly trivial, as the documents are already on a good shape. Just a few markup changes are needed for Sphinx to properly parse the docs.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Thanks a lot for the conversion. I tried html output and it looks very well.
Just a question. This patch does only the formatting. The documentation is not really generated because the file is not renamed to .rst. Also it is not referenced from any top level documents. Is it by intention?
I am happy even for the conversion, so:
Best Regards,
Petr
Re: [PATCH 20/57] docs: livepatch: convert it to ReST format
Em Tue, 16 Apr 2019 10:43:54 +0200
Petr Mladek <[email protected]> escreveu:
Quoted 8 lines · Mauro Carvalho Chehab
Quoted 6 lines
Convert livepatch documentation to ReST format. The changes are mostly trivial, as the documents are already on a good shape. Just a few markup changes are needed for Sphinx to properly parse the docs.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Quoted 7 lines
Thanks a lot for the conversion. I tried html output and it looks very well.
Just a question. This patch does only the formatting. The documentation is not really generated because the file is not renamed to .rst. Also it is not referenced from any top level documents. Is it by intention?
Yes. The rationale is simple: renaming to .rst would require to add them on an index file (or otherwise build would produce lots of warnings). As this series is doing a lot of such conversions, assuming that some of those patches will go through different trees, that would cause lots of conflicts at the main index files.
So, it sounds better to apply the conversion first and then, on a better moment (maybe late during the merge window), do the rename and add to the index files.
Quoted 8 lines
I am happy even for the conversion, so:
Reviewed-by Petr Mladek <[email protected]>Best Regards,
Petr
Thanks,
Mauro
PATCH 21/57 docs: locking: convert docs to ReST format
In reply to Mauro Carvalho ChehabConvert 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.
--- Documentation/locking/lockdep-design.txt | 41 ++-- Documentation/locking/lockstat.txt | 219 ++++++++++++---------- Documentation/locking/locktorture.txt | 105 +++++++---- Documentation/locking/mutex-design.txt | 26 ++- Documentation/locking/rt-mutex-design.txt | 135 +++++++------ Documentation/locking/rt-mutex.txt | 30 +-- Documentation/locking/spinlocks.txt | 32 ++-- Documentation/locking/ww-mutex-design.txt | 82 ++++---- 8 files changed, 385 insertions(+), 285 deletions(-)
Documentation/locking/lockdep-design.txt +23 -18
@@ -2,6 +2,7 @@ Runtime locking correctness validator ===================================== started by Ingo Molnar <[email protected]> + additions by Arjan van de Ven <[email protected]> Lock-class
@@ -42,7 +43,7 @@ Where STATE can be either one of (kernel/locking/lockdep_states.h) - 'ever used' [ == !unused ] When locking rules are violated, these state bits are presented in the -locking error messages, inside curlies. A contrived example: +locking error messages, inside curlies. A contrived example:: modprobe/2287 is trying to acquire lock: (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
@@ -54,10 +55,12 @@ locking error messages, inside curlies. A contrived example: The bit position indicates STATE, STATE-read, for each of the states listed above, and the character displayed in each 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. + === =================================================== Unused mutexes cannot be part of the cause of an error.
@@ -67,7 +70,7 @@ Single-lock state rules: A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The following states are exclusive, and only one of them is allowed to be -set for any lock-class: +set for any lock-class:: <hardirq-safe> and <hardirq-unsafe> <softirq-safe> and <softirq-unsafe>
@@ -81,7 +84,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 may not be taken in different order: +Furthermore, two locks may not be taken in different order:: <L1> -> <L2> <L2> -> <L1>
@@ -92,7 +95,7 @@ other locking sequence between the acquire-lock operations, the validator will still track all dependencies between locks.) 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>
@@ -148,16 +151,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.
@@ -178,7 +181,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) {
@@ -197,7 +200,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) {
@@ -224,7 +227,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'
@@ -243,7 +246,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
@@ -254,7 +259,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
@@ -313,17 +318,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
Documentation/locking/lockstat.txt +120 -99
268 lines not on this page · raw message
Documentation/locking/locktorture.txt +65 -40
185 lines not on this page · raw message
Documentation/locking/mutex-design.txt +18 -8
@@ -1,6 +1,9 @@ +======================= Generic Mutex Subsystem +======================= started by Ingo Molnar <[email protected]> + updated by Davidlohr Bueso <[email protected]> What are mutexes?
@@ -23,7 +26,7 @@ Implementation Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h and implemented in kernel/locking/mutex.c. These locks use an atomic variable (->owner) to keep track of the lock state during its lifetime. Field owner -actually contains 'struct task_struct *' to the current lock owner and it is +actually contains `struct task_struct *` to the current lock owner and it is therefore NULL if not currently owned. Since task_struct pointers are aligned at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., if waiter list is non-empty). In its most basic form it also includes a
@@ -101,29 +104,36 @@ features that make lock debugging easier and faster: Interfaces ---------- -Statically define the mutex: +Statically define the mutex:: + DEFINE_MUTEX(name); -Dynamically initialize the mutex: +Dynamically initialize the mutex:: + mutex_init(mutex); -Acquire the mutex, uninterruptible: +Acquire the mutex, uninterruptible:: + void mutex_lock(struct mutex *lock); void mutex_lock_nested(struct mutex *lock, unsigned int subclass); int mutex_trylock(struct mutex *lock); -Acquire the mutex, interruptible: +Acquire the mutex, interruptible:: + int mutex_lock_interruptible_nested(struct mutex *lock, unsigned int subclass); int mutex_lock_interruptible(struct mutex *lock); -Acquire the mutex, interruptible, if dec to 0: +Acquire the mutex, interruptible, if dec to 0:: + int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); -Unlock the mutex: +Unlock the mutex:: + void mutex_unlock(struct mutex *lock); -Test if the mutex is taken: +Test if the mutex is taken:: + int mutex_is_locked(struct mutex *lock); Disadvantages
Documentation/locking/rt-mutex-design.txt +75 -60
288 lines not on this page · raw message
Documentation/locking/rt-mutex.txt +17 -13
@@ -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
Documentation/locking/spinlocks.txt +21 -11
@@ -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;
Documentation/locking/ww-mutex-design.txt +46 -36
209 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 22/57 docs: mic: convert it to ReST format
In reply to Mauro Carvalho ChehabConvert Intel Many Integrated Core architecture docs to ReST.
The conversion is trivial: just add title and literal block markups, and adjust some identation.
--- Documentation/mic/mic_overview.txt | 6 ++- Documentation/mic/scif_overview.txt | 58 +++++++++++++++++------------ 2 files changed, 39 insertions(+), 25 deletions(-)
Documentation/mic/mic_overview.txt +5 -1
@@ -1,3 +1,7 @@ +====================================================== +Intel Many Integrated Core (MIC) architecture overview +====================================================== + An Intel MIC X100 device is a PCIe form factor add-in coprocessor card based on the Intel Many Integrated Core (MIC) architecture that runs a Linux OS. It is a PCIe endpoint in a platform and therefore
@@ -45,7 +49,7 @@ Here is a block diagram of the various components described above. The virtio backends are situated on the host rather than the card given better single threaded performance for the host compared to MIC, the ability of the host to initiate DMA's to/from the card using the MIC DMA engine and -the fact that the virtio block storage backend can only be on the host. +the fact that the virtio block storage backend can only be on the host:: +----------+ | +----------+ | Card OS | | | Host OS |
Documentation/mic/scif_overview.txt +34 -24
87 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 23/57 docs: netlabel: convert it to ReST
In reply to Mauro Carvalho ChehabConvert netlabel documentation to ReST.
This was trivial: just add proper title markups.
--- Documentation/netlabel/cipso_ipv4.txt | 19 +++++++++++++------ Documentation/netlabel/introduction.txt | 16 +++++++++++----- Documentation/netlabel/lsm_interface.txt | 16 +++++++++++----- 3 files changed, 35 insertions(+), 16 deletions(-)
Documentation/netlabel/cipso_ipv4.txt +13 -6
@@ -1,10 +1,13 @@ +=================================== NetLabel CIPSO/IPv4 Protocol Engine -============================================================================== +=================================== + Paul Moore, [email protected] May 17, 2006 - * Overview +Overview +======== The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial IP Security Option (CIPSO) draft from July 16, 1992. A copy of this
@@ -13,7 +16,8 @@ draft can be found in this directory it to an RFC standard it has become a de-facto standard for labeled networking and is used in many trusted operating systems. - * Outbound Packet Processing +Outbound Packet Processing +========================== The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by adding the CIPSO label to the socket. This causes all packets leaving the
@@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is configured to use CIPSO for packet labeling then a CIPSO IP option will be generated and attached to the socket. - * Inbound Packet Processing +Inbound Packet Processing +========================= The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the IP layer without any special handling required by the LSM. However, in order
@@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet. This is typically done at the socket layer using the 'socket_sock_rcv_skb()' LSM hook. - * Label Translation +Label Translation +================= The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security attributes such as sensitivity level and category to values which are
@@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the NetLabel user space communication layer. Each DOI definition can have a different security attribute mapping table. - * Label Translation Cache +Label Translation Cache +======================= The NetLabel system provides a framework for caching security attribute mappings from the network labels to the corresponding LSM identifiers. The
Documentation/netlabel/introduction.txt +11 -5
@@ -1,10 +1,13 @@ +===================== NetLabel Introduction -============================================================================== +===================== + Paul Moore, [email protected] August 2, 2006 - * Overview +Overview +======== NetLabel is a mechanism which can be used by kernel security modules to attach security attributes to outgoing network packets generated from user space
@@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets. It is composed of three main components, the protocol engines, the communication layer, and the kernel security module API. - * Protocol Engines +Protocol Engines +================ The protocol engines are responsible for both applying and retrieving the network packet's security attributes. If any translation between the network
@@ -24,7 +28,8 @@ the NetLabel kernel security module API described below. Detailed information about each NetLabel protocol engine can be found in this directory. - * Communication Layer +Communication Layer +=================== The communication layer exists to allow NetLabel configuration and monitoring from user space. The NetLabel communication layer uses a message based
@@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family names can be found in the 'net/netlabel/' directory as comments in the header files as well as in 'include/net/netlabel.h'. - * Security Module API +Security Module API +=================== The purpose of the NetLabel security module API is to provide a protocol independent interface to the underlying NetLabel protocol engines. In addition
Documentation/netlabel/lsm_interface.txt +11 -5
@@ -1,10 +1,13 @@ +======================================== NetLabel Linux Security Module Interface -============================================================================== +======================================== + Paul Moore, [email protected] May 17, 2006 - * Overview +Overview +======== NetLabel is a mechanism which can set and retrieve security attributes from network packets. It is intended to be used by LSM developers who want to make
@@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols. The NetLabel security module API is defined in 'include/net/netlabel.h' but a brief overview is given below. - * NetLabel Security Attributes +NetLabel Security Attributes +============================ Since NetLabel supports multiple different packet labeling protocols and LSMs it uses the concept of security attributes to refer to the packet's security
@@ -24,7 +28,8 @@ configuration. It is up to the LSM developer to translate the NetLabel security attributes into whatever security identifiers are in use for their particular LSM. - * NetLabel LSM Protocol Operations +NetLabel LSM Protocol Operations +================================ These are the functions which allow the LSM developer to manipulate the labels on outgoing packets as well as read the labels on incoming packets. Functions
@@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly. These high level functions are translated into low level protocol operations based on how the administrator has configured the NetLabel subsystem. - * NetLabel Label Mapping Cache Operations +NetLabel Label Mapping Cache Operations +======================================= Depending on the exact configuration, translation between the network packet label and the internal LSM security identifier can be time consuming. The
Signature · 1 line
2.20.1
Re: [PATCH 23/57] docs: netlabel: convert it to ReST
Quoted 11 lines · Mauro Carvalho Chehab
Convert netlabel documentation to ReST.
This was trivial: just add proper title markups.
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/netlabel/cipso_ipv4.txt | 19 +++++++++++++------ Documentation/netlabel/introduction.txt | 16 +++++++++++----- Documentation/netlabel/lsm_interface.txt | 16 +++++++++++----- 3 files changed, 35 insertions(+), 16 deletions(-)
Thanks for doing this. I should probably revisit these docs to make sure they are still valid/correct; if nothing else that email address is from two employers ago (my apologies to the current email address holder).
Quoted 163 lines
Documentation/netlabel/cipso_ipv4.txt +13
-6@@ -1,10 +1,13 @@ +=================================== NetLabel CIPSO/IPv4 Protocol Engine -============================================================================== +=================================== + Paul Moore, [email protected] May 17, 2006 - * Overview +Overview +======== The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial IP Security Option (CIPSO) draft from July 16, 1992. A copy of this@@ -13,7 +16,8 @@ draft can be found in this directory it to an RFC standard it has become a de-facto standard for labeled networking and is used in many trusted operating systems. - * Outbound Packet Processing +Outbound Packet Processing +========================== The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by adding the CIPSO label to the socket. This causes all packets leaving the@@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is configured to use CIPSO for packet labeling then a CIPSO IP option will be generated and attached to the socket. - * Inbound Packet Processing +Inbound Packet Processing +========================= The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the IP layer without any special handling required by the LSM. However, in order@@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet. This is typically done at the socket layer using the 'socket_sock_rcv_skb()' LSM hook. - * Label Translation +Label Translation +================= The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security attributes such as sensitivity level and category to values which are@@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the NetLabel user space communication layer. Each DOI definition can have a different security attribute mapping table. - * Label Translation Cache +Label Translation Cache +======================= The NetLabel system provides a framework for caching security attribute mappings from the network labels to the corresponding LSM identifiers. TheDocumentation/netlabel/introduction.txt +11
-5@@ -1,10 +1,13 @@ +===================== NetLabel Introduction -============================================================================== +===================== + Paul Moore, [email protected] August 2, 2006 - * Overview +Overview +======== NetLabel is a mechanism which can be used by kernel security modules to attach security attributes to outgoing network packets generated from user space@@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets. It is composed of three main components, the protocol engines, the communication layer, and the kernel security module API. - * Protocol Engines +Protocol Engines +================ The protocol engines are responsible for both applying and retrieving the network packet's security attributes. If any translation between the network@@ -24,7 +28,8 @@ the NetLabel kernel security module API described below. Detailed information about each NetLabel protocol engine can be found in this directory. - * Communication Layer +Communication Layer +=================== The communication layer exists to allow NetLabel configuration and monitoring from user space. The NetLabel communication layer uses a message based@@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family names can be found in the 'net/netlabel/' directory as comments in the header files as well as in 'include/net/netlabel.h'. - * Security Module API +Security Module API +=================== The purpose of the NetLabel security module API is to provide a protocol independent interface to the underlying NetLabel protocol engines. In additionDocumentation/netlabel/lsm_interface.txt +11
-6@@ -1,10 +1,13 @@ +======================================== NetLabel Linux Security Module Interface -============================================================================== +======================================== + Paul Moore, [email protected] May 17, 2006 - * Overview +Overview +======== NetLabel is a mechanism which can set and retrieve security attributes from network packets. It is intended to be used by LSM developers who want to make@@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols. The NetLabel security module API is defined in 'include/net/netlabel.h' but a brief overview is given below. - * NetLabel Security Attributes +NetLabel Security Attributes +============================ Since NetLabel supports multiple different packet labeling protocols and LSMs it uses the concept of security attributes to refer to the packet's security@@ -24,7 +28,8 @@ configuration. It is up to the LSM developer to translate the NetLabel security attributes into whatever security identifiers are in use for their particular LSM. - * NetLabel LSM Protocol Operations +NetLabel LSM Protocol Operations +================================ These are the functions which allow the LSM developer to manipulate the labels on outgoing packets as well as read the labels on incoming packets. Functions@@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly. These high level functions are translated into low level protocol operations based on how the administrator has configured the NetLabel subsystem. - * NetLabel Label Mapping Cache Operations +NetLabel Label Mapping Cache Operations +======================================= Depending on the exact configuration, translation between the network packet label and the internal LSM security identifier can be time consuming. The --2.20.1
Signature · 2 lines
paul moore www.paul-moore.com
PATCH 24/57 docs: pcmcia: convert it to ReST format
In reply to Mauro Carvalho ChehabConvert the pcmcia docs to ReST format. Most of the changes here are trivial, making Sphinx properly identify titles, lists and literal blocks.
--- Documentation/pcmcia/devicetable.txt | 4 +++ Documentation/pcmcia/driver-changes.txt | 35 ++++++++++++++-------- Documentation/pcmcia/driver.txt | 18 ++++++------ Documentation/pcmcia/locking.txt | 39 +++++++++++++++++-------- 4 files changed, 63 insertions(+), 33 deletions(-)
Documentation/pcmcia/devicetable.txt +4 -0
@@ -1,3 +1,7 @@ +============ +Device table +============ + Matching of PCMCIA devices to drivers is done using one or more of the following criteria:
Documentation/pcmcia/driver-changes.txt +23 -12
@@ -1,15 +1,21 @@ +============== +Driver changes +============== + This file details changes in 2.6 which affect PCMCIA card driver authors: + * pcmcia_loop_config() and autoconfiguration (as of 2.6.36) - If struct pcmcia_device *p_dev->config_flags is set accordingly, + If `struct pcmcia_device *p_dev->config_flags` is set accordingly, pcmcia_loop_config() now sets up certain configuration values automatically, though the driver may still override the settings in the callback function. The following autoconfiguration options are provided at the moment: - CONF_AUTO_CHECK_VCC : check for matching Vcc - CONF_AUTO_SET_VPP : set Vpp - CONF_AUTO_AUDIO : auto-enable audio line, if required - CONF_AUTO_SET_IO : set ioport resources (->resource[0,1]) - CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2]) + + - CONF_AUTO_CHECK_VCC : check for matching Vcc + - CONF_AUTO_SET_VPP : set Vpp + - CONF_AUTO_AUDIO : auto-enable audio line, if required + - CONF_AUTO_SET_IO : set ioport resources (->resource[0,1]) + - CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2]) * pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36) pcmcia_request_configuration() got renamed to pcmcia_enable_device(),
@@ -19,14 +25,14 @@ This file details changes in 2.6 which affect PCMCIA card driver authors: * pcmcia_request_window changes (as of 2.6.36) Instead of win_req_t, drivers are now requested to fill out - struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport + `struct pcmcia_device *p_dev->resource[2,3,4,5]` for up to four ioport ranges. After a call to pcmcia_request_window(), the regions found there are reserved and may be used immediately -- until pcmcia_release_window() is called. * pcmcia_request_io changes (as of 2.6.36) Instead of io_req_t, drivers are now requested to fill out - struct pcmcia_device *p_dev->resource[0,1] for up to two ioport + `struct pcmcia_device *p_dev->resource[0,1]` for up to two ioport ranges. After a call to pcmcia_request_io(), the ports found there are reserved, after calling pcmcia_request_configuration(), they may be used.
@@ -42,7 +48,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors: * New IRQ request rules (as of 2.6.35) Instead of the old pcmcia_request_irq() interface, drivers may now choose between: - - calling request_irq/free_irq directly. Use the IRQ from *p_dev->irq. + + - calling request_irq/free_irq directly. Use the IRQ from `*p_dev->irq`. - use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will clean up automatically on calls to pcmcia_disable_device() or device ejection.
@@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors: exports for them were removed. * Unify detach and REMOVAL event code, as well as attach and INSERTION - code (as of 2.6.16) + code (as of 2.6.16):: + void (*remove) (struct pcmcia_device *dev); int (*probe) (struct pcmcia_device *dev); -* Move suspend, resume and reset out of event handler (as of 2.6.16) +* Move suspend, resume and reset out of event handler (as of 2.6.16):: + int (*suspend) (struct pcmcia_device *dev); int (*resume) (struct pcmcia_device *dev); + should be initialized in struct pcmcia_driver, and handle (SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events
@@ -117,7 +127,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors: * core functions no longer available (as of 2.6.11) The following functions have been removed from the kernel source because they are unused by all in-kernel drivers, and no external - driver was reported to rely on them: + driver was reported to rely on them:: + pcmcia_get_first_region() pcmcia_get_next_region() pcmcia_modify_window()
Documentation/pcmcia/driver.txt +9 -9
@@ -1,16 +1,16 @@ +============= PCMCIA Driver -------------- - +============= sysfs ----- New PCMCIA IDs may be added to a device driver pcmcia_device_id table at -runtime as shown below: +runtime as shown below:: -echo "match_flags manf_id card_id func_id function device_no \ -prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \ -/sys/bus/pcmcia/drivers/{driver}/new_id + echo "match_flags manf_id card_id func_id function device_no \ + prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \ + /sys/bus/pcmcia/drivers/{driver}/new_id All fields are passed in as hexadecimal values (no leading 0x). The meaning is described in the PCMCIA specification, the match_flags is
@@ -22,9 +22,9 @@ PCMCIA device listed in its (newly updated) pcmcia_device_id list. A common use-case is to add a new device according to the manufacturer ID and the card ID (form the manf_id and card_id file in the device tree). -For this, just use: +For this, just use:: -echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \ - /sys/bus/pcmcia/drivers/{driver}/new_id + echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \ + /sys/bus/pcmcia/drivers/{driver}/new_id after loading the driver.
Documentation/pcmcia/locking.txt +27 -12
@@ -1,3 +1,7 @@ +======= +Locking +======= + This file explains the locking and exclusion scheme used in the PCCARD and PCMCIA subsystems.
@@ -5,16 +9,21 @@ and PCMCIA subsystems. A) Overview, Locking Hierarchy: =============================== -pcmcia_socket_list_rwsem - protects only the list of sockets -- skt_mutex - serializes card insert / ejection - - ops_mutex - serializes socket operation +pcmcia_socket_list_rwsem + - protects only the list of sockets + +- skt_mutex + - serializes card insert / ejection + + - ops_mutex + - serializes socket operation B) Exclusion ============ The following functions and callbacks to struct pcmcia_socket must -be called with "skt_mutex" held: +be called with "skt_mutex" held:: socket_detect_change() send_event()
@@ -31,7 +40,7 @@ be called with "skt_mutex" held: struct pcmcia_callback *callback The following functions and callbacks to struct pcmcia_socket must -be called with "ops_mutex" held: +be called with "ops_mutex" held:: socket_reset() socket_setup()
@@ -39,7 +48,7 @@ be called with "ops_mutex" held: struct pccard_operations *ops struct pccard_resource_ops *resource_ops; -Note that send_event() and struct pcmcia_callback *callback must not be +Note that send_event() and `struct pcmcia_callback *callback` must not be called with "ops_mutex" held.
@@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex. The "main" struct pcmcia_socket is protected as follows (read-only fields or single-use fields not mentioned): -- by pcmcia_socket_list_rwsem: +- by pcmcia_socket_list_rwsem:: + struct list_head socket_list; -- by thread_lock: +- by thread_lock:: + unsigned int thread_events; -- by skt_mutex: +- by skt_mutex:: + u_int suspended_state; void (*tune_bridge); struct pcmcia_callback *callback; int resume_status; -- by ops_mutex: +- by ops_mutex:: + socket_state_t socket; u_int state; u_short lock_count;
@@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields or single-use fields not mentioned): -- by pcmcia_socket->ops_mutex: +- by pcmcia_socket->ops_mutex:: + struct list_head socket_device_list; struct config_t *function_config; u16 _irq:1;
@@ -111,7 +125,8 @@ or single-use fields not mentioned): u16 suspended:1; u16 _removed:1; -- by the PCMCIA driver: +- by the PCMCIA driver:: + io_req_t io; irq_req_t irq; config_req_t conf;
Signature · 1 line
2.20.1
Re: [PATCH 24/57] docs: pcmcia: convert it to ReST format
Quoted 5 lines · Mauro Carvalho Chehab
Convert the pcmcia docs to ReST format. Most of the changes here are trivial, making Sphinx properly identify titles, lists and literal blocks.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Thanks,
Dominik
PATCH 25/57 docs: power: convert docs to ReST
In reply to Mauro Carvalho ChehabConvert the PM documents to ReST, in order to allow them to build with Sphinx.
--- Documentation/power/apm-acpi.txt | 10 +- Documentation/power/basic-pm-debugging.txt | 77 ++- Documentation/power/charger-manager.txt | 101 +-- Documentation/power/drivers-testing.txt | 5 + Documentation/power/energy-model.txt | 101 +-- Documentation/power/freezing-of-tasks.txt | 91 +-- Documentation/power/interface.txt | 20 +- Documentation/power/opp.txt | 175 +++-- Documentation/power/pci.txt | 77 ++- Documentation/power/pm_qos_interface.txt | 127 ++-- Documentation/power/power_supply_class.txt | 269 +++++--- Documentation/power/powercap/powercap.txt | 297 ++++---- Documentation/power/regulator/consumer.txt | 141 ++-- Documentation/power/regulator/design.txt | 9 +- Documentation/power/regulator/machine.txt | 47 +- Documentation/power/regulator/overview.txt | 51 +- Documentation/power/regulator/regulator.txt | 18 +- Documentation/power/runtime_pm.txt | 234 ++++--- Documentation/power/s2ram.txt | 20 +- .../power/suspend-and-cpuhotplug.txt | 42 +- .../power/suspend-and-interrupts.txt | 2 + Documentation/power/swsusp-and-swap-files.txt | 15 +- Documentation/power/swsusp-dmcrypt.txt | 118 ++-- Documentation/power/swsusp.txt | 639 ++++++++++-------- Documentation/power/tricks.txt | 6 +- Documentation/power/userland-swsusp.txt | 53 +- Documentation/power/video.txt | 156 +++-- 27 files changed, 1637 insertions(+), 1264 deletions(-)
Documentation/power/apm-acpi.txt +7 -3
@@ -1,5 +1,7 @@ +============ APM or ACPI? ------------- +============ + If you have a relatively recent x86 mobile, desktop, or server system, odds are it supports either Advanced Power Management (APM) or Advanced Configuration and Power Interface (ACPI). ACPI is the newer
@@ -28,5 +30,7 @@ and be sure that they are started sometime in the system boot process. Go ahead and start both. If ACPI or APM is not available on your system the associated daemon will exit gracefully. - apmd: http://ftp.debian.org/pool/main/a/apmd/ - acpid: http://acpid.sf.net/ + ===== ======================================= + apmd http://ftp.debian.org/pool/main/a/apmd/ + acpid http://acpid.sf.net/ + ===== =======================================
Documentation/power/basic-pm-debugging.txt +46 -31
176 lines not on this page · raw message
Documentation/power/charger-manager.txt +53 -48
174 lines not on this page · raw message
Documentation/power/drivers-testing.txt +5 -0
@@ -1,7 +1,11 @@ +==================================================== Testing suspend and resume support in device drivers +==================================================== + (C) 2007 Rafael J. Wysocki <[email protected]>, GPL 1. Preparing the test system +============================ Unfortunately, to effectively test the support for the system-wide suspend and resume transitions in a driver, it is necessary to suspend and resume a fully
@@ -18,6 +22,7 @@ testing the new driver. Please see Documentation/power/basic-pm-debugging.txt for more information about the debugging of suspend/resume functionality. 2. Testing the driver +===================== Once you have resolved the suspend/resume-related problems with your test system without the new driver, you are ready to test it:
Documentation/power/energy-model.txt +52 -49
133 lines not on this page · raw message
Documentation/power/freezing-of-tasks.txt +52 -39
169 lines not on this page · raw message
Documentation/power/interface.txt +11 -9
@@ -1,4 +1,6 @@ +=========================================== Power Management Interface for System Sleep +=========================================== Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <[email protected]>
@@ -11,10 +13,10 @@ mounted at /sys). Reading from it returns a list of supported sleep states, encoded as: -'freeze' (Suspend-to-Idle) -'standby' (Power-On Suspend) -'mem' (Suspend-to-RAM) -'disk' (Suspend-to-Disk) +- 'freeze' (Suspend-to-Idle) +- 'standby' (Power-On Suspend) +- 'mem' (Suspend-to-RAM) +- 'disk' (Suspend-to-Disk) Suspend-to-Idle is always supported. Suspend-to-Disk is always supported too as long the kernel has been configured to support hibernation at all
@@ -32,11 +34,11 @@ Specifically, it tells the kernel what to do after creating a hibernation image. Reading from it returns a list of supported options encoded as: -'platform' (put the system into sleep using a platform-provided method) -'shutdown' (shut the system down) -'reboot' (reboot the system) -'suspend' (trigger a Suspend-to-RAM transition) -'test_resume' (resume-after-hibernation test mode) +- 'platform' (put the system into sleep using a platform-provided method) +- 'shutdown' (shut the system down) +- 'reboot' (reboot the system) +- 'suspend' (trigger a Suspend-to-RAM transition) +- 'test_resume' (resume-after-hibernation test mode) The currently selected option is printed in square brackets.
Documentation/power/opp.txt +106 -69
320 lines not on this page · raw message
Documentation/power/pci.txt +59 -18
360 lines not on this page · raw message
Documentation/power/pm_qos_interface.txt +70 -57
203 lines not on this page · raw message
Documentation/power/power_supply_class.txt +160 -109
303 lines not on this page · raw message
Documentation/power/powercap/powercap.txt +159 -138
359 lines not on this page · raw message
Documentation/power/regulator/consumer.txt +76 -65
264 lines not on this page · raw message
Documentation/power/regulator/design.txt +7 -2
@@ -1,3 +1,4 @@ +========================== Regulator API design notes ==========================
@@ -14,7 +15,9 @@ Safety have different power requirements, and not all components with power requirements are visible to software. - => The API should make no changes to the hardware state unless it has +.. note:: + + The API should make no changes to the hardware state unless it has specific knowledge that these changes are safe to perform on this particular system.
@@ -28,6 +31,8 @@ Consumer use cases - Many of the power supplies in the system will be shared between many different consumers. - => The consumer API should be structured so that these use cases are +.. note:: + + The consumer API should be structured so that these use cases are very easy to handle and so that consumers will work with shared supplies without any additional effort.
Documentation/power/regulator/machine.txt +24 -23
101 lines not on this page · raw message
Documentation/power/regulator/overview.txt +29 -22
104 lines not on this page · raw message
Documentation/power/regulator/regulator.txt +10 -8
@@ -1,3 +1,4 @@ +========================== Regulator Driver Interface ==========================
@@ -8,23 +9,24 @@ regulator drivers to register their services with the core framework. Registration ============ -Drivers can register a regulator by calling :- +Drivers can register a regulator by calling:: -struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc, - const struct regulator_config *config); + struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc, + const struct regulator_config *config); This will register the regulator's capabilities and operations to the regulator core. -Regulators can be unregistered by calling :- +Regulators can be unregistered by calling:: -void regulator_unregister(struct regulator_dev *rdev); + void regulator_unregister(struct regulator_dev *rdev); Regulator Events ================ + Regulators can send events (e.g. overtemperature, undervoltage, etc) to -consumer drivers by calling :- +consumer drivers by calling:: -int regulator_notifier_call_chain(struct regulator_dev *rdev, - unsigned long event, void *data); + int regulator_notifier_call_chain(struct regulator_dev *rdev, + unsigned long event, void *data);
Documentation/power/runtime_pm.txt +123 -111
204 lines not on this page · raw message
Documentation/power/suspend-and-cpuhotplug.txt +26 -16
42 lines not on this page · raw message
Documentation/power/suspend-and-interrupts.txt +2 -0
Lines of this file are not shown. View the raw message.
Documentation/power/swsusp-and-swap-files.txt +9 -6
Lines of this file are not shown. View the raw message.
Documentation/power/swsusp-dmcrypt.txt +60 -58
118 lines not on this page · raw message
Documentation/power/swsusp.txt +347 -292
639 lines not on this page · raw message
Documentation/power/userland-swsusp.txt +37 -16
53 lines not on this page · raw message
Documentation/power/video.txt +92 -64
156 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.20.1
Part of the diff is not shown here. View the raw message.
Re: [PATCH 25/57] docs: power: convert docs to ReST
Quoted 4 lines · Mauro Carvalho Chehab
Convert the PM documents to ReST, in order to allow them to build with Sphinx.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Re: [PATCH 25/57] docs: power: convert docs to ReST
In reply to Mauro Carvalho ChehabQuoted 2 lines · CEST Mauro Carvalho Chehab
Convert the PM documents to ReST, in order to allow them to build with Sphinx.
And what exactly is the motivation for doing that?
There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.
Thanks,
Rafael
Re: [PATCH 25/57] docs: power: convert docs to ReST
Em Tue, 16 Apr 2019 10:59:23 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:
Quoted 5 lines · CEST Mauro Carvalho Chehab
Quoted 2 lines
Convert the PM documents to ReST, in order to allow them to build with Sphinx.
And what exactly is the motivation for doing that?
Providing a little of context, I tried to submit a patchset that would just place existing documents on a sort of "staging" way, without actually reformatting:
https://lkml.org/lkml/2019/4/10/244
Jon had some concerns about such approach.
So, I split into one patch per subsystem. Then, I looked on each, and opted to do the conversion, as, on several cases, the conversion seemed to be easy enough.
My selfish motivation is that I was returning from vacations and wanted to review some stuff at the Kernel docs, but, discovered that, despite we started migrating the documentation on May, 2016, still the vast majority of documents that weren't converted.
For me, the main motivation for the conversion are:
1) Documents will be grouped into books and chapters, with makes easier to study them;
2) The Sphinx javascript is very convenient for seeking a document and a keyword within the body of the document;
3) Using a browser to read documentation allows to better scale the document to the screen I'm using.
That's said, sometimes I just prefer to convert the document to a PDF and read it on my tablet. PDF tools also provide similar features.
In other words, for my own consumption, I prefer reading documents using document tools, instead of reading in plain text.
Quoted 1 line
There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.
Feel free to use this patch as an starting point. If you prefer, I can split into smaller sets, but my main goal here is just to help to speedup the conversion.
Thanks,
Mauro
Rafael J. Wysocki
maintainerRe: [PATCH 25/57] docs: power: convert docs to ReST
Quoted 36 lines · Mauro Carvalho Chehab
Em Tue, 16 Apr 2019 10:59:23 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:Quoted 5 lines · CEST Mauro Carvalho Chehab
Quoted 2 lines
Convert the PM documents to ReST, in order to allow them to build with Sphinx.
And what exactly is the motivation for doing that?
Providing a little of context, I tried to submit a patchset that would just place existing documents on a sort of "staging" way, without actually reformatting:
https://lkml.org/lkml/2019/4/10/244Jon had some concerns about such approach.
So, I split into one patch per subsystem. Then, I looked on each, and opted to do the conversion, as, on several cases, the conversion seemed to be easy enough.
My selfish motivation is that I was returning from vacations and wanted to review some stuff at the Kernel docs, but, discovered that, despite we started migrating the documentation on May, 2016, still the vast majority of documents that weren't converted.
For me, the main motivation for the conversion are:
1) Documents will be grouped into books and chapters, with makes easier to study them;
2) The Sphinx javascript is very convenient for seeking a document and a keyword within the body of the document;
3) Using a browser to read documentation allows to better scale the document to the screen I'm using.
Quoted 7 lines
That's said, sometimes I just prefer to convert the document to a PDF and read it on my tablet. PDF tools also provide similar features.
In other words, for my own consumption, I prefer reading documents using document tools, instead of reading in plain text.
I see, thanks!
Quoted 5 lines
Quoted 1 line
There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.
Feel free to use this patch as an starting point. If you prefer, I can split into smaller sets, but my main goal here is just to help to speedup the conversion.
OK, we'll see. Thank you!
PATCH 26/57 docs: powerpc: convert docs to ReST
In reply to Mauro Carvalho ChehabConvert 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.
--- Documentation/powerpc/DAWR-POWER9.txt | 10 +- Documentation/powerpc/bootwrapper.txt | 28 ++- Documentation/powerpc/cpu_families.txt | 23 +-- Documentation/powerpc/cpu_features.txt | 6 +- Documentation/powerpc/cxl.txt | 46 +++-- Documentation/powerpc/cxlflash.txt | 8 +- Documentation/powerpc/dscr.txt | 18 +- .../powerpc/eeh-pci-error-recovery.txt | 108 +++++------ .../powerpc/firmware-assisted-dump.txt | 117 ++++++------ Documentation/powerpc/hvcs.txt | 108 ++++++----- Documentation/powerpc/isa-versions.rst | 13 +- Documentation/powerpc/mpc52xx.txt | 12 +- .../powerpc/pci_iov_resource_on_powernv.txt | 15 +- Documentation/powerpc/pmu-ebb.txt | 1 + Documentation/powerpc/ptrace.txt | 169 +++++++++--------- Documentation/powerpc/qe_firmware.txt | 37 ++-- Documentation/powerpc/syscall64-abi.txt | 29 +-- .../powerpc/transactional_memory.txt | 45 ++--- 18 files changed, 447 insertions(+), 346 deletions(-)
Documentation/powerpc/DAWR-POWER9.txt +5 -5
@@ -1,10 +1,11 @@ +===================== DAWR issues on POWER9 -============================ +===================== On POWER9 the 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: +this commit:: commit 9654153158d3e0684a1bdb76dbababdb7111d5a0 Author: Michael Neuling <[email protected]>
@@ -12,7 +13,7 @@ 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
@@ -55,4 +56,3 @@ guest is migrated to a POWER9 host, the watchpoint will be lost on the POWER9. Loads and stores to the watchpoint locations will not be trapped in GDB. The watchpoint is remembered, so if the guest is migrated back to the POWER8 host, it will start working again. -
Documentation/powerpc/bootwrapper.txt +21 -7
@@ -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
Documentation/powerpc/cpu_families.txt +12 -11
@@ -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 |
Documentation/powerpc/cpu_features.txt +5 -1
@@ -1,3 +1,7 @@ +============ +CPU Features +============ + Hollis Blanchard <[email protected]> 5 Jun 2002
@@ -32,7 +36,7 @@ anyways). After detecting the processor type, the kernel patches out sections of code that shouldn't be used by writing nop's over it. Using cpufeatures requires just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S -transfer_to_handler: +transfer_to_handler:: #ifdef CONFIG_ALTIVEC BEGIN_FTR_SECTION
Documentation/powerpc/cxl.txt +32 -14
133 lines not on this page · raw message
Documentation/powerpc/cxlflash.txt +6 -2
@@ -1,3 +1,7 @@ +================================ +Coherent Accelerator (CXL) Flash +================================ + Introduction ============
@@ -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.
Documentation/powerpc/dscr.txt +11 -7
@@ -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
Documentation/powerpc/eeh-pci-error-recovery.txt +55 -53
176 lines not on this page · raw message
Documentation/powerpc/firmware-assisted-dump.txt +63 -54
253 lines not on this page · raw message
Documentation/powerpc/hvcs.txt +61 -47
343 lines not on this page · raw message
Documentation/powerpc/isa-versions.rst +7 -6
@@ -1,11 +1,12 @@ +========================== 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
@@ -22,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
@@ -58,9 +59,9 @@ Power5 No PPC970 No ========== ==== -========== ==================== +========== ==================================== CPU Transactional Memory -========== ==================== +========== ==================================== Power9 Yes (* see transactional_memory.txt) Power8 Yes Power7 No
@@ -71,4 +72,4 @@ Power5++ No Power5+ No Power5 No PPC970 No -========== ==================== +========== ====================================
Documentation/powerpc/mpc52xx.txt +8 -4
@@ -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
Documentation/powerpc/pci_iov_resource_on_powernv.txt +13 -2
@@ -1,6 +1,13 @@ +=================================================== +PCI Express I/O Virtualization Resource on Powerenv +=================================================== + Wei Yang <[email protected]> + Benjamin Herrenschmidt <[email protected]> + Bjorn Helgaas <[email protected]> + 26 Aug 2014 This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks about considerations on enabling SRIOV on IODA2. 1. Introduction to Partitionable Endpoints +========================================== A Partitionable Endpoint (PE) is a way to group the various resources associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has its own set of PEs, etc. 2. Implementation of Partitionable Endpoints on P8 (IODA2) +========================================================== P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB. sense, but we haven't done it yet. 3. Considerations for SR-IOV on PowerKVM +======================================== * SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB. IODA supports 256 PEs, so segmented windows contain 256 segments, so if total_VFs is less than 256, we have the situation in Figure 1.0, where segments [total_VFs, 255] of the M64 window may map to some MMIO range on - other devices: + other devices:: 0 1 total_VFs - 1 +------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB. Figure 1.0 Direct map VF(n) BAR space Our current solution is to allocate 256 segments even if the VF(n) BAR - space doesn't need that much, as shown in Figure 1.1: + space doesn't need that much, as shown in Figure 1.1:: 0 1 total_VFs - 1 255 +------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB. responds to segments [total_VFs, 255]. 4. Implications for the Generic PCI Code +======================================== The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be aligned to the size of an individual VF BAR.
Documentation/powerpc/pmu-ebb.txt +1 -0
@@ -1,3 +1,4 @@ +======================== PMU Event Based Branches ========================
Documentation/powerpc/ptrace.txt +87 -82
212 lines not on this page · raw message
Documentation/powerpc/qe_firmware.txt +19 -18
@@ -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 ============================================
Documentation/powerpc/syscall64-abi.txt +17 -12
@@ -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 ----------
Documentation/powerpc/transactional_memory.txt +24 -21
91 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 27/57 docs: pps/pps.txt convert it to ReST and move to API book
In reply to Mauro Carvalho ChehabThis file is already in a good shape: just its title and adding some literal block markups is needed for it to be part of the document.
While it has a small chapter with sysfs stuff, most of the document is focused on driver development.
--- Documentation/pps/pps.txt | 67 ++++++++++++++++++++------------------- 1 file changed, 34 insertions(+), 33 deletions(-)
Documentation/pps/pps.txt +34 -33
@@ -1,8 +1,8 @@ +====================== +PPS - Pulse Per Second +====================== - PPS - Pulse Per Second - ---------------------- - -(C) Copyright 2007 Rodolfo Giometti <[email protected]> +Copyright (C) 2007 Rodolfo Giometti <[email protected]> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by
@@ -88,7 +88,7 @@ Coding example -------------- To register a PPS source into the kernel you should define a struct -pps_source_info as follows: +pps_source_info as follows:: static struct pps_source_info pps_ktimer_info = { .name = "ktimer",
@@ -101,12 +101,12 @@ pps_source_info as follows: }; and then calling the function pps_register_source() in your -initialization routine as follows: +initialization routine as follows:: source = pps_register_source(&pps_ktimer_info, PPS_CAPTUREASSERT | PPS_OFFSETASSERT); -The pps_register_source() prototype is: +The pps_register_source() prototype is:: int pps_register_source(struct pps_source_info *info, int default_params)
@@ -118,7 +118,7 @@ pps_source_info which describe the capabilities of the driver). Once you have registered a new PPS source into the system you can signal an assert event (for example in the interrupt handler routine) -just using: +just using:: pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
@@ -134,13 +134,13 @@ Please see the file drivers/pps/clients/pps-ktimer.c for example code. SYSFS support ------------- -If the SYSFS filesystem is enabled in the kernel it provides a new class: +If the SYSFS filesystem is enabled in the kernel it provides a new class:: $ ls /sys/class/pps/ pps0/ pps1/ pps2/ Every directory is the ID of a PPS sources defined in the system and -inside you find several files: +inside you find several files:: $ ls -F /sys/class/pps/pps0/ assert dev mode path subsystem@
@@ -148,7 +148,7 @@ inside you find several files: Inside each "assert" and "clear" file you can find the timestamp and a -sequence number: +sequence number:: $ cat /sys/class/pps/pps0/assert 1170026870.983207967#8
@@ -175,11 +175,11 @@ and the userland tools available in your distribution's pps-tools package, http://linuxpps.org , or https://github.com/redlab-i/pps-tools. Once you have enabled the compilation of pps-ktimer just modprobe it (if -not statically compiled): +not statically compiled):: # modprobe pps-ktimer -and the run ppstest as follow: +and the run ppstest as follow:: $ ./ppstest /dev/pps1 trying PPS source "/dev/pps1"
@@ -204,26 +204,27 @@ nor affordable. The cheap way is to load a PPS generator on one of the computers (master) and PPS clients on others (slaves), and use very simple cables to deliver signals using parallel ports, for example. -Parallel port cable pinout: -pin name master slave -1 STROBE *------ * -2 D0 * | * -3 D1 * | * -4 D2 * | * -5 D3 * | * -6 D4 * | * -7 D5 * | * -8 D6 * | * -9 D7 * | * -10 ACK * ------* -11 BUSY * * -12 PE * * -13 SEL * * -14 AUTOFD * * -15 ERROR * * -16 INIT * * -17 SELIN * * -18-25 GND *-----------* +Parallel port cable pinout:: + + pin name master slave + 1 STROBE *------ * + 2 D0 * | * + 3 D1 * | * + 4 D2 * | * + 5 D3 * | * + 6 D4 * | * + 7 D5 * | * + 8 D6 * | * + 9 D7 * | * + 10 ACK * ------* + 11 BUSY * * + 12 PE * * + 13 SEL * * + 14 AUTOFD * * + 15 ERROR * * + 16 INIT * * + 17 SELIN * * + 18-25 GND *-----------* Please note that parallel port interrupt occurs only on high->low transition, so it is used for PPS assert edge. PPS clear edge can be determined only
Signature · 1 line
2.20.1
PATCH 28/57 docs: ptp.txt: convert to ReST and move to driver-api
In reply to Mauro Carvalho ChehabThe conversion is trivial: just adjust title markups.
--- Documentation/ptp/ptp.txt | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-)
Documentation/ptp/ptp.txt +17 -9
@@ -1,5 +1,6 @@ - -* PTP hardware clock infrastructure for Linux +=========================================== +PTP hardware clock infrastructure for Linux +=========================================== This patch set introduces support for IEEE 1588 PTP clocks in Linux. Together with the SO_TIMESTAMPING socket options, this
@@ -22,7 +23,8 @@ - Period output signals configurable from user space - Synchronization of the Linux system time via the PPS subsystem -** PTP hardware clock kernel API +PTP hardware clock kernel API +============================= A PTP clock driver registers itself with the class driver. The class driver handles all of the dealings with user space. The
@@ -36,7 +38,8 @@ development, it can be useful to have more than one clock in a single system, in order to allow performance comparisons. -** PTP hardware clock user space API +PTP hardware clock user space API +================================= The class driver also creates a character device for each registered clock. User space can use an open file descriptor from
@@ -49,7 +52,8 @@ ancillary clock features. User space can receive time stamped events via blocking read() and poll(). -** Writing clock drivers +Writing clock drivers +===================== Clock drivers include include/linux/ptp_clock_kernel.h and register themselves by presenting a 'struct ptp_clock_info' to the
@@ -66,14 +70,17 @@ class driver, since the lock may also be needed by the clock driver's interrupt service routine. -** Supported hardware +Supported hardware +================== + + * Freescale eTSEC gianfar - + Freescale eTSEC gianfar - 2 Time stamp external triggers, programmable polarity (opt. interrupt) - 2 Alarm registers (optional interrupt) - 3 Periodic signals (optional interrupt) - + National DP83640 + * National DP83640 + - 6 GPIOs programmable as inputs or outputs - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be used as general inputs or outputs
@@ -81,6 +88,7 @@ - GPIO outputs can produce periodic signals - 1 interrupt pin - + Intel IXP465 + * Intel IXP465 + - Auxiliary Slave/Master Mode Snapshot (optional interrupt) - Target Time (optional interrupt)
Signature · 1 line
2.20.1
PATCH 29/57 docs: riscv: convert it to ReST format
In reply to Mauro Carvalho ChehabThe conversion here is trivial:
- Adjust the document title's markup
- Do some whitespace alignment;
- mark literal blocks;
- Use ReST way to markup indented lists.
--- Documentation/riscv/pmu.txt | 98 ++++++++++++++++++++----------------- 1 file changed, 52 insertions(+), 46 deletions(-)
Documentation/riscv/pmu.txt +52 -46
@@ -1,5 +1,7 @@ +=================================== Supporting PMUs on RISC-V platforms -========================================== +=================================== + Alan Kao <[email protected]>, Mar 2018 Introduction
@@ -77,13 +79,13 @@ Note that some features can be done in this stage as well: (2) privilege level setting (user space only, kernel space only, both); (3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*; (4) tweaks for non-sampling events, which will be utilized by functions such as -*perf_adjust_period*, usually something like the follows: + *perf_adjust_period*, usually something like the follows:: -if (!is_sampling_event(event)) { - hwc->sample_period = x86_pmu.max_period; - hwc->last_period = hwc->sample_period; - local64_set(&hwc->period_left, hwc->sample_period); -} + if (!is_sampling_event(event)) { + hwc->sample_period = x86_pmu.max_period; + hwc->last_period = hwc->sample_period; + local64_set(&hwc->period_left, hwc->sample_period); + } In the case of *riscv_base_pmu*, only (3) is provided for now.
@@ -94,10 +96,10 @@ In the case of *riscv_base_pmu*, only (3) is provided for now. 3.1. Interrupt Initialization This often occurs at the beginning of the *event_init* method. In common -practice, this should be a code segment like +practice, this should be a code segment like:: -int x86_reserve_hardware(void) -{ + int x86_reserve_hardware(void) + { int err = 0; if (!atomic_inc_not_zero(&pmc_refcount)) {
@@ -114,7 +116,7 @@ int x86_reserve_hardware(void) } return err; -} + } And the magic is in *reserve_pmc_hardware*, which usually does atomic operations to make implemented IRQ accessible from some global function pointer.
@@ -128,28 +130,28 @@ which will be introduced in the next section.) 3.2. IRQ Structure -Basically, a IRQ runs the following pseudo code: +Basically, a IRQ runs the following pseudo code:: -for each hardware counter that triggered this overflow + for each hardware counter that triggered this overflow - get the event of this counter + get the event of this counter - // following two steps are defined as *read()*, - // check the section Reading/Writing Counters for details. - count the delta value since previous interrupt - update the event->count (# event occurs) by adding delta, and - event->hw.period_left by subtracting delta + // following two steps are defined as *read()*, + // check the section Reading/Writing Counters for details. + count the delta value since previous interrupt + update the event->count (# event occurs) by adding delta, and + event->hw.period_left by subtracting delta - if the event overflows - sample data - set the counter appropriately for the next overflow + if the event overflows + sample data + set the counter appropriately for the next overflow - if the event overflows again - too frequently, throttle this event - fi - fi + if the event overflows again + too frequently, throttle this event + fi + fi -end for + end for However as of this writing, none of the RISC-V implementations have designed an interrupt for perf, so the details are to be completed in the future.
@@ -195,23 +197,26 @@ A normal flow of these state transitions are as follows: At this stage, a general event is bound to a physical counter, if any. The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now stopped, and the (software) event count does not need updating. -** *start* is then called, and the counter is enabled. - With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check - previous section for detail). - Nothing is written if the flag does not contain PERF_EF_RELOAD. - The state now is reset to none, because it is neither stopped nor updated - (the counting already started) + + - *start* is then called, and the counter is enabled. + With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check + previous section for detail). + Nothing is written if the flag does not contain PERF_EF_RELOAD. + The state now is reset to none, because it is neither stopped nor updated + (the counting already started) + * When being context-switched out, *del* is called. It then checks out all the events in the PMU and calls *stop* to update their counts. -** *stop* is called by *del* - and the perf core with flag PERF_EF_UPDATE, and it often shares the same - subroutine as *read* with the same logic. - The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again. -** Life cycle of these two pairs: *add* and *del* are called repeatedly as - tasks switch in-and-out; *start* and *stop* is also called when the perf core - needs a quick stop-and-start, for instance, when the interrupt period is being - adjusted. + - *stop* is called by *del* + and the perf core with flag PERF_EF_UPDATE, and it often shares the same + subroutine as *read* with the same logic. + The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again. + + - Life cycle of these two pairs: *add* and *del* are called repeatedly as + tasks switch in-and-out; *start* and *stop* is also called when the perf core + needs a quick stop-and-start, for instance, when the interrupt period is being + adjusted. Current implementation is sufficient for now and can be easily extended to features in the future.
@@ -225,25 +230,26 @@ A. Related Structures Both structures are designed to be read-only. *struct pmu* defines some function pointer interfaces, and most of them take -*struct perf_event* as a main argument, dealing with perf events according to -perf's internal state machine (check kernel/events/core.c for details). + *struct perf_event* as a main argument, dealing with perf events according to + perf's internal state machine (check kernel/events/core.c for details). *struct riscv_pmu* defines PMU-specific parameters. The naming follows the -convention of all other architectures. + convention of all other architectures. * struct perf_event: include/linux/perf_event.h * struct hw_perf_event The generic structure that represents perf events, and the hardware-related -details. + details. * struct riscv_hw_events: arch/riscv/include/asm/perf_event.h The structure that holds the status of events, has two fixed members: -the number of events and the array of the events. + the number of events and the array of the events. References ---------- [1] https://github.com/riscv/riscv-linux/pull/124 + [2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA
Signature · 7 lines
2.20.1 _______________________________________________ linux-riscv mailing list [email protected] http://lists.infradead.org/mailman/listinfo/linux-riscv
PATCH 30/57 docs: s390: Debugging390.txt: convert table to ascii artwork
In reply to Mauro Carvalho ChehabThe first bit/value table inside the document is very hard to read and won't fit ReST format. Convert it to a nice ascii artwork table with makes it easier to read and is compatible with ReST format parser on Sphinx.
--- Documentation/s390/Debugging390.txt | 210 ++++++++++++++++------------ 1 file changed, 120 insertions(+), 90 deletions(-)
Documentation/s390/Debugging390.txt +120 -90
@@ -78,96 +78,126 @@ e.g. switching address translation off requires that you have a logical=physical mapping for the address you are currently running at. - Bit Value -s/390 z/Architecture -0 0 Reserved ( must be 0 ) otherwise specification exception occurs. - -1 1 Program Event Recording 1 PER enabled, - PER is used to facilitate debugging e.g. single stepping. - -2-4 2-4 Reserved ( must be 0 ). - -5 5 Dynamic address translation 1=DAT on. - -6 6 Input/Output interrupt Mask - -7 7 External interrupt Mask used primarily for interprocessor - signalling and clock interrupts. - -8-11 8-11 PSW Key used for complex memory protection mechanism - (not used under linux) - -12 12 1 on s/390 0 on z/Architecture - -13 13 Machine Check Mask 1=enable machine check interrupts - -14 14 Wait State. Set this to 1 to stop the processor except for - interrupts and give time to other LPARS. Used in CPU idle in - the kernel to increase overall usage of processor resources. - -15 15 Problem state ( if set to 1 certain instructions are disabled ) - all linux user programs run with this bit 1 - ( useful info for debugging under VM ). - -16-17 16-17 Address Space Control - - 00 Primary Space Mode: - The register CR1 contains the primary address-space control ele- - ment (PASCE), which points to the primary space region/segment - table origin. - - 01 Access register mode - - 10 Secondary Space Mode: - The register CR7 contains the secondary address-space control - element (SASCE), which points to the secondary space region or - segment table origin. - - 11 Home Space Mode: - The register CR13 contains the home space address-space control - element (HASCE), which points to the home space region/segment - table origin. - - See "Address Spaces on Linux for s/390 & z/Architecture" below - for more information about address space usage in Linux. - -18-19 18-19 Condition codes (CC) - -20 20 Fixed point overflow mask if 1=FPU exceptions for this event - occur ( normally 0 ) - -21 21 Decimal overflow mask if 1=FPU exceptions for this event occur - ( normally 0 ) - -22 22 Exponent underflow mask if 1=FPU exceptions for this event occur - ( normally 0 ) - -23 23 Significance Mask if 1=FPU exceptions for this event occur - ( normally 0 ) - -24-31 24-30 Reserved Must be 0. - - 31 Extended Addressing Mode - 32 Basic Addressing Mode - Used to set addressing mode - PSW 31 PSW 32 - 0 0 24 bit - 0 1 31 bit - 1 1 64 bit - -32 1=31 bit addressing mode 0=24 bit addressing mode (for backward - compatibility), linux always runs with this bit set to 1 - -33-64 Instruction address. - 33-63 Reserved must be 0 - 64-127 Address - In 24 bits mode bits 64-103=0 bits 104-127 Address - In 31 bits mode bits 64-96=0 bits 97-127 Address - Note: unlike 31 bit mode on s/390 bit 96 must be zero - when loading the address with LPSWE otherwise a - specification exception occurs, LPSW is fully backward - compatible. - ++-------------------------+-------------------------------------------------+ +| Bit | | ++--------+----------------+ Value | +| s/390 | z/Architecture | | ++========+================+=================================================+ +| 0 | 0 | Reserved (must be 0) otherwise specification | +| | | exception occurs. | ++--------+----------------+-------------------------------------------------+ +| 1 | 1 | Program Event Recording 1 PER enabled, | +| | | PER is used to facilitate debugging e.g. | +| | | single stepping. | ++--------+----------------+-------------------------------------------------+ +| 2-4 | 2-4 | Reserved (must be 0). | ++--------+----------------+-------------------------------------------------+ +| 5 | 5 | Dynamic address translation 1=DAT on. | ++--------+----------------+-------------------------------------------------+ +| 6 | 6 | Input/Output interrupt Mask | ++--------+----------------+-------------------------------------------------+ +| 7 | 7 | External interrupt Mask used primarily for | +| | | interprocessor signalling and clock interrupts. | ++--------+----------------+-------------------------------------------------+ +| 8-11 | 8-11 | PSW Key used for complex memory protection | +| | | mechanism (not used under linux) | ++--------+----------------+-------------------------------------------------+ +| 12 | 12 | 1 on s/390 0 on z/Architecture | ++--------+----------------+-------------------------------------------------+ +| 13 | 13 | Machine Check Mask 1=enable machine check | +| | | interrupts | ++--------+----------------+-------------------------------------------------+ +| 14 | 14 | Wait State. Set this to 1 to stop the processor | +| | | except for interrupts and give time to other | +| | | LPARS. Used in CPU idle in the kernel to | +| | | increase overall usage of processor resources. | ++--------+----------------+-------------------------------------------------+ +| 15 | 15 | Problem state (if set to 1 certain instructions | +| | | are disabled). All linux user programs run with | +| | | this bit 1 (useful info for debugging under VM).| ++--------+----------------+-------------------------------------------------+ +| 16-17 | 16-17 | Address Space Control | +| | | | +| | | 00 Primary Space Mode: | +| | | | +| | | The register CR1 contains the primary | +| | | address-space control element (PASCE), which | +| | | points to the primary space region/segment | +| | | table origin. | +| | | | +| | | 01 Access register mode | +| | | | +| | | 10 Secondary Space Mode: | +| | | | +| | | The register CR7 contains the secondary | +| | | address-space control element (SASCE), which | +| | | points to the secondary space region or | +| | | segment table origin. | +| | | | +| | | 11 Home Space Mode: | +| | | | +| | | The register CR13 contains the home space | +| | | address-space control element (HASCE), which | +| | | points to the home space region/segment | +| | | table origin. | +| | | | +| | | See "Address Spaces on Linux for s/390 & | +| | | z/Architecture" below for more information | +| | | about address space usage in Linux. | ++--------+----------------+-------------------------------------------------+ +| 18-19 | 18-19 | Condition codes (CC) | ++--------+----------------+-------------------------------------------------+ +| 20 | 20 | Fixed point overflow mask if 1=FPU exceptions | +| | | for this event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 21 | 21 | Decimal overflow mask if 1=FPU exceptions for | +| | | this event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 22 | 22 | Exponent underflow mask if 1=FPU exceptions | +| | | for this event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 23 | 23 | Significance Mask if 1=FPU exceptions for this | +| | | event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 24-31 | 24-30 | Reserved Must be 0. | +| +----------------+-------------------------------------------------+ +| | 31 | Extended Addressing Mode | +| +----------------+-------------------------------------------------+ +| | 32 | Basic Addressing Mode | +| | | | +| | | Used to set addressing mode | +| | | | +| | | +---------+----------+----------+ | +| | | | PSW 31 | PSW 32 | | | +| | | +---------+----------+----------+ | +| | | | 0 | 0 | 24 bit | | +| | | +---------+----------+----------+ | +| | | | 0 | 1 | 31 bit | | +| | | +---------+----------+----------+ | +| | | | 1 | 1 | 64 bit | | +| | | +---------+----------+----------+ | ++--------+----------------+-------------------------------------------------+ +| 32 | | 1=31 bit addressing mode 0=24 bit addressing | +| | | mode (for backward compatibility), linux | +| | | always runs with this bit set to 1 | ++--------+----------------+-------------------------------------------------+ +| 33-64 | | Instruction address. | +| +----------------+-------------------------------------------------+ +| | 33-63 | Reserved must be 0 | +| +----------------+-------------------------------------------------+ +| | 64-127 | Address | +| | | | +| | | - In 24 bits mode bits 64-103=0 bits 104-127 | +| | | Address | +| | | - In 31 bits mode bits 64-96=0 bits 97-127 | +| | | Address | +| | | | +| | | Note: | +| | | unlike 31 bit mode on s/390 bit 96 must be | +| | | zero when loading the address with LPSWE | +| | | otherwise a specification exception occurs, | +| | | LPSW is fully backward compatible. | ++--------+----------------+-------------------------------------------------+ Prefix Page(s) --------------
Signature · 1 line
2.20.1
PATCH 31/57 docs: s390: convert text files to ReST format
In reply to Mauro Carvalho ChehabConvert all text files with s390 documentation to ReST format.
Tried to preserve as much as possible the original document format. Still, some of the files required some work in order for it to be visible on both plain text and after converted to html.
--- Documentation/s390/3270.txt | 85 +- Documentation/s390/CommonIO | 47 +- Documentation/s390/DASD | 33 +- Documentation/s390/Debugging390.txt | 2389 ++++++++++++++++----------- Documentation/s390/cds.txt | 354 ++-- Documentation/s390/driver-model.txt | 179 +- Documentation/s390/monreader.txt | 85 +- Documentation/s390/qeth.txt | 36 +- Documentation/s390/s390dbf.txt | 781 +++++---- Documentation/s390/vfio-ap.txt | 487 +++--- Documentation/s390/vfio-ccw.txt | 88 +- Documentation/s390/zfcpdump.txt | 2 + 12 files changed, 2686 insertions(+), 1880 deletions(-)
Documentation/s390/3270.txt +56 -29
@@ -1,13 +1,17 @@ +=============================== IBM 3270 Display System support +=============================== This file describes the driver that supports local channel attachment of IBM 3270 devices. It consists of three sections: + * Introduction * Installation * Operation -INTRODUCTION. +Introduction +============ This paper describes installing and operating 3270 devices under Linux/390. A 3270 device is a block-mode rows-and-columns terminal of
@@ -17,12 +21,12 @@ twenty and thirty years ago. You may have 3270s in-house and not know it. If you're using the VM-ESA operating system, define a 3270 to your virtual machine by using the command "DEF GRAF <hex-address>" This paper presumes you will be -defining four 3270s with the CP/CMS commands +defining four 3270s with the CP/CMS commands: - DEF GRAF 620 - DEF GRAF 621 - DEF GRAF 622 - DEF GRAF 623 + - DEF GRAF 620 + - DEF GRAF 621 + - DEF GRAF 622 + - DEF GRAF 623 Your network connection from VM-ESA allows you to use x3270, tn3270, or another 3270 emulator, started from an xterm window on your PC or
@@ -34,7 +38,8 @@ This paper covers installation of the driver and operation of a dialed-in x3270. -INSTALLATION. +Installation +============ You install the driver by installing a patch, doing a kernel build, and running the configuration script (config3270.sh, in this directory).
@@ -59,13 +64,15 @@ Use #CP TERM CONMODE 3270 to change it to 3270. If you generate only at boot time to a 3270 if it is a 3215. In brief, these are the steps: + 1. Install the tub3270 patch - 2. (If a module) add a line to a file in /etc/modprobe.d/*.conf + 2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf` 3. (If VM) define devices with DEF GRAF 4. Reboot 5. Configure To test that everything works, assuming VM and x3270, + 1. Bring up an x3270 window. 2. Use the DIAL command in that window. 3. You should immediately see a Linux login screen.
@@ -74,7 +81,8 @@ Here are the installation steps in detail: 1. The 3270 driver is a part of the official Linux kernel source. Build a tree with the kernel source and any necessary - patches. Then do + patches. Then do:: + make oldconfig (If you wish to disable 3215 console support, edit .config; change CONFIG_TN3215's value to "n";
@@ -84,20 +92,22 @@ Here are the installation steps in detail: make modules_install 2. (Perform this step only if you have configured tub3270 as a - module.) Add a line to a file /etc/modprobe.d/*.conf to automatically + module.) Add a line to a file `/etc/modprobe.d/*.conf` to automatically load the driver when it's needed. With this line added, you will see login prompts appear on your 3270s as soon as boot is complete (or with emulated 3270s, as soon as you dial into your vm guest using the command "DIAL <vmguestname>"). Since the line-mode major number is - 227, the line to add should be: + 227, the line to add should be:: + alias char-major-227 tub3270 3. Define graphic devices to your vm guest machine, if you haven't already. Define them before you reboot (reipl): - DEFINE GRAF 620 - DEFINE GRAF 621 - DEFINE GRAF 622 - DEFINE GRAF 623 + + - DEFINE GRAF 620 + - DEFINE GRAF 621 + - DEFINE GRAF 622 + - DEFINE GRAF 623 4. Reboot. The reboot process scans hardware devices, including 3270s, and this enables the tub3270 driver once loaded to respond
@@ -107,21 +117,23 @@ Here are the installation steps in detail: 5. Run the 3270 configuration script config3270. It is distributed in this same directory, Documentation/s390, as - config3270.sh. Inspect the output script it produces, + config3270.sh. Inspect the output script it produces, /tmp/mkdev3270, and then run that script. This will create the necessary character special device files and make the necessary changes to /etc/inittab. Then notify /sbin/init that /etc/inittab has changed, by issuing - the telinit command with the q operand: + the telinit command with the q operand:: + cd Documentation/s390 sh config3270.sh sh /tmp/mkdev3270 telinit q - This should be sufficient for your first time. If your 3270 + This should be sufficient for your first time. If your 3270 configuration has changed and you're reusing config3270, you - should follow these steps: + should follow these steps:: + Change 3270 configuration Reboot Run config3270 and /tmp/mkdev3270
@@ -132,8 +144,10 @@ Here are the testing steps in detail: 1. Bring up an x3270 window, or use an actual hardware 3278 or 3279, or use the 3270 emulator of your choice. You would be running the emulator on your PC or workstation. You would use - the command, for example, + the command, for example:: + x3270 vm-esa-domain-name & + if you wanted a 3278 Model 4 with 43 rows of 80 columns, the default model number. The driver does not take advantage of extended attributes.
@@ -144,7 +158,8 @@ Here are the testing steps in detail: 2. Use the DIAL command instead of the LOGIN command to connect to one of the virtual 3270s you defined with the DEF GRAF - commands: + commands:: + dial my-vm-guest-name 3. You should immediately see a login prompt from your
@@ -171,14 +186,17 @@ Here are the testing steps in detail: Wrong major number? Wrong minor number? There's your problem! - D. Do you get the message + D. Do you get the message:: + "HCPDIA047E my-vm-guest-name 0620 does not exist"? + If so, you must issue the command "DEF GRAF 620" from your VM 3215 console and then reboot the system. OPERATION. +========== The driver defines three areas on the 3270 screen: the log area, the input area, and the status area.
@@ -203,8 +221,10 @@ which indicates no scrolling will occur. (If you hit ENTER with "Linux Running" and nothing typed, the application receives a newline.) You may change the scrolling timeout value. For example, the following -command line: +command line:: + echo scrolltime=60 > /proc/tty/driver/tty3270 + changes the scrolling timeout value to 60 sec. Set scrolltime to 0 if you wish to prevent scrolling entirely.
@@ -228,7 +248,8 @@ cause an EOF also by typing "^D" and hitting ENTER. No PF key is preassigned to cause a job suspension, but you may cause a job suspension by typing "^Z" and hitting ENTER. You may wish to assign this function to a PF key. To make PF7 cause job suspension, -execute the command: +execute the command:: + echo pf7=^z > /proc/tty/driver/tty3270 If the input you type does not end with the two characters "^n", the
@@ -243,8 +264,10 @@ command is entered into the stack only when the input area is not made invisible (such as for password entry) and it is not identical to the current top entry. PF10 rotates backward through the command stack; PF11 rotates forward. You may assign the backward function to any PF -key (or PA key, for that matter), say, PA3, with the command: +key (or PA key, for that matter), say, PA3, with the command:: + echo -e pa3=\\033k > /proc/tty/driver/tty3270 + This assigns the string ESC-k to PA3. Similarly, the string ESC-j performs the forward function. (Rationale: In bash with vi-mode line editing, ESC-k and ESC-j retrieve backward and forward history.
@@ -252,15 +275,19 @@ Suggestions welcome.) Is a stack size of twenty commands not to your liking? Change it on the fly. To change to saving the last 100 commands, execute the -command: +command:: + echo recallsize=100 > /proc/tty/driver/tty3270 Have a command you issue frequently? Assign it to a PF or PA key! Use -the command - echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270 +the command:: + + echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270 + to execute the commands mkdir foobar and cd foobar immediately when you hit PF24. Want to see the command line first, before you execute it? -Use the -n option of the echo command: +Use the -n option of the echo command:: + echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
Documentation/s390/CommonIO +31 -16
108 lines not on this page · raw message
Documentation/s390/DASD +22 -11
@@ -1,4 +1,6 @@ +================== DASD device driver +================== S/390's disk devices (DASDs) are managed by Linux via the DASD device driver. It is valid for all types of DASDs and represents them to
@@ -14,14 +16,14 @@ parameters are to be given in hexadecimal notation without a leading If you supply kernel parameters the different instances are processed in order of appearance and a minor number is reserved for any device covered by the supplied range up to 64 volumes. Additional DASDs are -ignored. If you do not supply the 'dasd=' kernel parameter at all, the +ignored. If you do not supply the 'dasd=' kernel parameter at all, the DASD driver registers all supported DASDs of your system to a minor number in ascending order of the subchannel number. The driver currently supports ECKD-devices and there are stubs for support of the FBA and CKD architectures. For the FBA architecture only some smart data structures are missing to make the support -complete. +complete. We performed our testing on 3380 and 3390 type disks of different sizes, under VM and on the bare hardware (LPAR), using internal disks of the multiprise as well as a RAMAC virtual array. Disks exported by
@@ -34,19 +36,22 @@ accessibility of the DASD from other OSs. In a later stage we will provide support of partitions, maybe VTOC oriented or using a kind of partition table in the label record. -USAGE +Usage +===== -Low-level format (?CKD only) For using an ECKD-DASD as a Linux harddisk you have to low-level format the tracks by issuing the BLKDASDFORMAT-ioctl on that device. This will erase any data on that volume including IBM volume -labels, VTOCs etc. The ioctl may take a 'struct format_data *' or -'NULL' as an argument. -typedef struct { +labels, VTOCs etc. The ioctl may take a `struct format_data *` or +'NULL' as an argument:: + + typedef struct { int start_unit; int stop_unit; int blksize; -} format_data_t; + } format_data_t; + When a NULL argument is passed to the BLKDASDFORMAT ioctl the whole disk is formatted to a blocksize of 1024 bytes. Otherwise start_unit and stop_unit are the first and last track to be formatted. If
@@ -56,17 +61,23 @@ up to the last track. blksize can be any power of two between 512 and 1kB blocks anyway and you gain approx. 50% of capacity increasing your blksize from 512 byte to 1kB. --Make a filesystem +Make a filesystem +================= + Then you can mk??fs the filesystem of your choice on that volume or partition. For reasons of sanity you should build your filesystem on -the partition /dev/dd?1 instead of the whole volume. You only lose 3kB +the partition /dev/dd?1 instead of the whole volume. You only lose 3kB but may be sure that you can reuse your data after introduction of a real partition table. -BUGS: +Bugs +==== + - Performance sometimes is rather low because we don't fully exploit clustering -TODO-List: +TODO-List +========= + - Add IBM'S Disk layout to genhd - Enhance driver to use more than one major number - Enable usage as a module
Documentation/s390/Debugging390.txt +1415 -974
2,600 lines not on this page · raw message
Documentation/s390/cds.txt +206 -148
354 lines not on this page · raw message
Documentation/s390/driver-model.txt +110 -69
179 lines not on this page · raw message
Documentation/s390/monreader.txt +50 -35
85 lines not on this page · raw message
Documentation/s390/s390dbf.txt +454 -327
781 lines not on this page · raw message
Documentation/s390/vfio-ap.txt +258 -229
487 lines not on this page · raw message
Documentation/s390/vfio-ccw.txt +57 -31
88 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.20.1
Part of the diff is not shown here. View the raw message.
PATCH 32/57 s390: include/asm/debug.h add kerneldoc markups
In reply to Mauro Carvalho ChehabInstead of keeping the documentation inside s390dbf.txt, move them to arch/s390/include/asm/debug.h, using standard kernel-doc markups.
Those were converted to kerneldoc using this specially made script and manually editted:
<script>
use strict;
my $mode = "";
my $parameter = "";
my $ret = "";
my $descr = "";
sub add_var($)
{
my $ln = shift;
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
$ln =~ s/^(\S+)\s+/$1\t/;
print " * \@$ln\n";
}sub add_return($)
{
my $ln = shift;
print " *\n * Return:\n" if ($mode ne "Return Value:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * - $ln\n";
}sub add_description($)
{
my $ln = shift;
print " *\n * \n" if ($mode ne "Description:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * $ln\n";
}sub flush_results()
{
print " */\n\n";
}while (<>) {
if (m/^[\-]+$/) {
flush_results();
$mode = "";
$parameter = "";
$ret = "";
$descr = "";
next;
}
if (m/(Parameter:)(.*)/) {
print " *\n" if ($mode eq "func");
add_var($2);
$mode = $1;
next;
}
if (m/(Return Value:)(.*)/) {
add_return($2);
$mode = $1;
next;
}
if (m/(Description:)(.*)/) {
add_description($2);
$mode = $1;
next;
}
if ($mode eq "Parameter:") {
add_var($_);
next;
}
if ($mode eq "Return Value:") {
add_return($_);
next;
}
if ($mode eq "Description:") {
add_description($_);
next;
}
next if (m/^\s*$/);
if (m/^\S+.*\s\*?(\S+)\s*\(/) {
if ($mode eq "") {
print "/**\n * $1()\n";
} else {
print " * $1()\n";
}
$mode="func";
}
}flush_results();
</script>
--- Documentation/s390/s390dbf.txt | 322 +-------------------------------- arch/s390/include/asm/debug.h | 231 +++++++++++++++++++++++ 2 files changed, 232 insertions(+), 321 deletions(-)
Documentation/s390/s390dbf.txt +1 -321
@@ -107,327 +107,7 @@ will stay deactivated. Kernel Interfaces: ------------------ ----------------------------------------------------------------------------- - -:: - - debug_info_t *debug_register(char *name, int pages, int nr_areas, - int buf_size); - -Parameter: - name: - Name of debug log (e.g. used for debugfs entry) - pages: - Number of pages, which will be allocated per area - nr_areas: - Number of debug areas - buf_size: - Size of data area in each debug entry - -Return Value: - Handle for generated debug area - - NULL if register failed - -Description: Allocates memory for a debug log - Must not be called within an interrupt handler - ----------------------------------------------------------------------------- - -:: - - debug_info_t *debug_register_mode(char *name, int pages, int nr_areas, - int buf_size, mode_t mode, uid_t uid, - gid_t gid); - -Parameter: - name: - Name of debug log (e.g. used for debugfs entry) - pages: - Number of pages, which will be allocated per area - nr_areas: - Number of debug areas - buf_size: - Size of data area in each debug entry - mode: - File mode for debugfs files. E.g. S_IRWXUGO - uid: - User ID for debugfs files. Currently only 0 is - supported. - gid: - Group ID for debugfs files. Currently only 0 is - supported. - -Return Value: - Handle for generated debug area - - NULL if register failed - -Description: - Allocates memory for a debug log - Must not be called within an interrupt handler - ---------------------------------------------------------------------------- - -:: - - void debug_unregister (debug_info_t * id); - -Parameter: - id: - handle for debug log - -Return Value: - none - -Description: - frees memory for a debug log and removes all registered debug - views. - - Must not be called within an interrupt handler - ---------------------------------------------------------------------------- - -:: - - void debug_set_level (debug_info_t * id, int new_level); - -Parameter: id: handle for debug log - new_level: new debug level - -Return Value: - none - -Description: - Sets new actual debug level if new_level is valid. - ---------------------------------------------------------------------------- - -:: - - bool debug_level_enabled (debug_info_t * id, int level); - -Parameter: - id: - handle for debug log - level: - debug level - -Return Value: - True if level is less or equal to the current debug level. - -Description: - Returns true if debug events for the specified level would be - logged. Otherwise returns false. - ---------------------------------------------------------------------------- - -:: - - void debug_stop_all(void); - -Parameter: - none - -Return Value: - none - -Description: - stops the debug feature if stopping is allowed. Currently - used in case of a kernel oops. - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_event (debug_info_t* id, int level, void* data, - int length); - -Parameter: - id: - handle for debug log - level: - debug level - data: - pointer to data for debug entry - length: - length of data in bytes - -Return Value: - Address of written debug entry - -Description: - writes debug entry to active debug area (if level <= actual - debug level) - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_int_event (debug_info_t * id, int level, - unsigned int data); - debug_entry_t* debug_long_event(debug_info_t * id, int level, - unsigned long data); - -Parameter: - id: - handle for debug log - level: - debug level - data: - integer value for debug entry - -Return Value: - Address of written debug entry - -Description: - writes debug entry to active debug area (if level <= actual - debug level) - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_text_event (debug_info_t * id, int level, - const char* data); - -Parameter: - id: - handle for debug log - level: - debug level - data: - string for debug entry - -Return Value: - Address of written debug entry - -Description: - writes debug entry in ascii format to active debug area - (if level <= actual debug level) - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_sprintf_event (debug_info_t * id, int level, - char* string,...); - -Parameter: - id: - handle for debug log - level: - debug level - string: - format string for debug entry - ...: - varargs used as in sprintf() - -Return Value: Address of written debug entry - -Description: - writes debug entry with format string and varargs (longs) to - active debug area (if level $<=$ actual debug level). - floats and long long datatypes cannot be used as varargs. - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_exception (debug_info_t* id, int level, void* data, - int length); - -Parameter: - id: - handle for debug log - level: - debug level - data: - pointer to data for debug entry - length: - length of data in bytes - -Return Value: - Address of written debug entry - -Description: - writes debug entry to active debug area (if level <= actual - debug level) and switches to next debug area - ---------------------------------------------------------------------------- - -:: - debug_entry_t* debug_int_exception (debug_info_t * id, int level, - unsigned int data); - debug_entry_t* debug_long_exception(debug_info_t * id, int level, - unsigned long data); - -Parameter: id: handle for debug log - level: debug level - data: integer value for debug entry - -Return Value: Address of written debug entry - -Description: writes debug entry to active debug area (if level <= actual - debug level) and switches to next debug area - ---------------------------------------------------------------------------- - -debug_entry_t* debug_text_exception (debug_info_t * id, int level, - const char* data); - -Parameter: id: handle for debug log - level: debug level - data: string for debug entry - -Return Value: Address of written debug entry - -Description: writes debug entry in ascii format to active debug area - (if level <= actual debug level) and switches to next debug - area - ---------------------------------------------------------------------------- - -debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level, - char* string,...); - -Parameter: id: handle for debug log - level: debug level - string: format string for debug entry - ...: varargs used as in sprintf() - -Return Value: Address of written debug entry - -Description: writes debug entry with format string and varargs (longs) to - active debug area (if level $<=$ actual debug level) and - switches to next debug area. - floats and long long datatypes cannot be used as varargs. - ---------------------------------------------------------------------------- - -int debug_register_view (debug_info_t * id, struct debug_view *view); - -Parameter: id: handle for debug log - view: pointer to debug view struct - -Return Value: 0 : ok - < 0: Error - -Description: registers new debug view and creates debugfs dir entry - ---------------------------------------------------------------------------- - -int debug_unregister_view (debug_info_t * id, struct debug_view *view); - -Parameter: id: handle for debug log - view: pointer to debug view struct - -Return Value: 0 : ok - < 0: Error - -Description: unregisters debug view and removes debugfs dir entry - - +.. kernel-doc:: arch/s390/include/asm/debug.h Predefined views: -----------------
arch/s390/include/asm/debug.h +231 -0
317 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 33/57 docs: serial: convert it to ReST format
In reply to Mauro Carvalho ChehabThe converted files are focused at the Kernel internal API, so, this is a good candidate for the kernel API set of books.
--- Documentation/serial/README.cycladesZ | 5 +- Documentation/serial/driver | 113 +++- Documentation/serial/moxa-smartio | 750 +++++++++++++----------- Documentation/serial/n_gsm.txt | 81 +-- Documentation/serial/rocket.txt | 144 +++-- Documentation/serial/serial-iso7816.txt | 21 +- Documentation/serial/serial-rs485.txt | 22 +- Documentation/serial/tty.txt | 111 ++-- 8 files changed, 719 insertions(+), 528 deletions(-)
Documentation/serial/README.cycladesZ +4 -1
@@ -1,8 +1,11 @@ +================ +Cyclades-Z notes +================ The Cyclades-Z must have firmware loaded onto the card before it will operate. This operation should be performed during system startup, The firmware, loader program and the latest device driver code are available from Cyclades at + ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/ -
Documentation/serial/driver +88 -25
386 lines not on this page · raw message
Documentation/serial/moxa-smartio +421 -329
896 lines not on this page · raw message
Documentation/serial/n_gsm.txt +44 -37
109 lines not on this page · raw message
Documentation/serial/rocket.txt +70 -74
213 lines not on this page · raw message
Documentation/serial/serial-iso7816.txt +14 -7
@@ -1,11 +1,15 @@ - ISO7816 SERIAL COMMUNICATIONS +============================= +ISO7816 Serial Communications +============================= -1. INTRODUCTION +1. Introduction +=============== ISO/IEC7816 is a series of standards specifying integrated circuit cards (ICC) also known as smart cards. -2. HARDWARE-RELATED CONSIDERATIONS +2. Hardware-related considerations +================================== Some CPUs/UARTs (e.g., Microchip AT91) contain a built-in mode capable of handling communication with a smart card.
@@ -15,7 +19,8 @@ available at user-level to allow switching from one mode to the other, and vice versa. -3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL +3. Data Structures Already Available in the Kernel +================================================== The Linux kernel provides the serial_iso7816 structure (see [1]) to handle ISO7816 communications. This data structure is used to set and configure
@@ -27,10 +32,11 @@ to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config callback receives a pointer to struct serial_iso7816. -4. USAGE FROM USER-LEVEL +4. Usage from user-level +======================== From user-level, ISO7816 configuration can be get/set using the previous - ioctls. For instance, to set ISO7816 you can use the following code: + ioctls. For instance, to set ISO7816 you can use the following code:: #include <linux/serial.h>
@@ -78,6 +84,7 @@ /* Error handling. See errno. */ } -5. REFERENCES +5. References +============= [1] include/uapi/linux/serial.h
Documentation/serial/serial-rs485.txt +15 -7
@@ -1,6 +1,9 @@ - RS485 SERIAL COMMUNICATIONS +=========================== +RS485 Serial Communications +=========================== -1. INTRODUCTION +1. Introduction +=============== EIA-485, also known as TIA/EIA-485 or RS-485, is a standard defining the electrical characteristics of drivers and receivers for use in balanced
@@ -9,7 +12,8 @@ because it can be used effectively over long distances and in electrically noisy environments. -2. HARDWARE-RELATED CONSIDERATIONS +2. Hardware-related Considerations +================================== Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in half-duplex mode capable of automatically controlling line direction by
@@ -22,7 +26,8 @@ available at user-level to allow switching from one mode to the other, and vice versa. -3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL +3. Data Structures Already Available in the Kernel +================================================== The Linux kernel provides the serial_rs485 structure (see [1]) to handle RS485 communications. This data structure is used to set and configure RS485
@@ -38,10 +43,11 @@ to TIOCSRS485 and TIOCGRS485 ioctls (see below). The rs485_config callback receives a pointer to struct serial_rs485. -4. USAGE FROM USER-LEVEL +4. Usage from user-level +======================== From user-level, RS485 configuration can be get/set using the previous - ioctls. For instance, to set RS485 you can use the following code: + ioctls. For instance, to set RS485 you can use the following code:: #include <linux/serial.h>
@@ -89,7 +95,9 @@ /* Error handling. See errno. */ } -5. REFERENCES +5. References +============= [1] include/uapi/linux/serial.h + [2] Documentation/devicetree/bindings/serial/rs485.txt
Documentation/serial/tty.txt +63 -48
294 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 34/57 docs: target: convert it to ReST format
In reply to Mauro Carvalho ChehabConvert the TCM docs to ReST format and add them to the bookset.
This has a mix of userspace-faced and Kernelspace faced docs. Still, it sounds a better candidate to be added at the kernel API set of docs.
--- Documentation/target/tcm_mod_builder.txt | 200 ++++++++--------- Documentation/target/tcmu-design.txt | 268 ++++++++++++----------- 2 files changed, 248 insertions(+), 220 deletions(-)
Documentation/target/tcm_mod_builder.txt +102 -98
@@ -1,145 +1,149 @@ ->>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<< +========================================= +The TCM v4 fabric module script generator +========================================= Greetings all, This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py script to generate a brand new functional TCM v4 fabric .ko module of your very own, that once built can be immediately be loaded to start access the new TCM/ConfigFS -fabric skeleton, by simply using: +fabric skeleton, by simply using:: modprobe $TCM_NEW_MOD mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following - *) Generate new API callers for drivers/target/target_core_fabric_configs.c logic + 1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c - *) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module + 2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module using a skeleton struct target_core_fabric_ops API template. - *) Based on user defined T10 Proto_Ident for the new fabric module being built, + 3) Based on user defined T10 Proto_Ident for the new fabric module being built, the TransportID / Initiator and Target WWPN related handlers for SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c using drivers/target/target_core_fabric_lib.c logic. - *) NOP API calls for all other Data I/O path and fabric dependent attribute logic + 4) NOP API calls for all other Data I/O path and fabric dependent attribute logic in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m -$FABRIC_MOD_name' parameters, and actually running the script looks like: +$FABRIC_MOD_name' parameters, and actually running the script looks like:: -target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000 -tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../ -Set fabric_mod_name: tcm_nab5000 -Set fabric_mod_dir: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 -Using proto_ident: iSCSI -Creating fabric_mod_dir: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h -Using tcm_mod_scan_fabric_ops: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig -Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes -Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes + target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000 + tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../ + Set fabric_mod_name: tcm_nab5000 + Set fabric_mod_dir: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 + Using proto_ident: iSCSI + Creating fabric_mod_dir: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h + Using tcm_mod_scan_fabric_ops: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig + Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes + Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes At the end of tcm_mod_builder.py. the script will ask to add the following -line to drivers/target/Kbuild: +line to drivers/target/Kbuild:: obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/ -and the same for drivers/target/Kconfig: +and the same for drivers/target/Kconfig:: source "drivers/target/tcm_nab5000/Kconfig" -*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item: +#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:: <M> TCM_NAB5000 fabric module -*) Build using 'make modules', once completed you will have: +#) Build using 'make modules', once completed you will have:: -target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/ -total 1348 -drwxr-xr-x 2 root root 4096 2010-10-05 03:23 . -drwxr-xr-x 9 root root 4096 2010-10-05 03:22 .. --rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild --rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig --rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order --rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h --rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c --rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o --rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd --rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c --rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h --rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o --rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd --rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko --rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd --rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c --rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o --rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd --rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o --rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd + target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/ + total 1348 + drwxr-xr-x 2 root root 4096 2010-10-05 03:23 . + drwxr-xr-x 9 root root 4096 2010-10-05 03:22 .. + -rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild + -rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig + -rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order + -rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h + -rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c + -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o + -rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd + -rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c + -rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h + -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o + -rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd + -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko + -rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd + -rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c + -rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o + -rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd + -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o + -rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd -*) Load the new module, create a lun_0 configfs group, and add new TCM Core - IBLOCK backstore symlink to port: +#) Load the new module, create a lun_0 configfs group, and add new TCM Core + IBLOCK backstore symlink to port:: -target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko -target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0 -target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/ -target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port + target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko + target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0 + target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/ + target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port -target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd - -target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/ -/sys/kernel/config/target/nab5000/ -|-- discovery_auth -|-- iqn.foo -| `-- tpgt_1 -| |-- acls -| |-- attrib -| |-- lun -| | `-- lun_0 -| | |-- alua_tg_pt_gp -| | |-- alua_tg_pt_offline -| | |-- alua_tg_pt_status -| | |-- alua_tg_pt_write_md -| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0 -| |-- np -| `-- param -`-- version + target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd - + target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/ + /sys/kernel/config/target/nab5000/ + |-- discovery_auth + |-- iqn.foo + | `-- tpgt_1 + | |-- acls + | |-- attrib + | |-- lun + | | `-- lun_0 + | | |-- alua_tg_pt_gp + | | |-- alua_tg_pt_offline + | | |-- alua_tg_pt_status + | | |-- alua_tg_pt_write_md + | | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0 + | |-- np + | `-- param + `-- version -target:/mnt/sdb/lio-core-2.6.git# lsmod -Module Size Used by -tcm_nab5000 3935 4 -iscsi_target_mod 193211 0 -target_core_stgt 8090 0 -target_core_pscsi 11122 1 -target_core_file 9172 2 -target_core_iblock 9280 1 -target_core_mod 228575 31 -tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock -libfc 73681 0 -scsi_debug 56265 0 -scsi_tgt 8666 1 target_core_stgt -configfs 20644 2 target_core_mod + target:/mnt/sdb/lio-core-2.6.git# lsmod + Module Size Used by + tcm_nab5000 3935 4 + iscsi_target_mod 193211 0 + target_core_stgt 8090 0 + target_core_pscsi 11122 1 + target_core_file 9172 2 + target_core_iblock 9280 1 + target_core_mod 228575 31 + tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock + libfc 73681 0 + scsi_debug 56265 0 + scsi_tgt 8666 1 target_core_stgt + configfs 20644 2 target_core_mod ---------------------------------------------------------------------- -Future TODO items: +Future TODO items +================= - *) Add more T10 proto_idents - *) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer + 1) Add more T10 proto_idents + 2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops structure members. October 5th, 2010 + Nicholas A. Bellinger <[email protected]>
Documentation/target/tcmu-design.txt +146 -122
393 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH 35/57 docs: timers: convert documentation to ReST
In reply to Mauro Carvalho ChehabThe conversion here is really trivial: just a bunch of title markups and very few puntual changes is enough to make it to be parsed by Sphinx and generate a nice html.
--- Documentation/timers/NO_HZ.txt | 40 ++++++++++++++++----------- Documentation/timers/highres.txt | 11 ++++---- Documentation/timers/hpet.txt | 4 ++- Documentation/timers/hrtimers.txt | 6 ++-- Documentation/timers/timekeeping.txt | 3 +- Documentation/timers/timers-howto.txt | 15 +++++++--- 6 files changed, 49 insertions(+), 30 deletions(-)
Documentation/timers/NO_HZ.txt +24 -16
@@ -1,4 +1,6 @@ - NO_HZ: Reducing Scheduling-Clock Ticks +====================================== +NO_HZ: Reducing Scheduling-Clock Ticks +====================================== This document describes Kconfig options and boot parameters that can
@@ -28,7 +30,8 @@ by a third section on RCU-specific considerations, a fourth section discussing testing, and a fifth and final section listing known issues. -NEVER OMIT SCHEDULING-CLOCK TICKS +Never Omit Scheduling-Clock Ticks +================================= Very old versions of Linux from the 1990s and the very early 2000s are incapable of omitting scheduling-clock ticks. It turns out that
@@ -59,7 +62,8 @@ degrade your applications performance. If this describes your workload, you should read the following two sections. -OMIT SCHEDULING-CLOCK TICKS FOR IDLE CPUs +Omit Scheduling-Clock Ticks For Idle CPUs +========================================= If a CPU is idle, there is little point in sending it a scheduling-clock interrupt. After all, the primary purpose of a scheduling-clock interrupt
@@ -97,7 +101,8 @@ By default, CONFIG_NO_HZ_IDLE=y kernels boot with "nohz=on", enabling dyntick-idle mode. -OMIT SCHEDULING-CLOCK TICKS FOR CPUs WITH ONLY ONE RUNNABLE TASK +Omit Scheduling-Clock Ticks For CPUs With Only One Runnable Task +================================================================ If a CPU has only one runnable task, there is little point in sending it a scheduling-clock interrupt because there is no other task to switch to.
@@ -174,7 +179,8 @@ However, the drawbacks listed above mean that adaptive ticks should not (yet) be enabled by default. -RCU IMPLICATIONS +RCU Implications +================ There are situations in which idle CPUs cannot be permitted to enter either dyntick-idle mode or adaptive-tick mode, the most
@@ -199,7 +205,8 @@ scheduler will decide where to run them, which might or might not be where you want them to run. -TESTING +Testing +======= So you enable all the OS-jitter features described in this document, but do not see any change in your workload's behavior. Is this because
@@ -222,9 +229,10 @@ We do not currently have a good way to remove OS jitter from single-CPU systems. -KNOWN ISSUES +Known Issues +============ -o Dyntick-idle slows transitions to and from idle slightly. +* Dyntick-idle slows transitions to and from idle slightly. In practice, this has not been a problem except for the most aggressive real-time workloads, which have the option of disabling dyntick-idle mode, an option that most of them take. However,
@@ -248,13 +256,13 @@ o Dyntick-idle slows transitions to and from idle slightly. this parameter effectively disables Turbo Mode on Intel CPUs, which can significantly reduce maximum performance. -o Adaptive-ticks slows user/kernel transitions slightly. +* Adaptive-ticks slows user/kernel transitions slightly. This is not expected to be a problem for computationally intensive workloads, which have few such transitions. Careful benchmarking will be required to determine whether or not other workloads are significantly affected by this effect. -o Adaptive-ticks does not do anything unless there is only one +* Adaptive-ticks does not do anything unless there is only one runnable task for a given CPU, even though there are a number of other situations where the scheduling-clock tick is not needed. To give but one example, consider a CPU that has one
@@ -275,7 +283,7 @@ o Adaptive-ticks does not do anything unless there is only one Better handling of these sorts of situations is future work. -o A reboot is required to reconfigure both adaptive idle and RCU +* A reboot is required to reconfigure both adaptive idle and RCU callback offloading. Runtime reconfiguration could be provided if needed, however, due to the complexity of reconfiguring RCU at runtime, there would need to be an earthshakingly good reason.
@@ -283,12 +291,12 @@ o A reboot is required to reconfigure both adaptive idle and RCU simply offloading RCU callbacks from all CPUs and pinning them where you want them whenever you want them pinned. -o Additional configuration is required to deal with other sources +* Additional configuration is required to deal with other sources of OS jitter, including interrupts and system-utility tasks and processes. This configuration normally involves binding interrupts and tasks to particular CPUs. -o Some sources of OS jitter can currently be eliminated only by +* Some sources of OS jitter can currently be eliminated only by constraining the workload. For example, the only way to eliminate OS jitter due to global TLB shootdowns is to avoid the unmapping operations (such as kernel module unload operations) that
@@ -299,17 +307,17 @@ o Some sources of OS jitter can currently be eliminated only by helpful, especially when combined with the mlock() and mlockall() system calls. -o Unless all CPUs are idle, at least one CPU must keep the +* Unless all CPUs are idle, at least one CPU must keep the scheduling-clock interrupt going in order to support accurate timekeeping. -o If there might potentially be some adaptive-ticks CPUs, there +* If there might potentially be some adaptive-ticks CPUs, there will be at least one CPU keeping the scheduling-clock interrupt going, even if all CPUs are otherwise idle. Better handling of this situation is ongoing work. -o Some process-handling operations still require the occasional +* Some process-handling operations still require the occasional scheduling-clock tick. These operations include calculating CPU load, maintaining sched average, computing CFS entity vruntime, computing avenrun, and carrying out load balancing. They are
Documentation/timers/highres.txt +6 -5
@@ -1,5 +1,6 @@ +===================================================== High resolution timers and dynamic ticks design notes ------------------------------------------------------ +===================================================== Further information can be found in the paper of the OLS 2006 talk "hrtimers and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
@@ -35,6 +36,7 @@ also figure #2 (OLS slides p. 15) The main differences to the timer wheel, which holds the armed timer_list type timers are: + - time ordered enqueueing into a rb-tree - independent of ticks (the processing is based on nanoseconds)
@@ -55,7 +57,8 @@ merged into the 2.6.18 kernel. Further information about the Generic Time Of Day framework is available in the OLS 2005 Proceedings Volume 1: -http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf + + http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf The paper "We Are Not Getting Any Younger: A New Approach to Time and Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.
@@ -100,6 +103,7 @@ accounting, profiling, and high resolution timers. The management layer assigns one or more of the following functions to a clock event device: + - system global periodic tick (jiffies update) - cpu local update_process_times - cpu local profiling
@@ -244,6 +248,3 @@ extended to x86_64 and ARM already. Initial (work in progress) support is also available for MIPS and PowerPC. Thomas, Ingo - - -
Documentation/timers/hpet.txt +3 -1
@@ -1,4 +1,6 @@ - High Precision Event Timer Driver for Linux +=========================================== +High Precision Event Timer Driver for Linux +=========================================== The High Precision Event Timer (HPET) hardware follows a specification by Intel and Microsoft, revision 1.
Documentation/timers/hrtimers.txt +3 -3
@@ -1,6 +1,6 @@ - +====================================================== hrtimers - subsystem for high-resolution kernel timers ----------------------------------------------------- +====================================================== This patch introduces a new subsystem for high-resolution kernel timers.
@@ -146,7 +146,7 @@ the clock_getres() interface. This will return whatever real resolution a given clock has - be it low-res, high-res, or artificially-low-res. hrtimers - testing and verification ----------------------------------- +----------------------------------- We used the high-resolution clock subsystem ontop of hrtimers to verify the hrtimer implementation details in praxis, and we also ran the posix
Documentation/timers/timekeeping.txt +2 -1
@@ -1,5 +1,6 @@ +=========================================================== Clock sources, Clock events, sched_clock() and delay timers ------------------------------------------------------------ +=========================================================== This document tries to briefly explain some basic kernel timekeeping abstractions. It partly pertains to the drivers usually found in
Documentation/timers/timers-howto.txt +11 -4
@@ -1,5 +1,6 @@ +=================================================================== delays - Information on the various kernel delay / sleep mechanisms -------------------------------------------------------------------- +=================================================================== This document seeks to answer the common question: "What is the RightWay (TM) to insert a delay?"
@@ -17,7 +18,7 @@ code in an atomic context?" This should be followed closely by "Does it really need to delay in atomic context?" If so... ATOMIC CONTEXT: - You must use the *delay family of functions. These + You must use the `*delay` family of functions. These functions use the jiffie estimation of clock speed and will busy wait for enough loop cycles to achieve the desired delay:
@@ -35,21 +36,26 @@ ATOMIC CONTEXT: be refactored to allow for the use of msleep. NON-ATOMIC CONTEXT: - You should use the *sleep[_range] family of functions. + You should use the `*sleep[_range]` family of functions. There are a few more options here, while any of them may work correctly, using the "right" sleep function will help the scheduler, power management, and just make your driver better :) -- Backed by busy-wait loop: + udelay(unsigned long usecs) + -- Backed by hrtimers: + usleep_range(unsigned long min, unsigned long max) + -- Backed by jiffies / legacy_timers + msleep(unsigned long msecs) msleep_interruptible(unsigned long msecs) - Unlike the *delay family, the underlying mechanism + Unlike the `*delay` family, the underlying mechanism driving each of these calls varies, thus there are quirks you should be aware of.
@@ -70,6 +76,7 @@ NON-ATOMIC CONTEXT: - Why not msleep for (1ms - 20ms)? Explained originally here: http://lkml.org/lkml/2007/8/3/250 + msleep(1~20) may not do what the caller intends, and will often sleep longer (~20 ms actual sleep for any value given in the 1~20ms range). In many cases this
Signature · 1 line
2.20.1
PATCH 36/57 docs: usb: convert documents to ReST
In reply to Mauro Carvalho ChehabConvert USB documents to ReST, in order to prepare for adding it to the kernel API book, as most of the stuff there are driver or subsystem-related.
--- Documentation/usb/WUSB-Design-overview.txt | 56 +- Documentation/usb/acm.txt | 156 +++--- Documentation/usb/authorization.txt | 75 +-- Documentation/usb/chipidea.txt | 101 ++-- Documentation/usb/dwc3.txt | 12 +- Documentation/usb/ehci.txt | 42 +- Documentation/usb/functionfs.txt | 17 +- Documentation/usb/gadget-testing.txt | 609 ++++++++++++--------- Documentation/usb/gadget_configfs.txt | 302 +++++----- Documentation/usb/gadget_hid.txt | 175 +++--- Documentation/usb/gadget_multi.txt | 43 +- Documentation/usb/gadget_printer.txt | 155 +++--- Documentation/usb/gadget_serial.txt | 73 +-- Documentation/usb/iuu_phoenix.txt | 34 +- Documentation/usb/mass-storage.txt | 19 +- Documentation/usb/misc_usbsevseg.txt | 9 +- Documentation/usb/mtouchusb.txt | 42 +- Documentation/usb/ohci.txt | 5 +- Documentation/usb/rio.txt | 83 +-- Documentation/usb/usb-help.txt | 21 +- Documentation/usb/usb-serial.txt | 203 ++++--- Documentation/usb/usbip_protocol.txt | 552 ++++++++++--------- Documentation/usb/usbmon.txt | 100 ++-- 23 files changed, 1654 insertions(+), 1230 deletions(-)
Documentation/usb/WUSB-Design-overview.txt +37 -19
@@ -1,7 +1,9 @@ - +================================ Linux UWB + Wireless USB + WiNET +================================ + + Copyright (C) 2005-2006 Intel Corporation - (C) 2005-2006 Intel Corporation Inaky Perez-Gonzalez <[email protected]> This program is free software; you can redistribute it and/or
@@ -29,6 +31,7 @@ drivers for the USB based UWB radio controllers defined in the Wireless USB 1.0 specification (including Wireless USB host controller and an Intel WiNET controller). +.. Contents 1. Introduction 1. HWA: Host Wire adapters, your Wireless USB dongle
@@ -51,7 +54,8 @@ and an Intel WiNET controller). 4. Glossary - Introduction +Introduction +============ UWB is a wide-band communication protocol that is to serve also as the low-level protocol for others (much like TCP sits on IP). Currently
@@ -93,7 +97,8 @@ The different logical parts of this driver are: do the actual WUSB. - HWA: Host Wire adapters, your Wireless USB dongle +HWA: Host Wire adapters, your Wireless USB dongle +------------------------------------------------- WUSB also defines a device called a Host Wire Adaptor (HWA), which in mere terms is a USB dongle that enables your PC to have UWB and Wireless
@@ -125,7 +130,8 @@ The HWA itself is broken in two or three main interfaces: their type and kick into gear. - DWA: Device Wired Adaptor, a Wireless USB hub for wired devices +DWA: Device Wired Adaptor, a Wireless USB hub for wired devices +--------------------------------------------------------------- These are the complement to HWAs. They are a USB host for connecting wired devices, but it is connected to your PC connected via Wireless
@@ -137,7 +143,8 @@ code with the HWA-RC driver; there is a bunch of factorization work that has been done to support that in upcoming releases. - WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter +WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter +------------------------------------------------------------------- This is your usual PCI device that implements WHCI. Similar in concept to EHCI, it allows your wireless USB devices (including DWAs) to connect
@@ -148,7 +155,8 @@ There is still no driver support for this, but will be in upcoming releases. - The UWB stack +The UWB stack +============= The main mission of the UWB stack is to keep a tally of which devices are in radio proximity to allow drivers to connect to them. As well, it
@@ -156,7 +164,8 @@ provides an API for controlling the local radio controllers (RCs from now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. - Devices and hosts: the basic structure +Devices and hosts: the basic structure +-------------------------------------- The main building block here is the UWB device (struct uwb_dev). For each device that pops up in radio presence (ie: the UWB host receives a
@@ -187,7 +196,8 @@ the USB connected HWA. Eventually, drivers/whci-rc.c will do the same for the PCI connected WHCI controller. - Host Controller life cycle +Host Controller life cycle +-------------------------- So let's say we connect a dongle to the system: it is detected and firmware uploaded if needed [for Intel's i1480
@@ -209,7 +219,8 @@ When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ takes time of tearing everything down safely (or not...). - On the air: beacons and enumerating the radio neighborhood +On the air: beacons and enumerating the radio neighborhood +---------------------------------------------------------- So assuming we have devices and we have agreed for a channel to connect on (let's say 9), we put the new RC to beacon:
@@ -235,12 +246,14 @@ are received in some time, the device is considered gone and wiped out the beacon cache of dead devices]. - Device lists +Device lists +------------ All UWB devices are kept in the list of the struct bus_type uwb_bus_type. - Bandwidth allocation +Bandwidth allocation +-------------------- The UWB stack maintains a local copy of DRP availability through processing of incoming *DRP Availability Change* notifications. This
@@ -260,7 +273,8 @@ completion. [Note: The bandwidth reservation work is in progress and subject to change.] - Wireless USB Host Controller drivers +Wireless USB Host Controller drivers +==================================== *WARNING* This section needs a lot of work!
@@ -296,7 +310,8 @@ starts sending MMCs. Now it all depends on external stimuli. -*New device connection* +New device connection +--------------------- A new device pops up, it scans the radio looking for MMCs that give out the existence of Wireless USB channels. Once one (or more) are found,
@@ -322,7 +337,8 @@ has seen the port status changes, as we have been toggling them. It will start enumerating and doing transfers through usb_hcd->urb_enqueue() to read descriptors and move our data. -*Device life cycle and keep alives* +Device life cycle and keep alives +--------------------------------- Every time there is a successful transfer to/from a device, we update a per-device activity timestamp. If not, every now and then we check and
@@ -340,7 +356,8 @@ device list looking for whom needs refreshing. If the device wants to disconnect, it will either die (ugly) or send a /DN_Disconnect/ that will prompt a disconnection from the system. -*Sending and receiving data* +Sending and receiving data +-------------------------- Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is /aimed/ at an endpoint in a WUSB device. This is the same for HWAs and
@@ -394,7 +411,8 @@ finalize the transfer. For IN xfers, we only issue URBs for the segments we want to read and then wait for the xfer result data. -*URB mapping into xfers* +URB mapping into xfers +^^^^^^^^^^^^^^^^^^^^^^ This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an rpipe to the endpoint where we have to transmit, create a transfer
@@ -407,7 +425,8 @@ and not yet done and when all that is done, the xfer callback will be called--this will call the URB callback. - Glossary +Glossary +======== *DWA* -- Device Wire Adapter
@@ -436,4 +455,3 @@ the host. Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by InakyPerezGonzalez) -
Documentation/usb/acm.txt +80 -76
207 lines not on this page · raw message
Documentation/usb/authorization.txt +41 -34
140 lines not on this page · raw message
Documentation/usb/chipidea.txt +69 -32
155 lines not on this page · raw message
Documentation/usb/dwc3.txt +10 -2
@@ -1,6 +1,11 @@ +=========== +DWC3 driver +=========== + + +TODO +~~~~ - TODO -~~~~~~ Please pick something while reading :) - Convert interrupt handler to per-ep-thread-irq
@@ -9,6 +14,7 @@ Please pick something while reading :) until the command completes which is bad. Implementation idea: + - dwc core implements a demultiplexing irq chip for interrupts per endpoint. The interrupt numbers are allocated during probe and belong to the device. If MSI provides per-endpoint interrupt this dummy
@@ -19,6 +25,7 @@ Please pick something while reading :) - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout() until the command completes. - the interrupt handler is split into the following pieces: + - primary handler of the device goes through every event and calls generic_handle_irq() for event it. On return from generic_handle_irq() in acknowledges the event
@@ -40,6 +47,7 @@ Please pick something while reading :) for command completion. Latency: + There should be no increase in latency since the interrupt-thread has a high priority and will be run before an average task in user land (except the user changed priorities).
Documentation/usb/ehci.txt +29 -13
106 lines not on this page · raw message
Documentation/usb/functionfs.txt +9 -8
@@ -1,4 +1,6 @@ -*How FunctionFS works* +==================== +How FunctionFS works +==================== From kernel point of view it is just a composite function with some unique behaviour. It may be added to an USB configuration only after
@@ -38,13 +40,13 @@ when mounting. One can imagine a gadget that has an Ethernet, MTP and HID interfaces where the last two are implemented via FunctionFS. On user space -level it would look like this: +level it would look like this:: -$ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid -$ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp -$ ( cd /dev/ffs-mtp && mtp-daemon ) & -$ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid -$ ( cd /dev/ffs-hid && hid-daemon ) & + $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid + $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp + $ ( cd /dev/ffs-mtp && mtp-daemon ) & + $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid + $ ( cd /dev/ffs-hid && hid-daemon ) & On kernel level the gadget checks ffs_data->dev_name to identify whether it's FunctionFS designed for MTP ("mtp") or HID ("hid").
@@ -64,4 +66,3 @@ have been written to their ep0's. Conversely, the gadget is unregistered after the first USB function closes its endpoints. -
Documentation/usb/gadget-testing.txt +362 -247
950 lines not on this page · raw message
Documentation/usb/gadget_configfs.txt +154 -148
444 lines not on this page · raw message
Documentation/usb/gadget_hid.txt +90 -85
282 lines not on this page · raw message
Documentation/usb/gadget_multi.txt +29 -14
112 lines not on this page · raw message
Documentation/usb/gadget_printer.txt +84 -71
318 lines not on this page · raw message
Documentation/usb/gadget_serial.txt +38 -35
58 lines not on this page · raw message
Documentation/usb/mtouchusb.txt +27 -15
42 lines not on this page · raw message
Documentation/usb/rio.txt +47 -36
83 lines not on this page · raw message
Documentation/usb/usb-serial.txt +127 -76
203 lines not on this page · raw message
Documentation/usb/usbip_protocol.txt +303 -249
552 lines not on this page · raw message
Documentation/usb/usbmon.txt +60 -40
100 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Part of the diff is not shown here. View the raw message.
Re: [PATCH 36/57] docs: usb: convert documents to ReST
Quoted 21 lines · Mauro Carvalho Chehab
Convert USB documents to ReST, in order to prepare for adding it to the kernel API book, as most of the stuff there are driver or subsystem-related.
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/usb/WUSB-Design-overview.txt | 56 +- Documentation/usb/acm.txt | 156 +++--- Documentation/usb/authorization.txt | 75 +-- Documentation/usb/chipidea.txt | 101 ++-- Documentation/usb/dwc3.txt | 12 +- Documentation/usb/ehci.txt | 42 +- Documentation/usb/functionfs.txt | 17 +- Documentation/usb/gadget-testing.txt | 609 ++++++++++++--------- Documentation/usb/gadget_configfs.txt | 302 +++++----- Documentation/usb/gadget_hid.txt | 175 +++--- Documentation/usb/gadget_multi.txt | 43 +- Documentation/usb/gadget_printer.txt | 155 +++--- Documentation/usb/gadget_serial.txt | 73 +-- Documentation/usb/iuu_phoenix.txt | 34 +- Documentation/usb/mass-storage.txt | 19 +-
Quoted 8 lines
Documentation/usb/misc_usbsevseg.txt | 9 +- Documentation/usb/mtouchusb.txt | 42 +- Documentation/usb/ohci.txt | 5 +- Documentation/usb/rio.txt | 83 +-- Documentation/usb/usb-help.txt | 21 +- Documentation/usb/usb-serial.txt | 203 ++++--- Documentation/usb/usbip_protocol.txt | 552 ++++++++++--------- Documentation/usb/usbmon.txt | 100 ++--
should you change extension to .rst while at that?
Re: [PATCH 36/57] docs: usb: convert documents to ReST
Em Tue, 16 Apr 2019 09:12:32 +0300
Felipe Balbi <[email protected]> escreveu:
Quoted 32 lines
Quoted 21 lines · Mauro Carvalho Chehab
Convert USB documents to ReST, in order to prepare for adding it to the kernel API book, as most of the stuff there are driver or subsystem-related.
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/usb/WUSB-Design-overview.txt | 56 +- Documentation/usb/acm.txt | 156 +++--- Documentation/usb/authorization.txt | 75 +-- Documentation/usb/chipidea.txt | 101 ++-- Documentation/usb/dwc3.txt | 12 +- Documentation/usb/ehci.txt | 42 +- Documentation/usb/functionfs.txt | 17 +- Documentation/usb/gadget-testing.txt | 609 ++++++++++++--------- Documentation/usb/gadget_configfs.txt | 302 +++++----- Documentation/usb/gadget_hid.txt | 175 +++--- Documentation/usb/gadget_multi.txt | 43 +- Documentation/usb/gadget_printer.txt | 155 +++--- Documentation/usb/gadget_serial.txt | 73 +-- Documentation/usb/iuu_phoenix.txt | 34 +- Documentation/usb/mass-storage.txt | 19 +-Quoted 8 lines
Documentation/usb/misc_usbsevseg.txt | 9 +- Documentation/usb/mtouchusb.txt | 42 +- Documentation/usb/ohci.txt | 5 +- Documentation/usb/rio.txt | 83 +-- Documentation/usb/usb-help.txt | 21 +- Documentation/usb/usb-serial.txt | 203 ++++--- Documentation/usb/usbip_protocol.txt | 552 ++++++++++--------- Documentation/usb/usbmon.txt | 100 ++--
Quoted 1 line
should you change extension to .rst while at that?
I did that on a first version (not submitted):
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=all_with_indexes&id=d7eec4678dbfeb1a40c58bca7a157c8a4c39fa04
but I opted do the postpone the rename to a new series yet to be sent.
The problem is that renaming it will make Sphinx to try to build them, causing lots of warnings because they won't be inside an index file. Adding index would touch Documentation/index (or Documentation/drivers-api), with would cause merge conflicts.
Once this patch gets merged upstream, a renaming patch can happen anytime. It probably makes sense to do all renames at once, late at a merge window.
Thanks,
Mauro
PATCH 37/57 docs: watchdog: convert documents to ReST format
In reply to Mauro Carvalho ChehabConvert those documents and prepare them to be part of the kernel API book, as most of the stuff there are related to the Kernel interfaces.
Still, in the future, it would make sense to split the docs, as some of the stuff is clearly focused on sysadmin tasks.
--- .../convert_drivers_to_kernel_api.txt | 109 +-- Documentation/watchdog/hpwdt.txt | 23 +- Documentation/watchdog/mlx-wdt.txt | 24 +- Documentation/watchdog/pcwd-watchdog.txt | 13 +- Documentation/watchdog/watchdog-api.txt | 76 +- .../watchdog/watchdog-kernel-api.txt | 89 ++- .../watchdog/watchdog-parameters.txt | 672 +++++++++++++----- Documentation/watchdog/watchdog-pm.txt | 3 + Documentation/watchdog/wdt.txt | 31 +- 9 files changed, 733 insertions(+), 307 deletions(-)
Documentation/watchdog/convert_drivers_to_kernel_api.txt +55 -54
@@ -1,6 +1,8 @@ +========================================================= Converting old watchdog drivers to the watchdog framework +========================================================= + by Wolfram Sang <[email protected]> -========================================================= Before the watchdog framework came into the kernel, every driver had to implement the API on its own. Now, as the framework factored out the common
@@ -69,16 +71,16 @@ Here is a overview of the functions and probably needed actions: -ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error is directly given to the user. -Example conversion: +Example conversion:: --static const struct file_operations s3c2410wdt_fops = { -- .owner = THIS_MODULE, -- .llseek = no_llseek, -- .write = s3c2410wdt_write, -- .unlocked_ioctl = s3c2410wdt_ioctl, -- .open = s3c2410wdt_open, -- .release = s3c2410wdt_release, --}; + -static const struct file_operations s3c2410wdt_fops = { + - .owner = THIS_MODULE, + - .llseek = no_llseek, + - .write = s3c2410wdt_write, + - .unlocked_ioctl = s3c2410wdt_ioctl, + - .open = s3c2410wdt_open, + - .release = s3c2410wdt_release, + -}; Check the functions for device-specific stuff and keep it for later refactoring. The rest can go.
@@ -89,24 +91,24 @@ Remove the miscdevice Since the file_operations are gone now, you can also remove the 'struct miscdevice'. The framework will create it on watchdog_dev_register() called by -watchdog_register_device(). +watchdog_register_device():: --static struct miscdevice s3c2410wdt_miscdev = { -- .minor = WATCHDOG_MINOR, -- .name = "watchdog", -- .fops = &s3c2410wdt_fops, --}; + -static struct miscdevice s3c2410wdt_miscdev = { + - .minor = WATCHDOG_MINOR, + - .name = "watchdog", + - .fops = &s3c2410wdt_fops, + -}; Remove obsolete includes and defines ------------------------------------ Because of the simplifications, a few defines are probably unused now. Remove -them. Includes can be removed, too. For example: +them. Includes can be removed, too. For example:: -- #include <linux/fs.h> -- #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used) -- #include <linux/uaccess.h> (if no custom IOCTLs are used) + - #include <linux/fs.h> + - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used) + - #include <linux/uaccess.h> (if no custom IOCTLs are used) Add the watchdog operations
@@ -121,30 +123,30 @@ change the function header. Other changes are most likely not needed, because here simply happens the direct hardware access. If you have device-specific code left from the above steps, it should be refactored into these callbacks. -Here is a simple example: +Here is a simple example:: -+static struct watchdog_ops s3c2410wdt_ops = { -+ .owner = THIS_MODULE, -+ .start = s3c2410wdt_start, -+ .stop = s3c2410wdt_stop, -+ .ping = s3c2410wdt_keepalive, -+ .set_timeout = s3c2410wdt_set_heartbeat, -+}; + +static struct watchdog_ops s3c2410wdt_ops = { + + .owner = THIS_MODULE, + + .start = s3c2410wdt_start, + + .stop = s3c2410wdt_stop, + + .ping = s3c2410wdt_keepalive, + + .set_timeout = s3c2410wdt_set_heartbeat, + +}; -A typical function-header change looks like: +A typical function-header change looks like:: --static void s3c2410wdt_keepalive(void) -+static int s3c2410wdt_keepalive(struct watchdog_device *wdd) - { -... -+ -+ return 0; - } + -static void s3c2410wdt_keepalive(void) + +static int s3c2410wdt_keepalive(struct watchdog_device *wdd) + { + ... + + + + return 0; + } -... + ... -- s3c2410wdt_keepalive(); -+ s3c2410wdt_keepalive(&s3c2410_wdd); + - s3c2410wdt_keepalive(); + + s3c2410wdt_keepalive(&s3c2410_wdd); Add the watchdog device
@@ -159,12 +161,12 @@ static variables. Those have to be converted to use the members in watchdog_device. Note that the timeout values are unsigned int. Some drivers use signed int, so this has to be converted, too. -Here is a simple example for a watchdog device: +Here is a simple example for a watchdog device:: -+static struct watchdog_device s3c2410_wdd = { -+ .info = &s3c2410_wdt_ident, -+ .ops = &s3c2410wdt_ops, -+}; + +static struct watchdog_device s3c2410_wdd = { + + .info = &s3c2410_wdt_ident, + + .ops = &s3c2410wdt_ops, + +}; Handle the 'nowayout' feature
@@ -173,12 +175,12 @@ Handle the 'nowayout' feature A few drivers use nowayout statically, i.e. there is no module parameter for it and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be used. This needs to be converted by initializing the status variable of the -watchdog_device like this: +watchdog_device like this:: .status = WATCHDOG_NOWAYOUT_INIT_STATUS, Most drivers, however, also allow runtime configuration of nowayout, usually -by adding a module parameter. The conversion for this would be something like: +by adding a module parameter. The conversion for this would be something like:: watchdog_set_nowayout(&s3c2410_wdd, nowayout);
@@ -191,15 +193,15 @@ Register the watchdog device Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev). Make sure the return value gets checked and the error message, if present, -still fits. Also convert the unregister case. +still fits. Also convert the unregister case:: -- ret = misc_register(&s3c2410wdt_miscdev); -+ ret = watchdog_register_device(&s3c2410_wdd); + - ret = misc_register(&s3c2410wdt_miscdev); + + ret = watchdog_register_device(&s3c2410_wdd); -... + ... -- misc_deregister(&s3c2410wdt_miscdev); -+ watchdog_unregister_device(&s3c2410_wdd); + - misc_deregister(&s3c2410wdt_miscdev); + + watchdog_unregister_device(&s3c2410_wdd); Update the Kconfig-entry
@@ -207,7 +209,7 @@ Update the Kconfig-entry The entry for the driver now needs to select WATCHDOG_CORE: -+ select WATCHDOG_CORE + + select WATCHDOG_CORE Create a patch and send it to upstream
@@ -215,4 +217,3 @@ Create a patch and send it to upstream Make sure you understood Documentation/process/submitting-patches.rst and send your patch to [email protected]. We are looking forward to it :) -
Documentation/watchdog/hpwdt.txt +15 -8
@@ -1,7 +1,12 @@ +=========================== +HPE iLO NMI Watchdog Driver +=========================== + +for iLO based ProLiant Servers +============================== + Last reviewed: 08/20/2018 - HPE iLO NMI Watchdog Driver - for iLO based ProLiant Servers The HPE iLO NMI Watchdog driver is a kernel module that provides basic watchdog functionality and handler for the iLO "Generate NMI to System"
@@ -20,21 +25,24 @@ Last reviewed: 08/20/2018 The hpwdt driver also has the following module parameters: - soft_margin - allows the user to set the watchdog timer value. + ============ ================================================================ + soft_margin allows the user to set the watchdog timer value. Default value is 30 seconds. - timeout - an alias of soft_margin. - pretimeout - allows the user to set the watchdog pretimeout value. + timeout an alias of soft_margin. + pretimeout allows the user to set the watchdog pretimeout value. This is the number of seconds before timeout when an NMI is delivered to the system. Setting the value to zero disables the pretimeout NMI. Default value is 9 seconds. - nowayout - basic watchdog parameter that does not allow the timer to + nowayout basic watchdog parameter that does not allow the timer to be restarted or an impending ASR to be escaped. Default value is set when compiling the kernel. If it is set to "Y", then there is no way of disabling the watchdog once it has been started. + ============ ================================================================ - NOTE: More information about watchdog drivers in general, including the ioctl + NOTE: + More information about watchdog drivers in general, including the ioctl interface to /dev/watchdog can be found in Documentation/watchdog/watchdog-api.txt and Documentation/IPMI.txt.
@@ -63,4 +71,3 @@ Last reviewed: 08/20/2018 The HPE iLO NMI Watchdog Driver and documentation were originally developed by Tom Mingarelli. -
Documentation/watchdog/mlx-wdt.txt +14 -10
@@ -1,5 +1,9 @@ - Mellanox watchdog drivers - for x86 based system switches +========================= +Mellanox watchdog drivers +========================= + +for x86 based system switches +============================= This driver provides watchdog functionality for various Mellanox Ethernet and Infiniband switch systems.
@@ -9,16 +13,16 @@ Mellanox watchdog device is implemented in a programmable logic device. There are 2 types of HW watchdog implementations. Type 1: -Actual HW timeout can be defined as a power of 2 msec. -e.g. timeout 20 sec will be rounded up to 32768 msec. -The maximum timeout period is 32 sec (32768 msec.), -Get time-left isn't supported + Actual HW timeout can be defined as a power of 2 msec. + e.g. timeout 20 sec will be rounded up to 32768 msec. + The maximum timeout period is 32 sec (32768 msec.), + Get time-left isn't supported Type 2: -Actual HW timeout is defined in sec. and it's the same as -a user-defined timeout. -Maximum timeout is 255 sec. -Get time-left is supported. + Actual HW timeout is defined in sec. and it's the same as + a user-defined timeout. + Maximum timeout is 255 sec. + Get time-left is supported. Type 1 HW watchdog implementation exist in old systems and all new systems have type 2 HW watchdog.
Documentation/watchdog/pcwd-watchdog.txt +9 -4
@@ -1,8 +1,13 @@ +=================================== +Berkshire Products PC Watchdog Card +=================================== + Last reviewed: 10/05/2007 - Berkshire Products PC Watchdog Card - Support for ISA Cards Revision A and C - Documentation and Driver by Ken Hollis <[email protected]> +Support for ISA Cards Revision A and C +======================================= + +Documentation and Driver by Ken Hollis <[email protected]> The PC Watchdog is a card that offers the same type of functionality that the WDT card does, only it doesn't require an IRQ to run. Furthermore,
@@ -33,6 +38,7 @@ Last reviewed: 10/05/2007 WDIOC_GETSUPPORT This returns the support of the card itself. This returns in structure "PCWDS" which returns: + options = WDIOS_TEMPPANIC (This card supports temperature) firmware_version = xxxx
@@ -63,4 +69,3 @@ Last reviewed: 10/05/2007 -- Ken Hollis ([email protected]) -
Documentation/watchdog/watchdog-api.txt +55 -21
240 lines not on this page · raw message
Documentation/watchdog/watchdog-kernel-api.txt +61 -28
248 lines not on this page · raw message
Documentation/watchdog/watchdog-parameters.txt +499 -173
909 lines not on this page · raw message
Documentation/watchdog/watchdog-pm.txt +3 -0
@@ -1,5 +1,7 @@ +=============================================== The Linux WatchDog Timer Power Management Guide =============================================== + Last reviewed: 17-Dec-2018 Wolfram Sang <[email protected]>
@@ -16,4 +18,5 @@ On resume, a watchdog timer shall be reset to its selected value to give userspace enough time to resume. [1] [2] [1] https://patchwork.kernel.org/patch/10252209/ + [2] https://patchwork.kernel.org/patch/10711625/
Documentation/watchdog/wdt.txt +22 -9
@@ -1,11 +1,14 @@ +============================================================ +WDT Watchdog Timer Interfaces For The Linux Operating System +============================================================ + Last Reviewed: 10/05/2007 - WDT Watchdog Timer Interfaces For The Linux Operating System - Alan Cox <[email protected]> +Alan Cox <[email protected]> - ICS WDT501-P - ICS WDT501-P (no fan tachometer) - ICS WDT500-P + - ICS WDT501-P + - ICS WDT501-P (no fan tachometer) + - ICS WDT500-P All the interfaces provide /dev/watchdog, which when open must be written to within a timeout or the machine will reboot. Each write delays the reboot
@@ -21,19 +24,26 @@ degrees Fahrenheit. Each read returns a single byte giving the temperature. The third interface logs kernel messages on additional alert events. The ICS ISA-bus wdt card cannot be safely probed for. Instead you need to -pass IO address and IRQ boot parameters. E.g.: +pass IO address and IRQ boot parameters. E.g.:: + wdt.io=0x240 wdt.irq=11 Other "wdt" driver parameters are: + + =========== ====================================================== heartbeat Watchdog heartbeat in seconds (default 60) nowayout Watchdog cannot be stopped once started (kernel - build parameter) + build parameter) tachometer WDT501-P Fan Tachometer support (0=disable, default=0) type WDT501-P Card type (500 or 501, default=500) + =========== ====================================================== Features -------- - WDT501P WDT500P + +================ ======= ======= + WDT501P WDT500P +================ ======= ======= Reboot Timer X X External Reboot X X I/O Port Monitor o o
@@ -42,9 +52,12 @@ Fan Speed X o Power Under X o Power Over X o Overheat X o +================ ======= ======= The external event interfaces on the WDT boards are not currently supported. Minor numbers are however allocated for it. -Example Watchdog Driver: see samples/watchdog/watchdog-simple.c +Example Watchdog Driver: + + see samples/watchdog/watchdog-simple.c
Signature · 1 line
2.20.1