diff options
Diffstat (limited to 'Documentation')
191 files changed, 5108 insertions, 2285 deletions
diff --git a/Documentation/.renames.txt b/Documentation/.renames.txt new file mode 100644 index 000000000000..c0bd5d3dc8b9 --- /dev/null +++ b/Documentation/.renames.txt @@ -0,0 +1,1191 @@ +80211/cfg80211 driver-api/80211/cfg80211 +80211/index driver-api/80211/index +80211/introduction driver-api/80211/introduction +80211/mac80211 driver-api/80211/mac80211 +80211/mac80211-advanced driver-api/80211/mac80211-advanced +EDID/howto admin-guide/edid +PCI/picebus-howto PCI/pciebus-howto +RAS/address-translation admin-guide/RAS/address-translation +RAS/error-decoding admin-guide/RAS/error-decoding +RAS/ras admin-guide/RAS/error-decoding +accelerators/ocxl userspace-api/accelerators/ocxl +admin-guide/gpio/sysfs userspace-api/gpio/sysfs +admin-guide/l1tf admin-guide/hw-vuln/l1tf +admin-guide/media/v4l-with-ir admin-guide/media/remote-controller +admin-guide/ras admin-guide/RAS/main +admin-guide/security-bugs process/security-bugs +aoe/aoe admin-guide/aoe/aoe +aoe/examples admin-guide/aoe/examples +aoe/index admin-guide/aoe/index +aoe/todo admin-guide/aoe/todo +arc/arc arch/arc/arc +arc/features arch/arc/features +arc/index arch/arc/index +arch/x86/resctrl filesystems/resctrl +arm/arm arch/arm/arm +arm/booting arch/arm/booting +arm/cluster-pm-race-avoidance arch/arm/cluster-pm-race-avoidance +arm/features arch/arm/features +arm/firmware arch/arm/firmware +arm/google/chromebook-boot-flow arch/arm/google/chromebook-boot-flow +arm/index arch/arm/index +arm/interrupts arch/arm/interrupts +arm/ixp4xx arch/arm/ixp4xx +arm/kernel_mode_neon arch/arm/kernel_mode_neon +arm/kernel_user_helpers arch/arm/kernel_user_helpers +arm/keystone/knav-qmss arch/arm/keystone/knav-qmss +arm/keystone/overview arch/arm/keystone/overview +arm/marvel arch/arm/marvell +arm/marvell arch/arm/marvell +arm/mem_alignment arch/arm/mem_alignment +arm/memory arch/arm/memory +arm/microchip arch/arm/microchip +arm/netwinder arch/arm/netwinder +arm/nwfpe/index arch/arm/nwfpe/index +arm/nwfpe/netwinder-fpe arch/arm/nwfpe/netwinder-fpe +arm/nwfpe/notes arch/arm/nwfpe/notes +arm/nwfpe/nwfpe arch/arm/nwfpe/nwfpe +arm/nwfpe/todo arch/arm/nwfpe/todo +arm/omap/dss arch/arm/omap/dss +arm/omap/index arch/arm/omap/index +arm/omap/omap arch/arm/omap/omap +arm/omap/omap_pm arch/arm/omap/omap_pm +arm/porting arch/arm/porting +arm/pxa/mfp arch/arm/pxa/mfp +arm/sa1100/assabet arch/arm/sa1100/assabet +arm/sa1100/cerf arch/arm/sa1100/cerf +arm/sa1100/index arch/arm/sa1100/index +arm/sa1100/lart arch/arm/sa1100/lart +arm/sa1100/serial_uart arch/arm/sa1100/serial_uart +arm/samsung/bootloader-interface arch/arm/samsung/bootloader-interface +arm/samsung/gpio arch/arm/samsung/gpio +arm/samsung/index arch/arm/samsung/index +arm/samsung/overview arch/arm/samsung/overview +arm/setup arch/arm/setup +arm/spear/overview arch/arm/spear/overview +arm/sti/overview arch/arm/sti/overview +arm/sti/stih407-overview arch/arm/sti/stih407-overview +arm/sti/stih418-overview arch/arm/sti/stih418-overview +arm/stm32/overview arch/arm/stm32/overview +arm/stm32/stm32-dma-mdma-chaining arch/arm/stm32/stm32-dma-mdma-chaining +arm/stm32/stm32f429-overview arch/arm/stm32/stm32f429-overview +arm/stm32/stm32f746-overview arch/arm/stm32/stm32f746-overview +arm/stm32/stm32f769-overview arch/arm/stm32/stm32f769-overview +arm/stm32/stm32h743-overview arch/arm/stm32/stm32h743-overview +arm/stm32/stm32h750-overview arch/arm/stm32/stm32h750-overview +arm/stm32/stm32mp13-overview arch/arm/stm32/stm32mp13-overview +arm/stm32/stm32mp151-overview arch/arm/stm32/stm32mp151-overview +arm/stm32/stm32mp157-overview arch/arm/stm32/stm32mp157-overview +arm/sunxi arch/arm/sunxi +arm/sunxi/clocks arch/arm/sunxi/clocks +arm/swp_emulation arch/arm/swp_emulation +arm/tcm arch/arm/tcm +arm/uefi arch/arm/uefi +arm/vfp/release-notes arch/arm/vfp/release-notes +arm/vlocks arch/arm/vlocks +arm64/acpi_object_usage arch/arm64/acpi_object_usage +arm64/amu arch/arm64/amu +arm64/arm-acpi arch/arm64/arm-acpi +arm64/asymmetric-32bit arch/arm64/asymmetric-32bit +arm64/booting arch/arm64/booting +arm64/cpu-feature-registers arch/arm64/cpu-feature-registers +arm64/elf_hwcaps arch/arm64/elf_hwcaps +arm64/features arch/arm64/features +arm64/hugetlbpage arch/arm64/hugetlbpage +arm64/index arch/arm64/index +arm64/legacy_instructions arch/arm64/legacy_instructions +arm64/memory arch/arm64/memory +arm64/memory-tagging-extension arch/arm64/memory-tagging-extension +arm64/perf arch/arm64/perf +arm64/pointer-authentication arch/arm64/pointer-authentication +arm64/silicon-errata arch/arm64/silicon-errata +arm64/sme arch/arm64/sme +arm64/sve arch/arm64/sve +arm64/tagged-address-abi arch/arm64/tagged-address-abi +arm64/tagged-pointers arch/arm64/tagged-pointers +asm-annotations core-api/asm-annotations +auxdisplay/lcd-panel-cgram admin-guide/lcd-panel-cgram +backlight/lp855x-driver driver-api/backlight/lp855x-driver +blockdev/drbd/data-structure-v9 admin-guide/blockdev/drbd/data-structure-v9 +blockdev/drbd/figures admin-guide/blockdev/drbd/figures +blockdev/drbd/index admin-guide/blockdev/drbd/index +blockdev/floppy admin-guide/blockdev/floppy +blockdev/index admin-guide/blockdev/index +blockdev/nbd admin-guide/blockdev/nbd +blockdev/paride admin-guide/blockdev/paride +blockdev/ramdisk admin-guide/blockdev/ramdisk +blockdev/zram admin-guide/blockdev/zram +bpf/README bpf/index +bpf/bpf_lsm bpf/prog_lsm +bpf/instruction-set bpf/standardization/instruction-set +bpf/libbpf/libbpf bpf/libbpf/index +bpf/standardization/linux-notes bpf/linux-notes +bus-devices/ti-gpmc driver-api/memory-devices/ti-gpmc +cgroup-v1/blkio-controller admin-guide/cgroup-v1/blkio-controller +cgroup-v1/cgroups admin-guide/cgroup-v1/cgroups +cgroup-v1/cpuacct admin-guide/cgroup-v1/cpuacct +cgroup-v1/cpusets admin-guide/cgroup-v1/cpusets +cgroup-v1/devices admin-guide/cgroup-v1/devices +cgroup-v1/freezer-subsystem admin-guide/cgroup-v1/freezer-subsystem +cgroup-v1/hugetlb admin-guide/cgroup-v1/hugetlb +cgroup-v1/index admin-guide/cgroup-v1/index +cgroup-v1/memcg_test admin-guide/cgroup-v1/memcg_test +cgroup-v1/memory admin-guide/cgroup-v1/memory +cgroup-v1/net_cls admin-guide/cgroup-v1/net_cls +cgroup-v1/net_prio admin-guide/cgroup-v1/net_prio +cgroup-v1/pids admin-guide/cgroup-v1/pids +cgroup-v1/rdma admin-guide/cgroup-v1/rdma +cma/debugfs admin-guide/mm/cma_debugfs +connector/connector driver-api/connector +console/console driver-api/console +core-api/gcc-plugins kbuild/gcc-plugins +core-api/ioctl driver-api/ioctl +core-api/memory-hotplug-notifier core-api/memory-hotplug +dev-tools/gdb-kernel-debugging process/debugging/gdb-kernel-debugging +dev-tools/kgdb process/debugging/kgdb +dev-tools/tools dev-tools/index +development-process/1.Intro process/1.Intro +development-process/2.Process process/2.Process +development-process/3.Early-stage process/3.Early-stage +development-process/4.Coding process/4.Coding +development-process/5.Posting process/5.Posting +development-process/6.Followthrough process/6.Followthrough +development-process/7.AdvancedTopics process/7.AdvancedTopics +development-process/8.Conclusion process/8.Conclusion +development-process/development-process process/development-process +development-process/index process/index +device-mapper/cache admin-guide/device-mapper/cache +device-mapper/cache-policies admin-guide/device-mapper/cache-policies +device-mapper/delay admin-guide/device-mapper/delay +device-mapper/dm-crypt admin-guide/device-mapper/dm-crypt +device-mapper/dm-flakey admin-guide/device-mapper/dm-flakey +device-mapper/dm-init admin-guide/device-mapper/dm-init +device-mapper/dm-integrity admin-guide/device-mapper/dm-integrity +device-mapper/dm-io admin-guide/device-mapper/dm-io +device-mapper/dm-log admin-guide/device-mapper/dm-log +device-mapper/dm-queue-length admin-guide/device-mapper/dm-queue-length +device-mapper/dm-raid admin-guide/device-mapper/dm-raid +device-mapper/dm-service-time admin-guide/device-mapper/dm-service-time +device-mapper/dm-uevent admin-guide/device-mapper/dm-uevent +device-mapper/dm-zoned admin-guide/device-mapper/dm-zoned +device-mapper/era admin-guide/device-mapper/era +device-mapper/index admin-guide/device-mapper/index +device-mapper/kcopyd admin-guide/device-mapper/kcopyd +device-mapper/linear admin-guide/device-mapper/linear +device-mapper/log-writes admin-guide/device-mapper/log-writes +device-mapper/persistent-data admin-guide/device-mapper/persistent-data +device-mapper/snapshot admin-guide/device-mapper/snapshot +device-mapper/statistics admin-guide/device-mapper/statistics +device-mapper/striped admin-guide/device-mapper/striped +device-mapper/switch admin-guide/device-mapper/switch +device-mapper/thin-provisioning admin-guide/device-mapper/thin-provisioning +device-mapper/unstriped admin-guide/device-mapper/unstriped +device-mapper/verity admin-guide/device-mapper/verity +device-mapper/writecache admin-guide/device-mapper/writecache +device-mapper/zero admin-guide/device-mapper/zero +devicetree/writing-schema devicetree/bindings/writing-schema +driver-api/bt8xxgpio driver-api/gpio/bt8xxgpio +driver-api/cxl/access-coordinates driver-api/cxl/linux/access-coordinates +driver-api/cxl/memory-devices driver-api/cxl/theory-of-operation +driver-api/dcdbas userspace-api/dcdbas +driver-api/dell_rbu admin-guide/dell_rbu +driver-api/edid admin-guide/edid +driver-api/gpio driver-api/gpio/index +driver-api/hte/tegra194-hte driver-api/hte/tegra-hte +driver-api/isapnp userspace-api/isapnp +driver-api/media/drivers/v4l-drivers/zoran driver-api/media/drivers/zoran +driver-api/mtd/intel-spi driver-api/mtd/spi-intel +driver-api/pci driver-api/pci/pci +driver-api/pinctl driver-api/pin-control +driver-api/rapidio admin-guide/rapidio +driver-api/serial/moxa-smartio driver-api/tty/moxa-smartio +driver-api/serial/n_gsm driver-api/tty/n_gsm +driver-api/serial/tty driver-api/tty/tty_ldisc +driver-api/thermal/intel_powerclamp admin-guide/thermal/intel_powerclamp +driver-api/usb driver-api/usb/usb +driver-model/binding driver-api/driver-model/binding +driver-model/bus driver-api/driver-model/bus +driver-model/design-patterns driver-api/driver-model/design-patterns +driver-model/device driver-api/driver-model/device +driver-model/devres driver-api/driver-model/devres +driver-model/driver driver-api/driver-model/driver +driver-model/index driver-api/driver-model/index +driver-model/overview driver-api/driver-model/overview +driver-model/platform driver-api/driver-model/platform +driver-model/porting driver-api/driver-model/porting +early-userspace/buffer-format driver-api/early-userspace/buffer-format +early-userspace/early_userspace_support driver-api/early-userspace/early_userspace_support +early-userspace/index driver-api/early-userspace/index +errseq core-api/errseq +filesystems/binderfs admin-guide/binderfs +filesystems/cifs/cifsd filesystems/smb/ksmbd +filesystems/cifs/cifsroot filesystems/smb/cifsroot +filesystems/cifs/index filesystems/smb/index +filesystems/cifs/ksmbd filesystems/smb/ksmbd +filesystems/ext4/ext4 admin-guide/ext4 +filesystems/ext4/ondisk/about filesystems/ext4/about +filesystems/ext4/ondisk/allocators filesystems/ext4/allocators +filesystems/ext4/ondisk/attributes filesystems/ext4/attributes +filesystems/ext4/ondisk/bigalloc filesystems/ext4/bigalloc +filesystems/ext4/ondisk/bitmaps filesystems/ext4/bitmaps +filesystems/ext4/ondisk/blockgroup filesystems/ext4/blockgroup +filesystems/ext4/ondisk/blockmap filesystems/ext4/blockmap +filesystems/ext4/ondisk/blocks filesystems/ext4/blocks +filesystems/ext4/ondisk/checksums filesystems/ext4/checksums +filesystems/ext4/ondisk/directory filesystems/ext4/directory +filesystems/ext4/ondisk/dynamic filesystems/ext4/dynamic +filesystems/ext4/ondisk/eainode filesystems/ext4/eainode +filesystems/ext4/ondisk/globals filesystems/ext4/globals +filesystems/ext4/ondisk/group_descr filesystems/ext4/group_descr +filesystems/ext4/ondisk/ifork filesystems/ext4/ifork +filesystems/ext4/ondisk/inlinedata filesystems/ext4/inlinedata +filesystems/ext4/ondisk/inodes filesystems/ext4/inodes +filesystems/ext4/ondisk/journal filesystems/ext4/journal +filesystems/ext4/ondisk/mmp filesystems/ext4/mmp +filesystems/ext4/ondisk/overview filesystems/ext4/overview +filesystems/ext4/ondisk/special_inodes filesystems/ext4/special_inodes +filesystems/ext4/ondisk/super filesystems/ext4/super +filesystems/sysfs-pci PCI/sysfs-pci +filesystems/sysfs-tagging networking/sysfs-tagging +filesystems/xfs-delayed-logging-design filesystems/xfs/xfs-delayed-logging-design +filesystems/xfs-maintainer-entry-profile filesystems/xfs/xfs-maintainer-entry-profile +filesystems/xfs-online-fsck-design filesystems/xfs/xfs-online-fsck-design +filesystems/xfs-self-describing-metadata filesystems/xfs/xfs-self-describing-metadata +gpio/index admin-guide/gpio/index +gpio/sysfs userspace-api/gpio/sysfs +gpu/amdgpu gpu/amdgpu/index +hte/hte driver-api/hte/hte +hte/index driver-api/hte/index +hte/tegra194-hte driver-api/hte/tegra-hte +input/alps input/devices/alps +input/amijoy input/devices/amijoy +input/appletouch input/devices/appletouch +input/atarikbd input/devices/atarikbd +input/bcm5974 input/devices/bcm5974 +input/cma3000_d0x input/devices/cma3000_d0x +input/cs461x input/devices/cs461x +input/edt-ft5x06 input/devices/edt-ft5x06 +input/elantech input/devices/elantech +input/iforce-protocol input/devices/iforce-protocol +input/joystick input/joydev/joystick +input/joystick-api input/joydev/joystick-api +input/joystick-parport input/devices/joystick-parport +input/ntrig input/devices/ntrig +input/rotary-encoder input/devices/rotary-encoder +input/sentelic input/devices/sentelic +input/walkera0701 input/devices/walkera0701 +input/xpad input/devices/xpad +input/yealink input/devices/yealink +interconnect/interconnect driver-api/interconnect +ioctl/botching-up-ioctls process/botching-up-ioctls +ioctl/cdrom userspace-api/ioctl/cdrom +ioctl/hdio userspace-api/ioctl/hdio +ioctl/index userspace-api/ioctl/index +ioctl/ioctl-decoding userspace-api/ioctl/ioctl-decoding +ioctl/ioctl-number userspace-api/ioctl/ioctl-number +kbuild/namespaces core-api/symbol-namespaces +kdump/index admin-guide/kdump/index +kdump/kdump admin-guide/kdump/kdump +kdump/vmcoreinfo admin-guide/kdump/vmcoreinfo +kernel-documentation doc-guide/kernel-doc +laptops/asus-laptop admin-guide/laptops/asus-laptop +laptops/disk-shock-protection admin-guide/laptops/disk-shock-protection +laptops/index admin-guide/laptops/index +laptops/laptop-mode admin-guide/laptops/laptop-mode +laptops/lg-laptop admin-guide/laptops/lg-laptop +laptops/sony-laptop admin-guide/laptops/sony-laptop +laptops/sonypi admin-guide/laptops/sonypi +laptops/thinkpad-acpi admin-guide/laptops/thinkpad-acpi +laptops/toshiba_haps admin-guide/laptops/toshiba_haps +loongarch/booting arch/loongarch/booting +loongarch/features arch/loongarch/features +loongarch/index arch/loongarch/index +loongarch/introduction arch/loongarch/introduction +loongarch/irq-chip-model arch/loongarch/irq-chip-model +m68k/buddha-driver arch/m68k/buddha-driver +m68k/features arch/m68k/features +m68k/index arch/m68k/index +m68k/kernel-options arch/m68k/kernel-options +md/index driver-api/md/index +md/md-cluster driver-api/md/md-cluster +md/raid5-cache driver-api/md/raid5-cache +md/raid5-ppl driver-api/md/raid5-ppl +media/dvb-drivers/avermedia admin-guide/media/avermedia +media/dvb-drivers/bt8xx admin-guide/media/bt8xx +media/dvb-drivers/ci admin-guide/media/ci +media/dvb-drivers/contributors driver-api/media/drivers/contributors +media/dvb-drivers/dvb-usb driver-api/media/drivers/dvb-usb +media/dvb-drivers/faq admin-guide/media/faq +media/dvb-drivers/frontends driver-api/media/drivers/frontends +media/dvb-drivers/index driver-api/media/drivers/index +media/dvb-drivers/lmedm04 admin-guide/media/lmedm04 +media/dvb-drivers/opera-firmware admin-guide/media/opera-firmware +media/dvb-drivers/technisat admin-guide/media/technisat +media/dvb-drivers/ttusb-dec admin-guide/media/ttusb-dec +media/intro userspace-api/media/intro +media/kapi/cec-core driver-api/media/cec-core +media/kapi/dtv-ca driver-api/media/dtv-ca +media/kapi/dtv-common driver-api/media/dtv-common +media/kapi/dtv-core driver-api/media/dtv-core +media/kapi/dtv-demux driver-api/media/dtv-demux +media/kapi/dtv-frontend driver-api/media/dtv-frontend +media/kapi/dtv-net driver-api/media/dtv-net +media/kapi/mc-core driver-api/media/mc-core +media/kapi/rc-core driver-api/media/rc-core +media/kapi/v4l2-async driver-api/media/v4l2-async +media/kapi/v4l2-common driver-api/media/v4l2-common +media/kapi/v4l2-controls driver-api/media/v4l2-controls +media/kapi/v4l2-core driver-api/media/v4l2-core +media/kapi/v4l2-dev driver-api/media/v4l2-dev +media/kapi/v4l2-device driver-api/media/v4l2-device +media/kapi/v4l2-dv-timings driver-api/media/v4l2-dv-timings +media/kapi/v4l2-event driver-api/media/v4l2-event +media/kapi/v4l2-fh driver-api/media/v4l2-fh +media/kapi/v4l2-flash-led-class driver-api/media/v4l2-flash-led-class +media/kapi/v4l2-fwnode driver-api/media/v4l2-fwnode +media/kapi/v4l2-intro driver-api/media/v4l2-intro +media/kapi/v4l2-mc driver-api/media/v4l2-mc +media/kapi/v4l2-mediabus driver-api/media/v4l2-mediabus +media/kapi/v4l2-mem2mem driver-api/media/v4l2-mem2mem +media/kapi/v4l2-rect driver-api/media/v4l2-rect +media/kapi/v4l2-subdev driver-api/media/v4l2-subdev +media/kapi/v4l2-tuner driver-api/media/v4l2-tuner +media/kapi/v4l2-tveeprom driver-api/media/v4l2-tveeprom +media/kapi/v4l2-videobuf2 driver-api/media/v4l2-videobuf2 +media/media_kapi driver-api/media/index +media/media_uapi userspace-api/media/index +media/uapi/cec/cec-api userspace-api/media/cec/cec-api +media/uapi/cec/cec-func-close userspace-api/media/cec/cec-func-close +media/uapi/cec/cec-func-ioctl userspace-api/media/cec/cec-func-ioctl +media/uapi/cec/cec-func-open userspace-api/media/cec/cec-func-open +media/uapi/cec/cec-func-poll userspace-api/media/cec/cec-func-poll +media/uapi/cec/cec-funcs userspace-api/media/cec/cec-funcs +media/uapi/cec/cec-header userspace-api/media/cec/cec-header +media/uapi/cec/cec-intro userspace-api/media/cec/cec-intro +media/uapi/cec/cec-ioc-adap-g-caps userspace-api/media/cec/cec-ioc-adap-g-caps +media/uapi/cec/cec-ioc-adap-g-conn-info userspace-api/media/cec/cec-ioc-adap-g-conn-info +media/uapi/cec/cec-ioc-adap-g-log-addrs userspace-api/media/cec/cec-ioc-adap-g-log-addrs +media/uapi/cec/cec-ioc-adap-g-phys-addr userspace-api/media/cec/cec-ioc-adap-g-phys-addr +media/uapi/cec/cec-ioc-dqevent userspace-api/media/cec/cec-ioc-dqevent +media/uapi/cec/cec-ioc-g-mode userspace-api/media/cec/cec-ioc-g-mode +media/uapi/cec/cec-ioc-receive userspace-api/media/cec/cec-ioc-receive +media/uapi/cec/cec-pin-error-inj userspace-api/media/cec/cec-pin-error-inj +media/uapi/dvb/ca userspace-api/media/dvb/ca +media/uapi/dvb/ca-fclose userspace-api/media/dvb/ca-fclose +media/uapi/dvb/ca-fopen userspace-api/media/dvb/ca-fopen +media/uapi/dvb/ca-get-cap userspace-api/media/dvb/ca-get-cap +media/uapi/dvb/ca-get-descr-info userspace-api/media/dvb/ca-get-descr-info +media/uapi/dvb/ca-get-msg userspace-api/media/dvb/ca-get-msg +media/uapi/dvb/ca-get-slot-info userspace-api/media/dvb/ca-get-slot-info +media/uapi/dvb/ca-reset userspace-api/media/dvb/ca-reset +media/uapi/dvb/ca-send-msg userspace-api/media/dvb/ca-send-msg +media/uapi/dvb/ca-set-descr userspace-api/media/dvb/ca-set-descr +media/uapi/dvb/ca_data_types userspace-api/media/dvb/ca_data_types +media/uapi/dvb/ca_function_calls userspace-api/media/dvb/ca_function_calls +media/uapi/dvb/ca_high_level userspace-api/media/dvb/ca_high_level +media/uapi/dvb/demux userspace-api/media/dvb/demux +media/uapi/dvb/dmx-add-pid userspace-api/media/dvb/dmx-add-pid +media/uapi/dvb/dmx-expbuf userspace-api/media/dvb/dmx-expbuf +media/uapi/dvb/dmx-fclose userspace-api/media/dvb/dmx-fclose +media/uapi/dvb/dmx-fopen userspace-api/media/dvb/dmx-fopen +media/uapi/dvb/dmx-fread userspace-api/media/dvb/dmx-fread +media/uapi/dvb/dmx-fwrite userspace-api/media/dvb/dmx-fwrite +media/uapi/dvb/dmx-get-pes-pids userspace-api/media/dvb/dmx-get-pes-pids +media/uapi/dvb/dmx-get-stc userspace-api/media/dvb/dmx-get-stc +media/uapi/dvb/dmx-mmap userspace-api/media/dvb/dmx-mmap +media/uapi/dvb/dmx-munmap userspace-api/media/dvb/dmx-munmap +media/uapi/dvb/dmx-qbuf userspace-api/media/dvb/dmx-qbuf +media/uapi/dvb/dmx-querybuf userspace-api/media/dvb/dmx-querybuf +media/uapi/dvb/dmx-remove-pid userspace-api/media/dvb/dmx-remove-pid +media/uapi/dvb/dmx-reqbufs userspace-api/media/dvb/dmx-reqbufs +media/uapi/dvb/dmx-set-buffer-size userspace-api/media/dvb/dmx-set-buffer-size +media/uapi/dvb/dmx-set-filter userspace-api/media/dvb/dmx-set-filter +media/uapi/dvb/dmx-set-pes-filter userspace-api/media/dvb/dmx-set-pes-filter +media/uapi/dvb/dmx-start userspace-api/media/dvb/dmx-start +media/uapi/dvb/dmx-stop userspace-api/media/dvb/dmx-stop +media/uapi/dvb/dmx_fcalls userspace-api/media/dvb/dmx_fcalls +media/uapi/dvb/dmx_types userspace-api/media/dvb/dmx_types +media/uapi/dvb/dvb-fe-read-status userspace-api/media/dvb/dvb-fe-read-status +media/uapi/dvb/dvb-frontend-event userspace-api/media/dvb/dvb-frontend-event +media/uapi/dvb/dvb-frontend-parameters userspace-api/media/dvb/dvb-frontend-parameters +media/uapi/dvb/dvbapi userspace-api/media/dvb/dvbapi +media/uapi/dvb/dvbproperty userspace-api/media/dvb/dvbproperty +media/uapi/dvb/examples userspace-api/media/dvb/examples +media/uapi/dvb/fe-bandwidth-t userspace-api/media/dvb/fe-bandwidth-t +media/uapi/dvb/fe-diseqc-recv-slave-reply userspace-api/media/dvb/fe-diseqc-recv-slave-reply +media/uapi/dvb/fe-diseqc-reset-overload userspace-api/media/dvb/fe-diseqc-reset-overload +media/uapi/dvb/fe-diseqc-send-burst userspace-api/media/dvb/fe-diseqc-send-burst +media/uapi/dvb/fe-diseqc-send-master-cmd userspace-api/media/dvb/fe-diseqc-send-master-cmd +media/uapi/dvb/fe-dishnetwork-send-legacy-cmd userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd +media/uapi/dvb/fe-enable-high-lnb-voltage userspace-api/media/dvb/fe-enable-high-lnb-voltage +media/uapi/dvb/fe-get-event userspace-api/media/dvb/fe-get-event +media/uapi/dvb/fe-get-frontend userspace-api/media/dvb/fe-get-frontend +media/uapi/dvb/fe-get-info userspace-api/media/dvb/fe-get-info +media/uapi/dvb/fe-get-property userspace-api/media/dvb/fe-get-property +media/uapi/dvb/fe-read-ber userspace-api/media/dvb/fe-read-ber +media/uapi/dvb/fe-read-signal-strength userspace-api/media/dvb/fe-read-signal-strength +media/uapi/dvb/fe-read-snr userspace-api/media/dvb/fe-read-snr +media/uapi/dvb/fe-read-status userspace-api/media/dvb/fe-read-status +media/uapi/dvb/fe-read-uncorrected-blocks userspace-api/media/dvb/fe-read-uncorrected-blocks +media/uapi/dvb/fe-set-frontend userspace-api/media/dvb/fe-set-frontend +media/uapi/dvb/fe-set-frontend-tune-mode userspace-api/media/dvb/fe-set-frontend-tune-mode +media/uapi/dvb/fe-set-tone userspace-api/media/dvb/fe-set-tone +media/uapi/dvb/fe-set-voltage userspace-api/media/dvb/fe-set-voltage +media/uapi/dvb/fe-type-t userspace-api/media/dvb/fe-type-t +media/uapi/dvb/fe_property_parameters userspace-api/media/dvb/fe_property_parameters +media/uapi/dvb/frontend userspace-api/media/dvb/frontend +media/uapi/dvb/frontend-header userspace-api/media/dvb/frontend-header +media/uapi/dvb/frontend-property-cable-systems userspace-api/media/dvb/frontend-property-cable-systems +media/uapi/dvb/frontend-property-satellite-systems userspace-api/media/dvb/frontend-property-satellite-systems +media/uapi/dvb/frontend-property-terrestrial-systems userspace-api/media/dvb/frontend-property-terrestrial-systems +media/uapi/dvb/frontend-stat-properties userspace-api/media/dvb/frontend-stat-properties +media/uapi/dvb/frontend_f_close userspace-api/media/dvb/frontend_f_close +media/uapi/dvb/frontend_f_open userspace-api/media/dvb/frontend_f_open +media/uapi/dvb/frontend_fcalls userspace-api/media/dvb/frontend_fcalls +media/uapi/dvb/frontend_legacy_api userspace-api/media/dvb/frontend_legacy_api +media/uapi/dvb/frontend_legacy_dvbv3_api userspace-api/media/dvb/frontend_legacy_dvbv3_api +media/uapi/dvb/headers userspace-api/media/dvb/headers +media/uapi/dvb/intro userspace-api/media/dvb/intro +media/uapi/dvb/legacy_dvb_apis userspace-api/media/dvb/legacy_dvb_apis +media/uapi/dvb/net userspace-api/media/dvb/net +media/uapi/dvb/net-add-if userspace-api/media/dvb/net-add-if +media/uapi/dvb/net-get-if userspace-api/media/dvb/net-get-if +media/uapi/dvb/net-remove-if userspace-api/media/dvb/net-remove-if +media/uapi/dvb/net-types userspace-api/media/dvb/net-types +media/uapi/dvb/query-dvb-frontend-info userspace-api/media/dvb/query-dvb-frontend-info +media/uapi/fdl-appendix userspace-api/media/fdl-appendix +media/uapi/gen-errors userspace-api/media/gen-errors +media/uapi/mediactl/media-controller userspace-api/media/mediactl/media-controller +media/uapi/mediactl/media-controller-intro userspace-api/media/mediactl/media-controller-intro +media/uapi/mediactl/media-controller-model userspace-api/media/mediactl/media-controller-model +media/uapi/mediactl/media-func-close userspace-api/media/mediactl/media-func-close +media/uapi/mediactl/media-func-ioctl userspace-api/media/mediactl/media-func-ioctl +media/uapi/mediactl/media-func-open userspace-api/media/mediactl/media-func-open +media/uapi/mediactl/media-funcs userspace-api/media/mediactl/media-funcs +media/uapi/mediactl/media-header userspace-api/media/mediactl/media-header +media/uapi/mediactl/media-ioc-device-info userspace-api/media/mediactl/media-ioc-device-info +media/uapi/mediactl/media-ioc-enum-entities userspace-api/media/mediactl/media-ioc-enum-entities +media/uapi/mediactl/media-ioc-enum-links userspace-api/media/mediactl/media-ioc-enum-links +media/uapi/mediactl/media-ioc-g-topology userspace-api/media/mediactl/media-ioc-g-topology +media/uapi/mediactl/media-ioc-request-alloc userspace-api/media/mediactl/media-ioc-request-alloc +media/uapi/mediactl/media-ioc-setup-link userspace-api/media/mediactl/media-ioc-setup-link +media/uapi/mediactl/media-request-ioc-queue userspace-api/media/mediactl/media-request-ioc-queue +media/uapi/mediactl/media-request-ioc-reinit userspace-api/media/mediactl/media-request-ioc-reinit +media/uapi/mediactl/media-types userspace-api/media/mediactl/media-types +media/uapi/mediactl/request-api userspace-api/media/mediactl/request-api +media/uapi/mediactl/request-func-close userspace-api/media/mediactl/request-func-close +media/uapi/mediactl/request-func-ioctl userspace-api/media/mediactl/request-func-ioctl +media/uapi/mediactl/request-func-poll userspace-api/media/mediactl/request-func-poll +media/uapi/rc/keytable.c userspace-api/media/rc/keytable.c +media/uapi/rc/lirc-dev userspace-api/media/rc/lirc-dev +media/uapi/rc/lirc-dev-intro userspace-api/media/rc/lirc-dev-intro +media/uapi/rc/lirc-func userspace-api/media/rc/lirc-func +media/uapi/rc/lirc-get-features userspace-api/media/rc/lirc-get-features +media/uapi/rc/lirc-get-rec-mode userspace-api/media/rc/lirc-get-rec-mode +media/uapi/rc/lirc-get-rec-resolution userspace-api/media/rc/lirc-get-rec-resolution +media/uapi/rc/lirc-get-send-mode userspace-api/media/rc/lirc-get-send-mode +media/uapi/rc/lirc-get-timeout userspace-api/media/rc/lirc-get-timeout +media/uapi/rc/lirc-header userspace-api/media/rc/lirc-header +media/uapi/rc/lirc-read userspace-api/media/rc/lirc-read +media/uapi/rc/lirc-set-measure-carrier-mode userspace-api/media/rc/lirc-set-measure-carrier-mode +media/uapi/rc/lirc-set-rec-carrier userspace-api/media/rc/lirc-set-rec-carrier +media/uapi/rc/lirc-set-rec-carrier-range userspace-api/media/rc/lirc-set-rec-carrier-range +media/uapi/rc/lirc-set-rec-timeout userspace-api/media/rc/lirc-set-rec-timeout +media/uapi/rc/lirc-set-send-carrier userspace-api/media/rc/lirc-set-send-carrier +media/uapi/rc/lirc-set-send-duty-cycle userspace-api/media/rc/lirc-set-send-duty-cycle +media/uapi/rc/lirc-set-transmitter-mask userspace-api/media/rc/lirc-set-transmitter-mask +media/uapi/rc/lirc-set-wideband-receiver userspace-api/media/rc/lirc-set-wideband-receiver +media/uapi/rc/lirc-write userspace-api/media/rc/lirc-write +media/uapi/rc/rc-intro userspace-api/media/rc/rc-intro +media/uapi/rc/rc-protos userspace-api/media/rc/rc-protos +media/uapi/rc/rc-sysfs-nodes userspace-api/media/rc/rc-sysfs-nodes +media/uapi/rc/rc-table-change userspace-api/media/rc/rc-table-change +media/uapi/rc/rc-tables userspace-api/media/rc/rc-tables +media/uapi/rc/remote_controllers userspace-api/media/rc/remote_controllers +media/uapi/v4l/app-pri userspace-api/media/v4l/app-pri +media/uapi/v4l/audio userspace-api/media/v4l/audio +media/uapi/v4l/biblio userspace-api/media/v4l/biblio +media/uapi/v4l/buffer userspace-api/media/v4l/buffer +media/uapi/v4l/capture-example userspace-api/media/v4l/capture-example +media/uapi/v4l/capture.c userspace-api/media/v4l/capture.c +media/uapi/v4l/colorspaces userspace-api/media/v4l/colorspaces +media/uapi/v4l/colorspaces-defs userspace-api/media/v4l/colorspaces-defs +media/uapi/v4l/colorspaces-details userspace-api/media/v4l/colorspaces-details +media/uapi/v4l/common userspace-api/media/v4l/common +media/uapi/v4l/common-defs userspace-api/media/v4l/common-defs +media/uapi/v4l/compat userspace-api/media/v4l/compat +media/uapi/v4l/control userspace-api/media/v4l/control +media/uapi/v4l/crop userspace-api/media/v4l/crop +media/uapi/v4l/depth-formats userspace-api/media/v4l/depth-formats +media/uapi/v4l/dev-capture userspace-api/media/v4l/dev-capture +media/uapi/v4l/dev-codec userspace-api/media/v4l/dev-mem2mem +media/uapi/v4l/dev-decoder userspace-api/media/v4l/dev-decoder +media/uapi/v4l/dev-event userspace-api/media/v4l/dev-event +media/uapi/v4l/dev-mem2mem userspace-api/media/v4l/dev-mem2mem +media/uapi/v4l/dev-meta userspace-api/media/v4l/dev-meta +media/uapi/v4l/dev-osd userspace-api/media/v4l/dev-osd +media/uapi/v4l/dev-output userspace-api/media/v4l/dev-output +media/uapi/v4l/dev-overlay userspace-api/media/v4l/dev-overlay +media/uapi/v4l/dev-radio userspace-api/media/v4l/dev-radio +media/uapi/v4l/dev-raw-vbi userspace-api/media/v4l/dev-raw-vbi +media/uapi/v4l/dev-rds userspace-api/media/v4l/dev-rds +media/uapi/v4l/dev-sdr userspace-api/media/v4l/dev-sdr +media/uapi/v4l/dev-sliced-vbi userspace-api/media/v4l/dev-sliced-vbi +media/uapi/v4l/dev-stateless-decoder userspace-api/media/v4l/dev-stateless-decoder +media/uapi/v4l/dev-subdev userspace-api/media/v4l/dev-subdev +media/uapi/v4l/dev-touch userspace-api/media/v4l/dev-touch +media/uapi/v4l/devices userspace-api/media/v4l/devices +media/uapi/v4l/diff-v4l userspace-api/media/v4l/diff-v4l +media/uapi/v4l/dmabuf userspace-api/media/v4l/dmabuf +media/uapi/v4l/dv-timings userspace-api/media/v4l/dv-timings +media/uapi/v4l/ext-ctrls-camera userspace-api/media/v4l/ext-ctrls-camera +media/uapi/v4l/ext-ctrls-codec userspace-api/media/v4l/ext-ctrls-codec +media/uapi/v4l/ext-ctrls-detect userspace-api/media/v4l/ext-ctrls-detect +media/uapi/v4l/ext-ctrls-dv userspace-api/media/v4l/ext-ctrls-dv +media/uapi/v4l/ext-ctrls-flash userspace-api/media/v4l/ext-ctrls-flash +media/uapi/v4l/ext-ctrls-fm-rx userspace-api/media/v4l/ext-ctrls-fm-rx +media/uapi/v4l/ext-ctrls-fm-tx userspace-api/media/v4l/ext-ctrls-fm-tx +media/uapi/v4l/ext-ctrls-image-process userspace-api/media/v4l/ext-ctrls-image-process +media/uapi/v4l/ext-ctrls-image-source userspace-api/media/v4l/ext-ctrls-image-source +media/uapi/v4l/ext-ctrls-jpeg userspace-api/media/v4l/ext-ctrls-jpeg +media/uapi/v4l/ext-ctrls-rf-tuner userspace-api/media/v4l/ext-ctrls-rf-tuner +media/uapi/v4l/extended-controls userspace-api/media/v4l/extended-controls +media/uapi/v4l/field-order userspace-api/media/v4l/field-order +media/uapi/v4l/format userspace-api/media/v4l/format +media/uapi/v4l/func-close userspace-api/media/v4l/func-close +media/uapi/v4l/func-ioctl userspace-api/media/v4l/func-ioctl +media/uapi/v4l/func-mmap userspace-api/media/v4l/func-mmap +media/uapi/v4l/func-munmap userspace-api/media/v4l/func-munmap +media/uapi/v4l/func-open userspace-api/media/v4l/func-open +media/uapi/v4l/func-poll userspace-api/media/v4l/func-poll +media/uapi/v4l/func-read userspace-api/media/v4l/func-read +media/uapi/v4l/func-select userspace-api/media/v4l/func-select +media/uapi/v4l/func-write userspace-api/media/v4l/func-write +media/uapi/v4l/hist-v4l2 userspace-api/media/v4l/hist-v4l2 +media/uapi/v4l/hsv-formats userspace-api/media/v4l/hsv-formats +media/uapi/v4l/io userspace-api/media/v4l/io +media/uapi/v4l/libv4l userspace-api/media/v4l/libv4l +media/uapi/v4l/libv4l-introduction userspace-api/media/v4l/libv4l-introduction +media/uapi/v4l/meta-formats userspace-api/media/v4l/meta-formats +media/uapi/v4l/mmap userspace-api/media/v4l/mmap +media/uapi/v4l/open userspace-api/media/v4l/open +media/uapi/v4l/pixfmt userspace-api/media/v4l/pixfmt +media/uapi/v4l/pixfmt-002 userspace-api/media/v4l/pixfmt-v4l2 +media/uapi/v4l/pixfmt-003 userspace-api/media/v4l/pixfmt-v4l2-mplane +media/uapi/v4l/pixfmt-004 userspace-api/media/v4l/pixfmt-intro +media/uapi/v4l/pixfmt-006 userspace-api/media/v4l/colorspaces-defs +media/uapi/v4l/pixfmt-007 userspace-api/media/v4l/colorspaces-details +media/uapi/v4l/pixfmt-013 userspace-api/media/v4l/pixfmt-compressed +media/uapi/v4l/pixfmt-bayer userspace-api/media/v4l/pixfmt-bayer +media/uapi/v4l/pixfmt-cnf4 userspace-api/media/v4l/pixfmt-cnf4 +media/uapi/v4l/pixfmt-compressed userspace-api/media/v4l/pixfmt-compressed +media/uapi/v4l/pixfmt-indexed userspace-api/media/v4l/pixfmt-indexed +media/uapi/v4l/pixfmt-intro userspace-api/media/v4l/pixfmt-intro +media/uapi/v4l/pixfmt-inzi userspace-api/media/v4l/pixfmt-inzi +media/uapi/v4l/pixfmt-m420 userspace-api/media/v4l/pixfmt-m420 +media/uapi/v4l/pixfmt-meta-d4xx userspace-api/media/v4l/metafmt-d4xx +media/uapi/v4l/pixfmt-meta-intel-ipu3 userspace-api/media/v4l/metafmt-intel-ipu3 +media/uapi/v4l/pixfmt-meta-uvc userspace-api/media/v4l/metafmt-uvc +media/uapi/v4l/pixfmt-meta-vivid userspace-api/media/v4l/metafmt-vivid +media/uapi/v4l/pixfmt-meta-vsp1-hgo userspace-api/media/v4l/metafmt-vsp1-hgo +media/uapi/v4l/pixfmt-meta-vsp1-hgt userspace-api/media/v4l/metafmt-vsp1-hgt +media/uapi/v4l/pixfmt-packed-hsv userspace-api/media/v4l/pixfmt-packed-hsv +media/uapi/v4l/pixfmt-packed-yuv userspace-api/media/v4l/pixfmt-packed-yuv +media/uapi/v4l/pixfmt-reserved userspace-api/media/v4l/pixfmt-reserved +media/uapi/v4l/pixfmt-rgb userspace-api/media/v4l/pixfmt-rgb +media/uapi/v4l/pixfmt-sbggr16 userspace-api/media/v4l/pixfmt-srggb16 +media/uapi/v4l/pixfmt-sdr-cs08 userspace-api/media/v4l/pixfmt-sdr-cs08 +media/uapi/v4l/pixfmt-sdr-cs14le userspace-api/media/v4l/pixfmt-sdr-cs14le +media/uapi/v4l/pixfmt-sdr-cu08 userspace-api/media/v4l/pixfmt-sdr-cu08 +media/uapi/v4l/pixfmt-sdr-cu16le userspace-api/media/v4l/pixfmt-sdr-cu16le +media/uapi/v4l/pixfmt-sdr-pcu16be userspace-api/media/v4l/pixfmt-sdr-pcu16be +media/uapi/v4l/pixfmt-sdr-pcu18be userspace-api/media/v4l/pixfmt-sdr-pcu18be +media/uapi/v4l/pixfmt-sdr-pcu20be userspace-api/media/v4l/pixfmt-sdr-pcu20be +media/uapi/v4l/pixfmt-sdr-ru12le userspace-api/media/v4l/pixfmt-sdr-ru12le +media/uapi/v4l/pixfmt-srggb10 userspace-api/media/v4l/pixfmt-srggb10 +media/uapi/v4l/pixfmt-srggb10-ipu3 userspace-api/media/v4l/pixfmt-srggb10-ipu3 +media/uapi/v4l/pixfmt-srggb10alaw8 userspace-api/media/v4l/pixfmt-srggb10alaw8 +media/uapi/v4l/pixfmt-srggb10dpcm8 userspace-api/media/v4l/pixfmt-srggb10dpcm8 +media/uapi/v4l/pixfmt-srggb10p userspace-api/media/v4l/pixfmt-srggb10p +media/uapi/v4l/pixfmt-srggb12 userspace-api/media/v4l/pixfmt-srggb12 +media/uapi/v4l/pixfmt-srggb12p userspace-api/media/v4l/pixfmt-srggb12p +media/uapi/v4l/pixfmt-srggb14 userspace-api/media/v4l/pixfmt-srggb14 +media/uapi/v4l/pixfmt-srggb14p userspace-api/media/v4l/pixfmt-srggb14p +media/uapi/v4l/pixfmt-srggb16 userspace-api/media/v4l/pixfmt-srggb16 +media/uapi/v4l/pixfmt-srggb8 userspace-api/media/v4l/pixfmt-srggb8 +media/uapi/v4l/pixfmt-tch-td08 userspace-api/media/v4l/pixfmt-tch-td08 +media/uapi/v4l/pixfmt-tch-td16 userspace-api/media/v4l/pixfmt-tch-td16 +media/uapi/v4l/pixfmt-tch-tu08 userspace-api/media/v4l/pixfmt-tch-tu08 +media/uapi/v4l/pixfmt-tch-tu16 userspace-api/media/v4l/pixfmt-tch-tu16 +media/uapi/v4l/pixfmt-uv8 userspace-api/media/v4l/pixfmt-uv8 +media/uapi/v4l/pixfmt-v4l2 userspace-api/media/v4l/pixfmt-v4l2 +media/uapi/v4l/pixfmt-v4l2-mplane userspace-api/media/v4l/pixfmt-v4l2-mplane +media/uapi/v4l/pixfmt-y12i userspace-api/media/v4l/pixfmt-y12i +media/uapi/v4l/pixfmt-y8i userspace-api/media/v4l/pixfmt-y8i +media/uapi/v4l/pixfmt-z16 userspace-api/media/v4l/pixfmt-z16 +media/uapi/v4l/planar-apis userspace-api/media/v4l/planar-apis +media/uapi/v4l/querycap userspace-api/media/v4l/querycap +media/uapi/v4l/rw userspace-api/media/v4l/rw +media/uapi/v4l/sdr-formats userspace-api/media/v4l/sdr-formats +media/uapi/v4l/selection-api userspace-api/media/v4l/selection-api +media/uapi/v4l/selection-api-002 userspace-api/media/v4l/selection-api-intro +media/uapi/v4l/selection-api-003 userspace-api/media/v4l/selection-api-targets +media/uapi/v4l/selection-api-004 userspace-api/media/v4l/selection-api-configuration +media/uapi/v4l/selection-api-005 userspace-api/media/v4l/selection-api-vs-crop-api +media/uapi/v4l/selection-api-006 userspace-api/media/v4l/selection-api-examples +media/uapi/v4l/selection-api-configuration userspace-api/media/v4l/selection-api-configuration +media/uapi/v4l/selection-api-examples userspace-api/media/v4l/selection-api-examples +media/uapi/v4l/selection-api-intro userspace-api/media/v4l/selection-api-intro +media/uapi/v4l/selection-api-targets userspace-api/media/v4l/selection-api-targets +media/uapi/v4l/selection-api-vs-crop-api userspace-api/media/v4l/selection-api-vs-crop-api +media/uapi/v4l/selections-common userspace-api/media/v4l/selections-common +media/uapi/v4l/standard userspace-api/media/v4l/standard +media/uapi/v4l/streaming-par userspace-api/media/v4l/streaming-par +media/uapi/v4l/subdev-formats userspace-api/media/v4l/subdev-formats +media/uapi/v4l/tch-formats userspace-api/media/v4l/tch-formats +media/uapi/v4l/tuner userspace-api/media/v4l/tuner +media/uapi/v4l/user-func userspace-api/media/v4l/user-func +media/uapi/v4l/userp userspace-api/media/v4l/userp +media/uapi/v4l/v4l2 userspace-api/media/v4l/v4l2 +media/uapi/v4l/v4l2-selection-flags userspace-api/media/v4l/v4l2-selection-flags +media/uapi/v4l/v4l2-selection-targets userspace-api/media/v4l/v4l2-selection-targets +media/uapi/v4l/v4l2grab-example userspace-api/media/v4l/v4l2grab-example +media/uapi/v4l/v4l2grab.c userspace-api/media/v4l/v4l2grab.c +media/uapi/v4l/video userspace-api/media/v4l/video +media/uapi/v4l/videodev userspace-api/media/v4l/videodev +media/uapi/v4l/vidioc-create-bufs userspace-api/media/v4l/vidioc-create-bufs +media/uapi/v4l/vidioc-cropcap userspace-api/media/v4l/vidioc-cropcap +media/uapi/v4l/vidioc-dbg-g-chip-info userspace-api/media/v4l/vidioc-dbg-g-chip-info +media/uapi/v4l/vidioc-dbg-g-register userspace-api/media/v4l/vidioc-dbg-g-register +media/uapi/v4l/vidioc-decoder-cmd userspace-api/media/v4l/vidioc-decoder-cmd +media/uapi/v4l/vidioc-dqevent userspace-api/media/v4l/vidioc-dqevent +media/uapi/v4l/vidioc-dv-timings-cap userspace-api/media/v4l/vidioc-dv-timings-cap +media/uapi/v4l/vidioc-encoder-cmd userspace-api/media/v4l/vidioc-encoder-cmd +media/uapi/v4l/vidioc-enum-dv-timings userspace-api/media/v4l/vidioc-enum-dv-timings +media/uapi/v4l/vidioc-enum-fmt userspace-api/media/v4l/vidioc-enum-fmt +media/uapi/v4l/vidioc-enum-frameintervals userspace-api/media/v4l/vidioc-enum-frameintervals +media/uapi/v4l/vidioc-enum-framesizes userspace-api/media/v4l/vidioc-enum-framesizes +media/uapi/v4l/vidioc-enum-freq-bands userspace-api/media/v4l/vidioc-enum-freq-bands +media/uapi/v4l/vidioc-enumaudio userspace-api/media/v4l/vidioc-enumaudio +media/uapi/v4l/vidioc-enumaudioout userspace-api/media/v4l/vidioc-enumaudioout +media/uapi/v4l/vidioc-enuminput userspace-api/media/v4l/vidioc-enuminput +media/uapi/v4l/vidioc-enumoutput userspace-api/media/v4l/vidioc-enumoutput +media/uapi/v4l/vidioc-enumstd userspace-api/media/v4l/vidioc-enumstd +media/uapi/v4l/vidioc-expbuf userspace-api/media/v4l/vidioc-expbuf +media/uapi/v4l/vidioc-g-audio userspace-api/media/v4l/vidioc-g-audio +media/uapi/v4l/vidioc-g-audioout userspace-api/media/v4l/vidioc-g-audioout +media/uapi/v4l/vidioc-g-crop userspace-api/media/v4l/vidioc-g-crop +media/uapi/v4l/vidioc-g-ctrl userspace-api/media/v4l/vidioc-g-ctrl +media/uapi/v4l/vidioc-g-dv-timings userspace-api/media/v4l/vidioc-g-dv-timings +media/uapi/v4l/vidioc-g-edid userspace-api/media/v4l/vidioc-g-edid +media/uapi/v4l/vidioc-g-enc-index userspace-api/media/v4l/vidioc-g-enc-index +media/uapi/v4l/vidioc-g-ext-ctrls userspace-api/media/v4l/vidioc-g-ext-ctrls +media/uapi/v4l/vidioc-g-fbuf userspace-api/media/v4l/vidioc-g-fbuf +media/uapi/v4l/vidioc-g-fmt userspace-api/media/v4l/vidioc-g-fmt +media/uapi/v4l/vidioc-g-frequency userspace-api/media/v4l/vidioc-g-frequency +media/uapi/v4l/vidioc-g-input userspace-api/media/v4l/vidioc-g-input +media/uapi/v4l/vidioc-g-jpegcomp userspace-api/media/v4l/vidioc-g-jpegcomp +media/uapi/v4l/vidioc-g-modulator userspace-api/media/v4l/vidioc-g-modulator +media/uapi/v4l/vidioc-g-output userspace-api/media/v4l/vidioc-g-output +media/uapi/v4l/vidioc-g-parm userspace-api/media/v4l/vidioc-g-parm +media/uapi/v4l/vidioc-g-priority userspace-api/media/v4l/vidioc-g-priority +media/uapi/v4l/vidioc-g-selection userspace-api/media/v4l/vidioc-g-selection +media/uapi/v4l/vidioc-g-sliced-vbi-cap userspace-api/media/v4l/vidioc-g-sliced-vbi-cap +media/uapi/v4l/vidioc-g-std userspace-api/media/v4l/vidioc-g-std +media/uapi/v4l/vidioc-g-tuner userspace-api/media/v4l/vidioc-g-tuner +media/uapi/v4l/vidioc-log-status userspace-api/media/v4l/vidioc-log-status +media/uapi/v4l/vidioc-overlay userspace-api/media/v4l/vidioc-overlay +media/uapi/v4l/vidioc-prepare-buf userspace-api/media/v4l/vidioc-prepare-buf +media/uapi/v4l/vidioc-qbuf userspace-api/media/v4l/vidioc-qbuf +media/uapi/v4l/vidioc-query-dv-timings userspace-api/media/v4l/vidioc-query-dv-timings +media/uapi/v4l/vidioc-querybuf userspace-api/media/v4l/vidioc-querybuf +media/uapi/v4l/vidioc-querycap userspace-api/media/v4l/vidioc-querycap +media/uapi/v4l/vidioc-queryctrl userspace-api/media/v4l/vidioc-queryctrl +media/uapi/v4l/vidioc-querystd userspace-api/media/v4l/vidioc-querystd +media/uapi/v4l/vidioc-reqbufs userspace-api/media/v4l/vidioc-reqbufs +media/uapi/v4l/vidioc-s-hw-freq-seek userspace-api/media/v4l/vidioc-s-hw-freq-seek +media/uapi/v4l/vidioc-streamon userspace-api/media/v4l/vidioc-streamon +media/uapi/v4l/vidioc-subdev-enum-frame-interval userspace-api/media/v4l/vidioc-subdev-enum-frame-interval +media/uapi/v4l/vidioc-subdev-enum-frame-size userspace-api/media/v4l/vidioc-subdev-enum-frame-size +media/uapi/v4l/vidioc-subdev-enum-mbus-code userspace-api/media/v4l/vidioc-subdev-enum-mbus-code +media/uapi/v4l/vidioc-subdev-g-crop userspace-api/media/v4l/vidioc-subdev-g-crop +media/uapi/v4l/vidioc-subdev-g-fmt userspace-api/media/v4l/vidioc-subdev-g-fmt +media/uapi/v4l/vidioc-subdev-g-frame-interval userspace-api/media/v4l/vidioc-subdev-g-frame-interval +media/uapi/v4l/vidioc-subdev-g-selection userspace-api/media/v4l/vidioc-subdev-g-selection +media/uapi/v4l/vidioc-subscribe-event userspace-api/media/v4l/vidioc-subscribe-event +media/uapi/v4l/yuv-formats userspace-api/media/v4l/yuv-formats +media/v4l-drivers/au0828-cardlist admin-guide/media/au0828-cardlist +media/v4l-drivers/bttv admin-guide/media/bttv +media/v4l-drivers/bttv-cardlist admin-guide/media/bttv-cardlist +media/v4l-drivers/bttv-devel driver-api/media/drivers/bttv-devel +media/v4l-drivers/cafe_ccic admin-guide/media/cafe_ccic +media/v4l-drivers/cardlist admin-guide/media/cardlist +media/v4l-drivers/cx2341x driver-api/media/drivers/cx2341x-devel +media/v4l-drivers/cx2341x-devel driver-api/media/drivers/cx2341x-devel +media/v4l-drivers/cx2341x-uapi userspace-api/media/drivers/cx2341x-uapi +media/v4l-drivers/cx23885-cardlist admin-guide/media/cx23885-cardlist +media/v4l-drivers/cx88 admin-guide/media/cx88 +media/v4l-drivers/cx88-cardlist admin-guide/media/cx88-cardlist +media/v4l-drivers/cx88-devel driver-api/media/drivers/cx88-devel +media/v4l-drivers/em28xx-cardlist admin-guide/media/em28xx-cardlist +media/v4l-drivers/fimc admin-guide/media/fimc +media/v4l-drivers/fimc-devel driver-api/media/drivers/fimc-devel +media/v4l-drivers/fourcc userspace-api/media/v4l/fourcc +media/v4l-drivers/gspca-cardlist admin-guide/media/gspca-cardlist +media/v4l-drivers/imx admin-guide/media/imx +media/v4l-drivers/imx-uapi userspace-api/media/drivers/imx-uapi +media/v4l-drivers/imx7 admin-guide/media/imx7 +media/v4l-drivers/index userspace-api/media/drivers/index +media/v4l-drivers/ipu3 admin-guide/media/ipu3 +media/v4l-drivers/ivtv admin-guide/media/ivtv +media/v4l-drivers/ivtv-cardlist admin-guide/media/ivtv-cardlist +media/v4l-drivers/max2175 userspace-api/media/drivers/max2175 +media/v4l-drivers/omap3isp admin-guide/media/omap3isp +media/v4l-drivers/omap3isp-uapi userspace-api/media/drivers/omap3isp-uapi +media/v4l-drivers/philips admin-guide/media/philips +media/v4l-drivers/pvrusb2 driver-api/media/drivers/pvrusb2 +media/v4l-drivers/pxa_camera driver-api/media/drivers/pxa_camera +media/v4l-drivers/qcom_camss admin-guide/media/qcom_camss +media/v4l-drivers/radiotrack driver-api/media/drivers/radiotrack +media/v4l-drivers/rcar-fdp1 admin-guide/media/rcar-fdp1 +media/v4l-drivers/saa7134 admin-guide/media/saa7134 +media/v4l-drivers/saa7134-cardlist admin-guide/media/saa7134-cardlist +media/v4l-drivers/saa7134-devel driver-api/media/drivers/saa7134-devel +media/v4l-drivers/saa7164-cardlist admin-guide/media/saa7164-cardlist +media/v4l-drivers/sh_mobile_ceu_camera driver-api/media/drivers/sh_mobile_ceu_camera +media/v4l-drivers/si470x admin-guide/media/si470x +media/v4l-drivers/si4713 admin-guide/media/si4713 +media/v4l-drivers/si476x admin-guide/media/si476x +media/v4l-drivers/tuner-cardlist admin-guide/media/tuner-cardlist +media/v4l-drivers/tuners driver-api/media/drivers/tuners +media/v4l-drivers/uvcvideo userspace-api/media/drivers/uvcvideo +media/v4l-drivers/v4l-with-ir admin-guide/media/remote-controller +media/v4l-drivers/vimc admin-guide/media/vimc +media/v4l-drivers/vimc-devel driver-api/media/drivers/vimc-devel +media/v4l-drivers/vivid admin-guide/media/vivid +media/v4l-drivers/zoran driver-api/media/drivers/zoran +memory-devices/ti-emif driver-api/memory-devices/ti-emif +mips/booting arch/mips/booting +mips/features arch/mips/features +mips/index arch/mips/index +mips/ingenic-tcu arch/mips/ingenic-tcu +mm/slub admin-guide/mm/slab +mmc/index driver-api/mmc/index +mmc/mmc-async-req driver-api/mmc/mmc-async-req +mmc/mmc-dev-attrs driver-api/mmc/mmc-dev-attrs +mmc/mmc-dev-parts driver-api/mmc/mmc-dev-parts +mmc/mmc-tools driver-api/mmc/mmc-tools +mtd/index driver-api/mtd/index +mtd/intel-spi driver-api/mtd/spi-intel +mtd/nand_ecc driver-api/mtd/nand_ecc +mtd/spi-nor driver-api/mtd/spi-nor +namespaces/compatibility-list admin-guide/namespaces/compatibility-list +namespaces/index admin-guide/namespaces/index +namespaces/resource-control admin-guide/namespaces/resource-control +networking/altera_tse networking/device_drivers/ethernet/altera/altera_tse +networking/baycom networking/device_drivers/hamradio/baycom +networking/bpf_flow_dissector bpf/prog_flow_dissector +networking/cxacru networking/device_drivers/atm/cxacru +networking/defza networking/device_drivers/fddi/defza +networking/device_drivers/3com/3c509 networking/device_drivers/ethernet/3com/3c509 +networking/device_drivers/3com/vortex networking/device_drivers/ethernet/3com/vortex +networking/device_drivers/amazon/ena networking/device_drivers/ethernet/amazon/ena +networking/device_drivers/aquantia/atlantic networking/device_drivers/ethernet/aquantia/atlantic +networking/device_drivers/chelsio/cxgb networking/device_drivers/ethernet/chelsio/cxgb +networking/device_drivers/cirrus/cs89x0 networking/device_drivers/ethernet/cirrus/cs89x0 +networking/device_drivers/davicom/dm9000 networking/device_drivers/ethernet/davicom/dm9000 +networking/device_drivers/dec/dmfe networking/device_drivers/ethernet/dec/dmfe +networking/device_drivers/dlink/dl2k networking/device_drivers/ethernet/dlink/dl2k +networking/device_drivers/freescale/dpaa networking/device_drivers/ethernet/freescale/dpaa +networking/device_drivers/freescale/dpaa2/dpio-driver networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver +networking/device_drivers/freescale/dpaa2/ethernet-driver networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver +networking/device_drivers/freescale/dpaa2/index networking/device_drivers/ethernet/freescale/dpaa2/index +networking/device_drivers/freescale/dpaa2/mac-phy-support networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support +networking/device_drivers/freescale/dpaa2/overview networking/device_drivers/ethernet/freescale/dpaa2/overview +networking/device_drivers/freescale/gianfar networking/device_drivers/ethernet/freescale/gianfar +networking/device_drivers/google/gve networking/device_drivers/ethernet/google/gve +networking/device_drivers/intel/e100 networking/device_drivers/ethernet/intel/e100 +networking/device_drivers/intel/e1000 networking/device_drivers/ethernet/intel/e1000 +networking/device_drivers/intel/e1000e networking/device_drivers/ethernet/intel/e1000e +networking/device_drivers/intel/fm10k networking/device_drivers/ethernet/intel/fm10k +networking/device_drivers/intel/i40e networking/device_drivers/ethernet/intel/i40e +networking/device_drivers/intel/iavf networking/device_drivers/ethernet/intel/iavf +networking/device_drivers/intel/ice networking/device_drivers/ethernet/intel/ice +networking/device_drivers/intel/igb networking/device_drivers/ethernet/intel/igb +networking/device_drivers/intel/igbvf networking/device_drivers/ethernet/intel/igbvf +networking/device_drivers/intel/ipw2100 networking/device_drivers/wifi/intel/ipw2100 +networking/device_drivers/intel/ipw2200 networking/device_drivers/wifi/intel/ipw2200 +networking/device_drivers/intel/ixgbe networking/device_drivers/ethernet/intel/ixgbe +networking/device_drivers/intel/ixgbevf networking/device_drivers/ethernet/intel/ixgbevf +networking/device_drivers/marvell/octeontx2 networking/device_drivers/ethernet/marvell/octeontx2 +networking/device_drivers/microsoft/netvsc networking/device_drivers/ethernet/microsoft/netvsc +networking/device_drivers/neterion/s2io networking/device_drivers/ethernet/neterion/s2io +networking/device_drivers/netronome/nfp networking/device_drivers/ethernet/netronome/nfp +networking/device_drivers/pensando/ionic networking/device_drivers/ethernet/pensando/ionic +networking/device_drivers/qualcomm/rmnet networking/device_drivers/cellular/qualcomm/rmnet +networking/device_drivers/smsc/smc9 networking/device_drivers/ethernet/smsc/smc9 +networking/device_drivers/stmicro/stmmac networking/device_drivers/ethernet/stmicro/stmmac +networking/device_drivers/ti/cpsw networking/device_drivers/ethernet/ti/cpsw +networking/device_drivers/ti/cpsw_switchdev networking/device_drivers/ethernet/ti/cpsw_switchdev +networking/device_drivers/ti/tlan networking/device_drivers/ethernet/ti/tlan +networking/devlink-trap networking/devlink/devlink-trap +networking/dpaa2/dpio-driver networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver +networking/dpaa2/ethernet-driver networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver +networking/dpaa2/index networking/device_drivers/ethernet/freescale/dpaa2/index +networking/dpaa2/overview networking/device_drivers/ethernet/freescale/dpaa2/overview +networking/e100 networking/device_drivers/ethernet/intel/e100 +networking/e1000 networking/device_drivers/ethernet/intel/e1000 +networking/e1000e networking/device_drivers/ethernet/intel/e1000e +networking/fm10k networking/device_drivers/ethernet/intel/fm10k +networking/fore200e networking/device_drivers/atm/fore200e +networking/hinic networking/device_drivers/ethernet/huawei/hinic +networking/i40e networking/device_drivers/ethernet/intel/i40e +networking/iavf networking/device_drivers/ethernet/intel/iavf +networking/ice networking/device_drivers/ethernet/intel/ice +networking/igb networking/device_drivers/ethernet/intel/igb +networking/igbvf networking/device_drivers/ethernet/intel/igbvf +networking/iphase networking/device_drivers/atm/iphase +networking/ixgbe networking/device_drivers/ethernet/intel/ixgbe +networking/ixgbevf networking/device_drivers/ethernet/intel/ixgbevf +networking/netdev-FAQ process/maintainer-netdev +networking/skfp networking/device_drivers/fddi/skfp +networking/z8530drv networking/device_drivers/hamradio/z8530drv +nfc/index driver-api/nfc/index +nfc/nfc-hci driver-api/nfc/nfc-hci +nfc/nfc-pn544 driver-api/nfc/nfc-pn544 +nios2/features arch/nios2/features +nios2/index arch/nios2/index +nios2/nios2 arch/nios2/nios2 +nvdimm/btt driver-api/nvdimm/btt +nvdimm/index driver-api/nvdimm/index +nvdimm/nvdimm driver-api/nvdimm/nvdimm +nvdimm/security driver-api/nvdimm/security +nvmem/nvmem driver-api/nvmem +openrisc/features arch/openrisc/features +openrisc/index arch/openrisc/index +openrisc/openrisc_port arch/openrisc/openrisc_port +openrisc/todo arch/openrisc/todo +parisc/debugging arch/parisc/debugging +parisc/features arch/parisc/features +parisc/index arch/parisc/index +parisc/registers arch/parisc/registers +perf/arm-ccn admin-guide/perf/arm-ccn +perf/arm_dsu_pmu admin-guide/perf/arm_dsu_pmu +perf/hisi-pmu admin-guide/perf/hisi-pmu +perf/index admin-guide/perf/index +perf/qcom_l2_pmu admin-guide/perf/qcom_l2_pmu +perf/qcom_l3_pmu admin-guide/perf/qcom_l3_pmu +perf/thunderx2-pmu admin-guide/perf/thunderx2-pmu +perf/xgene-pmu admin-guide/perf/xgene-pmu +phy/samsung-usb2 driver-api/phy/samsung-usb2 +powerpc/associativity arch/powerpc/associativity +powerpc/booting arch/powerpc/booting +powerpc/bootwrapper arch/powerpc/bootwrapper +powerpc/cpu_families arch/powerpc/cpu_families +powerpc/cpu_features arch/powerpc/cpu_features +powerpc/dawr-power9 arch/powerpc/dawr-power9 +powerpc/dexcr arch/powerpc/dexcr +powerpc/dscr arch/powerpc/dscr +powerpc/eeh-pci-error-recovery arch/powerpc/eeh-pci-error-recovery +powerpc/elf_hwcaps arch/powerpc/elf_hwcaps +powerpc/elfnote arch/powerpc/elfnote +powerpc/features arch/powerpc/features +powerpc/firmware-assisted-dump arch/powerpc/firmware-assisted-dump +powerpc/hvcs arch/powerpc/hvcs +powerpc/imc arch/powerpc/imc +powerpc/index arch/powerpc/index +powerpc/isa-versions arch/powerpc/isa-versions +powerpc/kaslr-booke32 arch/powerpc/kaslr-booke32 +powerpc/mpc52xx arch/powerpc/mpc52xx +powerpc/papr_hcalls arch/powerpc/papr_hcalls +powerpc/pci_iov_resource_on_powernv arch/powerpc/pci_iov_resource_on_powernv +powerpc/pmu-ebb arch/powerpc/pmu-ebb +powerpc/ptrace arch/powerpc/ptrace +powerpc/qe_firmware arch/powerpc/qe_firmware +powerpc/syscall64-abi arch/powerpc/syscall64-abi +powerpc/transactional_memory arch/powerpc/transactional_memory +powerpc/ultravisor arch/powerpc/ultravisor +powerpc/vas-api arch/powerpc/vas-api +powerpc/vcpudispatch_stats arch/powerpc/vcpudispatch_stats +powerpc/vmemmap_dedup arch/powerpc/vmemmap_dedup +process/clang-format dev-tools/clang-format +process/magic-number staging/magic-number +process/unaligned-memory-access core-api/unaligned-memory-access +rapidio/index driver-api/rapidio/index +rapidio/mport_cdev driver-api/rapidio/mport_cdev +rapidio/rapidio driver-api/rapidio/rapidio +rapidio/rio_cm driver-api/rapidio/rio_cm +rapidio/sysfs driver-api/rapidio/sysfs +rapidio/tsi721 driver-api/rapidio/tsi721 +riscv/acpi arch/riscv/acpi +riscv/boot arch/riscv/boot +riscv/boot-image-header arch/riscv/boot-image-header +riscv/features arch/riscv/features +riscv/hwprobe arch/riscv/hwprobe +riscv/index arch/riscv/index +riscv/patch-acceptance arch/riscv/patch-acceptance +riscv/uabi arch/riscv/uabi +riscv/vector arch/riscv/vector +riscv/vm-layout arch/riscv/vm-layout +s390/3270 arch/s390/3270 +s390/cds arch/s390/cds +s390/common_io arch/s390/common_io +s390/driver-model arch/s390/driver-model +s390/features arch/s390/features +s390/index arch/s390/index +s390/monreader arch/s390/monreader +s390/pci arch/s390/pci +s390/qeth arch/s390/qeth +s390/s390dbf arch/s390/s390dbf +s390/text_files arch/s390/text_files +s390/vfio-ap arch/s390/vfio-ap +s390/vfio-ap-locking arch/s390/vfio-ap-locking +s390/vfio-ccw arch/s390/vfio-ccw +s390/zfcpdump arch/s390/zfcpdump +security/LSM security/lsm-development +security/LSM-sctp security/SCTP +serial/driver driver-api/serial/driver +serial/index driver-api/serial/index +serial/moxa-smartio driver-api/tty/moxa-smartio +serial/n_gsm driver-api/tty/n_gsm +serial/serial-iso7816 driver-api/serial/serial-iso7816 +serial/serial-rs485 driver-api/serial/serial-rs485 +serial/tty driver-api/tty/tty_ldisc +sh/booting arch/sh/booting +sh/features arch/sh/features +sh/index arch/sh/index +sh/new-machine arch/sh/new-machine +sh/register-banks arch/sh/register-banks +sparc/adi arch/sparc/adi +sparc/console arch/sparc/console +sparc/features arch/sparc/features +sparc/index arch/sparc/index +sparc/oradax/oracle-dax arch/sparc/oradax/oracle-dax +staging/kprobes trace/kprobes +sysctl/abi admin-guide/sysctl/abi +sysctl/fs admin-guide/sysctl/fs +sysctl/index admin-guide/sysctl/index +sysctl/kernel admin-guide/sysctl/kernel +sysctl/net admin-guide/sysctl/net +sysctl/sunrpc admin-guide/sysctl/sunrpc +sysctl/user admin-guide/sysctl/user +sysctl/vm admin-guide/sysctl/vm +thermal/cpu-cooling-api driver-api/thermal/cpu-cooling-api +thermal/exynos_thermal driver-api/thermal/exynos_thermal +thermal/exynos_thermal_emulation driver-api/thermal/exynos_thermal_emulation +thermal/index driver-api/thermal/index +thermal/intel_powerclamp admin-guide/thermal/intel_powerclamp +thermal/nouveau_thermal driver-api/thermal/nouveau_thermal +thermal/power_allocator driver-api/thermal/power_allocator +thermal/sysfs-api driver-api/thermal/sysfs-api +thermal/x86_pkg_temperature_thermal driver-api/thermal/x86_pkg_temperature_thermal +tpm/index security/tpm/index +tpm/tpm_vtpm_proxy security/tpm/tpm_vtpm_proxy +trace/coresight trace/coresight/coresight +trace/coresight-cpu-debug trace/coresight/coresight-cpu-debug +trace/rv/da_monitor_synthesis trace/rv/monitor_synthesis +translations/it_IT/admin-guide/security-bugs translations/it_IT/process/security-bugs +translations/it_IT/process/clang-format translations/it_IT/dev-tools/clang-format +translations/it_IT/process/magic-number translations/it_IT/staging/magic-number +translations/it_IT/riscv/patch-acceptance translations/it_IT/arch/riscv/patch-acceptance +translations/ja_JP/howto translations/ja_JP/process/howto +translations/ko_KR/howto translations/ko_KR/process/howto +translations/sp_SP/howto translations/sp_SP/process/howto +translations/sp_SP/submitting-patches translations/sp_SP/process/submitting-patches +translations/zh_CN/admin-guide/security-bugs translations/zh_CN/process/security-bugs +translations/zh_CN/arch translations/zh_CN/arch/index +translations/zh_CN/arm64/amu translations/zh_CN/arch/arm64/amu +translations/zh_CN/arm64/elf_hwcaps translations/zh_CN/arch/arm64/elf_hwcaps +translations/zh_CN/arm64/hugetlbpage translations/zh_CN/arch/arm64/hugetlbpage +translations/zh_CN/arm64/index translations/zh_CN/arch/arm64/index +translations/zh_CN/arm64/perf translations/zh_CN/arch/arm64/perf +translations/zh_CN/coding-style translations/zh_CN/process/coding-style +translations/zh_CN/loongarch/booting translations/zh_CN/arch/loongarch/booting +translations/zh_CN/loongarch/features translations/zh_CN/arch/loongarch/features +translations/zh_CN/loongarch/index translations/zh_CN/arch/loongarch/index +translations/zh_CN/loongarch/introduction translations/zh_CN/arch/loongarch/introduction +translations/zh_CN/loongarch/irq-chip-model translations/zh_CN/arch/loongarch/irq-chip-model +translations/zh_CN/mips/booting translations/zh_CN/arch/mips/booting +translations/zh_CN/mips/features translations/zh_CN/arch/mips/features +translations/zh_CN/mips/index translations/zh_CN/arch/mips/index +translations/zh_CN/mips/ingenic-tcu translations/zh_CN/arch/mips/ingenic-tcu +translations/zh_CN/openrisc/index translations/zh_CN/arch/openrisc/index +translations/zh_CN/openrisc/openrisc_port translations/zh_CN/arch/openrisc/openrisc_port +translations/zh_CN/openrisc/todo translations/zh_CN/arch/openrisc/todo +translations/zh_CN/parisc/debugging translations/zh_CN/arch/parisc/debugging +translations/zh_CN/parisc/index translations/zh_CN/arch/parisc/index +translations/zh_CN/parisc/registers translations/zh_CN/arch/parisc/registers +translations/zh_CN/riscv/boot-image-header translations/zh_CN/arch/riscv/boot-image-header +translations/zh_CN/riscv/index translations/zh_CN/arch/riscv/index +translations/zh_CN/riscv/patch-acceptance translations/zh_CN/arch/riscv/patch-acceptance +translations/zh_CN/riscv/vm-layout translations/zh_CN/arch/riscv/vm-layout +translations/zh_CN/vm/active_mm translations/zh_CN/mm/active_mm +translations/zh_CN/vm/balance translations/zh_CN/mm/balance +translations/zh_CN/vm/damon/api translations/zh_CN/mm/damon/api +translations/zh_CN/vm/damon/design translations/zh_CN/mm/damon/design +translations/zh_CN/vm/damon/faq translations/zh_CN/mm/damon/faq +translations/zh_CN/vm/damon/index translations/zh_CN/mm/damon/index +translations/zh_CN/vm/free_page_reporting translations/zh_CN/mm/free_page_reporting +translations/zh_CN/vm/highmem translations/zh_CN/mm/highmem +translations/zh_CN/vm/hmm translations/zh_CN/mm/hmm +translations/zh_CN/vm/hugetlbfs_reserv translations/zh_CN/mm/hugetlbfs_reserv +translations/zh_CN/vm/hwpoison translations/zh_CN/mm/hwpoison +translations/zh_CN/vm/index translations/zh_CN/mm/index +translations/zh_CN/vm/ksm translations/zh_CN/mm/ksm +translations/zh_CN/vm/memory-model translations/zh_CN/mm/memory-model +translations/zh_CN/vm/mmu_notifier translations/zh_CN/mm/mmu_notifier +translations/zh_CN/vm/numa translations/zh_CN/mm/numa +translations/zh_CN/vm/overcommit-accounting translations/zh_CN/mm/overcommit-accounting +translations/zh_CN/vm/page_frags translations/zh_CN/mm/page_frags +translations/zh_CN/vm/page_owner translations/zh_CN/mm/page_owner +translations/zh_CN/vm/page_table_check translations/zh_CN/mm/page_table_check +translations/zh_CN/vm/remap_file_pages translations/zh_CN/mm/remap_file_pages +translations/zh_CN/vm/split_page_table_lock translations/zh_CN/mm/split_page_table_lock +translations/zh_CN/vm/zsmalloc translations/zh_CN/mm/zsmalloc +translations/zh_TW/arm64/amu translations/zh_TW/arch/arm64/amu +translations/zh_TW/arm64/elf_hwcaps translations/zh_TW/arch/arm64/elf_hwcaps +translations/zh_TW/arm64/hugetlbpage translations/zh_TW/arch/arm64/hugetlbpage +translations/zh_TW/arm64/index translations/zh_TW/arch/arm64/index +translations/zh_TW/arm64/perf translations/zh_TW/arch/arm64/perf +tty/device_drivers/oxsemi-tornado misc-devices/oxsemi-tornado +tty/index driver-api/tty/index +tty/n_tty driver-api/tty/n_tty +tty/tty_buffer driver-api/tty/tty_buffer +tty/tty_driver driver-api/tty/tty_driver +tty/tty_internals driver-api/tty/tty_internals +tty/tty_ldisc driver-api/tty/tty_ldisc +tty/tty_port driver-api/tty/tty_port +tty/tty_struct driver-api/tty/tty_struct +usb/typec driver-api/usb/typec +usb/usb3-debug-port driver-api/usb/usb3-debug-port +userspace-api/media/drivers/st-vgxy61 userspace-api/media/drivers/vgxy61 +userspace-api/media/v4l/pixfmt-meta-d4xx userspace-api/media/v4l/metafmt-d4xx +userspace-api/media/v4l/pixfmt-meta-intel-ipu3 userspace-api/media/v4l/metafmt-intel-ipu3 +userspace-api/media/v4l/pixfmt-meta-rkisp1 userspace-api/media/v4l/metafmt-rkisp1 +userspace-api/media/v4l/pixfmt-meta-uvc userspace-api/media/v4l/metafmt-uvc +userspace-api/media/v4l/pixfmt-meta-vivid userspace-api/media/v4l/metafmt-vivid +userspace-api/media/v4l/pixfmt-meta-vsp1-hgo userspace-api/media/v4l/metafmt-vsp1-hgo +userspace-api/media/v4l/pixfmt-meta-vsp1-hgt userspace-api/media/v4l/metafmt-vsp1-hgt +virt/coco/sevguest virt/coco/sev-guest +virt/kvm/amd-memory-encryption virt/kvm/x86/amd-memory-encryption +virt/kvm/arm/psci virt/kvm/arm/fw-pseudo-registers +virt/kvm/cpuid virt/kvm/x86/cpuid +virt/kvm/hypercalls virt/kvm/x86/hypercalls +virt/kvm/mmu virt/kvm/x86/mmu +virt/kvm/msr virt/kvm/x86/msr +virt/kvm/nested-vmx virt/kvm/x86/nested-vmx +virt/kvm/running-nested-guests virt/kvm/x86/running-nested-guests +virt/kvm/s390-diag virt/kvm/s390/s390-diag +virt/kvm/s390-pv virt/kvm/s390/s390-pv +virt/kvm/s390-pv-boot virt/kvm/s390/s390-pv-boot +virt/kvm/timekeeping virt/kvm/x86/timekeeping +virt/kvm/x86/halt-polling virt/kvm/halt-polling +virtual/index virt/index +virtual/kvm/amd-memory-encryption virt/kvm/x86/amd-memory-encryption +virtual/kvm/cpuid virt/kvm/x86/cpuid +virtual/kvm/index virt/kvm/index +virtual/kvm/vcpu-requests virt/kvm/vcpu-requests +virtual/paravirt_ops virt/paravirt_ops +vm/active_mm mm/active_mm +vm/arch_pgtable_helpers mm/arch_pgtable_helpers +vm/balance mm/balance +vm/bootmem mm/bootmem +vm/damon/api mm/damon/api +vm/damon/design mm/damon/design +vm/damon/faq mm/damon/faq +vm/damon/index mm/damon/index +vm/free_page_reporting mm/free_page_reporting +vm/highmem mm/highmem +vm/hmm mm/hmm +vm/hugetlbfs_reserv mm/hugetlbfs_reserv +vm/hugetlbpage admin-guide/mm/hugetlbpage +vm/hwpoison mm/hwpoison +vm/idle_page_tracking admin-guide/mm/idle_page_tracking +vm/index mm/index +vm/ksm mm/ksm +vm/memory-model mm/memory-model +vm/mmu_notifier mm/mmu_notifier +vm/numa mm/numa +vm/numa_memory_policy admin-guide/mm/numa_memory_policy +vm/oom mm/oom +vm/overcommit-accounting mm/overcommit-accounting +vm/page_allocation mm/page_allocation +vm/page_cache mm/page_cache +vm/page_frags mm/page_frags +vm/page_migration mm/page_migration +vm/page_owner mm/page_owner +vm/page_reclaim mm/page_reclaim +vm/page_table_check mm/page_table_check +vm/page_tables mm/page_tables +vm/pagemap admin-guide/mm/pagemap +vm/physical_memory mm/physical_memory +vm/process_addrs mm/process_addrs +vm/remap_file_pages mm/remap_file_pages +vm/shmfs mm/shmfs +vm/slab mm/slab +vm/slub admin-guide/mm/slab +vm/soft-dirty admin-guide/mm/soft-dirty +vm/split_page_table_lock mm/split_page_table_lock +vm/swap mm/swap +vm/swap_numa admin-guide/mm/swap_numa +vm/transhuge mm/transhuge +vm/unevictable-lru mm/unevictable-lru +vm/userfaultfd admin-guide/mm/userfaultfd +vm/vmalloc mm/vmalloc +vm/vmalloced-kernel-stacks mm/vmalloced-kernel-stacks +vm/vmemmap_dedup mm/vmemmap_dedup +vm/zsmalloc mm/zsmalloc +vm/zswap admin-guide/mm/zswap +watch_queue core-api/watch_queue +x86/amd-memory-encryption arch/x86/amd-memory-encryption +x86/amd_hsmp arch/x86/amd_hsmp +x86/boot arch/x86/boot +x86/booting-dt arch/x86/booting-dt +x86/buslock arch/x86/buslock +x86/cpuinfo arch/x86/cpuinfo +x86/earlyprintk arch/x86/earlyprintk +x86/elf_auxvec arch/x86/elf_auxvec +x86/entry_64 arch/x86/entry_64 +x86/exception-tables arch/x86/exception-tables +x86/features arch/x86/features +x86/i386/IO-APIC arch/x86/i386/IO-APIC +x86/i386/index arch/x86/i386/index +x86/ifs arch/x86/ifs +x86/index arch/x86/index +x86/intel-hfi arch/x86/intel-hfi +x86/intel_txt arch/x86/intel_txt +x86/iommu arch/x86/iommu +x86/kernel-stacks arch/x86/kernel-stacks +x86/mds arch/x86/mds +x86/microcode arch/x86/microcode +x86/mtrr arch/x86/mtrr +x86/orc-unwinder arch/x86/orc-unwinder +x86/pat arch/x86/pat +x86/protection-keys core-api/protection-keys +x86/pti arch/x86/pti +x86/resctrl filesystems/resctrl +x86/resctrl_ui filesystems/resctrl +x86/sgx arch/x86/sgx +x86/sva arch/x86/sva +x86/tdx arch/x86/tdx +x86/tlb arch/x86/tlb +x86/topology arch/x86/topology +x86/tsx_async_abort arch/x86/tsx_async_abort +x86/usb-legacy-support arch/x86/usb-legacy-support +x86/x86_64/5level-paging arch/x86/x86_64/5level-paging +x86/x86_64/cpu-hotplug-spec arch/x86/x86_64/cpu-hotplug-spec +x86/x86_64/fake-numa-for-cpusets arch/x86/x86_64/fake-numa-for-cpusets +x86/x86_64/fsgs arch/x86/x86_64/fsgs +x86/x86_64/index arch/x86/x86_64/index +x86/x86_64/machinecheck arch/x86/x86_64/machinecheck +x86/x86_64/mm arch/x86/x86_64/mm +x86/x86_64/uefi arch/x86/x86_64/uefi +x86/xstate arch/x86/xstate +x86/zero-page arch/x86/zero-page +xilinx/eemi driver-api/xilinx/eemi +xilinx/index driver-api/xilinx/index +xtensa/atomctl arch/xtensa/atomctl +xtensa/booting arch/xtensa/booting +xtensa/features arch/xtensa/features +xtensa/index arch/xtensa/index +xtensa/mmu arch/xtensa/mmu diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index bc0e7fefc39d..b590809869ca 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -822,8 +822,8 @@ What: /sys/fs/f2fs/<disk>/gc_valid_thresh_ratio Date: September 2024 Contact: "Daeho Jeong" <daehojeong@google.com> Description: It controls the valid block ratio threshold not to trigger excessive GC - for zoned deivces. The initial value of it is 95(%). F2FS will stop the - background GC thread from intiating GC for sections having valid blocks + for zoned devices. The initial value of it is 95(%). F2FS will stop the + background GC thread from initiating GC for sections having valid blocks exceeding the ratio. What: /sys/fs/f2fs/<disk>/max_read_extent_count @@ -847,7 +847,7 @@ Description: For several zoned storage devices, vendors will provide extra space filesystem level GC. To do that, we can reserve the space using reserved_blocks. However, it is not enough, since this extra space should not be shown to users. So, with this new sysfs node, we can hide the space - by substracting reserved_blocks from total bytes. + by subtracting reserved_blocks from total bytes. What: /sys/fs/f2fs/<disk>/encoding_flags Date: April 2025 @@ -883,3 +883,53 @@ Date: June 2025 Contact: "Daeho Jeong" <daehojeong@google.com> Description: Control GC algorithm for boost GC. 0: cost benefit, 1: greedy Default: 1 + +What: /sys/fs/f2fs/<disk>/effective_lookup_mode +Date: August 2025 +Contact: "Daniel Lee" <chullee@google.com> +Description: + This is a read-only entry to show the effective directory lookup mode + F2FS is currently using for casefolded directories. + This considers both the "lookup_mode" mount option and the on-disk + encoding flag, SB_ENC_NO_COMPAT_FALLBACK_FL. + + Possible values are: + - "perf": Hash-only lookup. + - "compat": Hash-based lookup with a linear search fallback enabled + - "auto:perf": lookup_mode is auto and fallback is disabled on-disk + - "auto:compat": lookup_mode is auto and fallback is enabled on-disk + +What: /sys/fs/f2fs/<disk>/bggc_io_aware +Date: August 2025 +Contact: "Liao Yuanhong" <liaoyuanhong@vivo.com> +Description: Used to adjust the BG_GC priority when pending IO, with a default value + of 0. Specifically, for ZUFS, the default value is 1. + + ================== ====================================================== + value description + bggc_io_aware = 0 skip background GC if there is any kind of pending IO + bggc_io_aware = 1 skip background GC if there is pending read IO + bggc_io_aware = 2 don't aware IO for background GC + ================== ====================================================== + +What: /sys/fs/f2fs/<disk>/allocate_section_hint +Date: August 2025 +Contact: "Liao Yuanhong" <liaoyuanhong@vivo.com> +Description: Indicates the hint section between the first device and others in multi-devices + setup. It defaults to the end of the first device in sections. For a single storage + device, it defaults to the total number of sections. It can be manually set to match + scenarios where multi-devices are mapped to the same dm device. + +What: /sys/fs/f2fs/<disk>/allocate_section_policy +Date: August 2025 +Contact: "Liao Yuanhong" <liaoyuanhong@vivo.com> +Description: Controls write priority in multi-devices setups. A value of 0 means normal writing. + A value of 1 prioritizes writing to devices before the allocate_section_hint. A value of 2 + prioritizes writing to devices after the allocate_section_hint. The default is 0. + + =========================== ========================================================== + value description + allocate_section_policy = 0 Normal writing + allocate_section_policy = 1 Prioritize writing to section before allocate_section_hint + allocate_section_policy = 2 Prioritize writing to section after allocate_section_hint + =========================== ========================================================== diff --git a/Documentation/Makefile b/Documentation/Makefile index 820f07e0afe6..3609cb86137b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -60,8 +60,8 @@ ifeq ($(HAVE_LATEXMK),1) endif #HAVE_LATEXMK # Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter +PAPEROPT_a4 = -D latex_elements.papersize=a4paper +PAPEROPT_letter = -D latex_elements.papersize=letterpaper ALLSPHINXOPTS = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) ALLSPHINXOPTS += $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ifneq ($(wildcard $(srctree)/.config),) @@ -87,7 +87,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__) quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) - cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ + cmd_sphinx = \ PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \ @@ -108,6 +108,9 @@ htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) +htmldocs-redirects: $(srctree)/Documentation/.renames.txt + @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< + # If Rust support is available and .config exists, add rustdoc generated contents. # If there are any, the errors from this make rustdoc will be displayed but # won't stop the execution of htmldocs @@ -171,11 +174,11 @@ refcheckdocs: cleandocs: $(Q)rm -rf $(BUILDDIR) - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' @echo ' htmldocs - HTML' + @echo ' htmldocs-redirects - generate HTML redirects for moved pages' @echo ' texinfodocs - Texinfo' @echo ' infodocs - Info' @echo ' latexdocs - LaTeX' diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst index fb73345cfb8a..e69c2872ce3b 100644 --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst @@ -86,7 +86,7 @@ The <EPF Device> directory can have a list of symbolic links be created by the user to represent the virtual functions that are bound to the physical function. In the above directory structure <EPF Device 11> is a physical function and <EPF Device 31> is a virtual function. An EPF device once -it's linked to another EPF device, cannot be linked to a EPC device. +it's linked to another EPF device, cannot be linked to an EPC device. EPC Device ========== @@ -108,7 +108,7 @@ entries corresponding to EPC device will be created by the EPC core. The <EPC Device> directory will have a list of symbolic links to <EPF Device>. These symbolic links should be created by the user to represent the functions present in the endpoint device. Only <EPF Device> -that represents a physical function can be linked to a EPC device. +that represents a physical function can be linked to an EPC device. The <EPC Device> directory will also have a *start* field. Once "1" is written to this field, the endpoint device will be ready to diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst b/Documentation/PCI/endpoint/pci-endpoint.rst index 599763aa01ca..0741c8cbd74e 100644 --- a/Documentation/PCI/endpoint/pci-endpoint.rst +++ b/Documentation/PCI/endpoint/pci-endpoint.rst @@ -197,8 +197,8 @@ by the PCI endpoint function driver. * pci_epf_register_driver() The PCI Endpoint Function driver should implement the following ops: - * bind: ops to perform when a EPC device has been bound to EPF device - * unbind: ops to perform when a binding has been lost between a EPC + * bind: ops to perform when an EPC device has been bound to EPF device + * unbind: ops to perform when a binding has been lost between an EPC device and EPF device * add_cfs: optional ops to create function specific configfs attributes @@ -251,7 +251,7 @@ pci-ep-cfs.c can be used as reference for using these APIs. * pci_epf_bind() pci_epf_bind() should be invoked when the EPF device has been bound to - a EPC device. + an EPC device. * pci_epf_unbind() diff --git a/Documentation/RCU/lockdep.rst b/Documentation/RCU/lockdep.rst index 69e73a39bd11..741b157bbacb 100644 --- a/Documentation/RCU/lockdep.rst +++ b/Documentation/RCU/lockdep.rst @@ -106,7 +106,7 @@ or the RCU-protected data that it points to can change concurrently. Like rcu_dereference(), when lockdep is enabled, RCU list and hlist traversal primitives check for being called from within an RCU read-side critical section. However, a lockdep expression can be passed to them -as a additional optional argument. With this lockdep expression, these +as an additional optional argument. With this lockdep expression, these traversal primitives will complain only if the lockdep expression is false and they are called from outside any RCU read-side critical section. diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index d1ccd6039a8c..d7c8eff63317 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -119,7 +119,7 @@ warnings: uncommon in large datacenter. In one memorable case some decades back, a CPU failed in a running system, becoming unresponsive, but not causing an immediate crash. This resulted in a series - of RCU CPU stall warnings, eventually leading the realization + of RCU CPU stall warnings, eventually leading to the realization that the CPU had failed. The RCU, RCU-sched, RCU-tasks, and RCU-tasks-trace implementations have diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst index 0ec34863c674..6d439c987563 100644 --- a/Documentation/admin-guide/LSM/SafeSetID.rst +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -41,7 +41,7 @@ namespace). The higher level goal is to allow for uid-based sandboxing of system services without having to give out CAP_SETUID all over the place just so that non-root programs can drop to even-lesser-privileged uids. This is especially relevant when one non-root daemon on the system should be allowed to spawn other -processes as different uids, but its undesirable to give the daemon a +processes as different uids, but it's undesirable to give the daemon a basically-root-equivalent CAP_SETUID. diff --git a/Documentation/admin-guide/RAS/main.rst b/Documentation/admin-guide/RAS/main.rst index 7ac1d4ccc509..447bfde509fb 100644 --- a/Documentation/admin-guide/RAS/main.rst +++ b/Documentation/admin-guide/RAS/main.rst @@ -253,7 +253,7 @@ interface. Some architectures have ECC detectors for L1, L2 and L3 caches, along with DMA engines, fabric switches, main data path switches, interconnections, and various other hardware data paths. If the hardware -reports it, then a edac_device device probably can be constructed to +reports it, then an edac_device device probably can be constructed to harvest and present that to userspace. diff --git a/Documentation/admin-guide/aoe/udev.txt b/Documentation/admin-guide/aoe/udev.txt index 5fb756466bc7..d55ecb411c21 100644 --- a/Documentation/admin-guide/aoe/udev.txt +++ b/Documentation/admin-guide/aoe/udev.txt @@ -2,7 +2,7 @@ # They may be installed along the following lines. Check the section # 8 udev manpage to see whether your udev supports SUBSYSTEM, and # whether it uses one or two equal signs for SUBSYSTEM and KERNEL. -# +# # ecashin@makki ~$ su # Password: # bash# find /etc -type f -name udev.conf @@ -13,7 +13,7 @@ # 10-wacom.rules 50-udev.rules # bash# cp /path/to/linux/Documentation/admin-guide/aoe/udev.txt \ # /etc/udev/rules.d/60-aoe.rules -# +# # aoe char devices SUBSYSTEM=="aoe", KERNEL=="discover", NAME="etherd/%k", GROUP="disk", MODE="0220" @@ -22,5 +22,5 @@ SUBSYSTEM=="aoe", KERNEL=="interfaces", NAME="etherd/%k", GROUP="disk", MODE="02 SUBSYSTEM=="aoe", KERNEL=="revalidate", NAME="etherd/%k", GROUP="disk", MODE="0220" SUBSYSTEM=="aoe", KERNEL=="flush", NAME="etherd/%k", GROUP="disk", MODE="0220" -# aoe block devices +# aoe block devices KERNEL=="etherd*", GROUP="disk" diff --git a/Documentation/admin-guide/blockdev/paride.rst b/Documentation/admin-guide/blockdev/paride.rst index e85ad37cc0e5..b2f627d4c2f8 100644 --- a/Documentation/admin-guide/blockdev/paride.rst +++ b/Documentation/admin-guide/blockdev/paride.rst @@ -118,7 +118,7 @@ and high-level drivers that you would use: ================ ============ ======== All parports and all protocol drivers are probed automatically unless probe=0 -parameter is used. So just "modprobe epat" is enough for a Imation SuperDisk +parameter is used. So just "modprobe epat" is enough for an Imation SuperDisk drive to work. Manual device creation:: diff --git a/Documentation/admin-guide/device-mapper/delay.rst b/Documentation/admin-guide/device-mapper/delay.rst index 4d667228e744..a1e673c0e782 100644 --- a/Documentation/admin-guide/device-mapper/delay.rst +++ b/Documentation/admin-guide/device-mapper/delay.rst @@ -3,7 +3,7 @@ dm-delay ======== Device-Mapper's "delay" target delays reads and/or writes -and/or flushs and optionally maps them to different devices. +and/or flushes and optionally maps them to different devices. Arguments:: @@ -18,7 +18,7 @@ Table line has to either have 3, 6 or 9 arguments: to write and flush operations on optionally different write_device with optionally different sector offset -9: same as 6 arguments plus define flush_offset and flush_delay explicitely +9: same as 6 arguments plus define flush_offset and flush_delay explicitly on/with optionally different flush_device/flush_offset. Offsets are specified in sectors. @@ -40,7 +40,7 @@ Example scripts #!/bin/sh # # Create mapped device delaying write and flush operations for 400ms and - # splitting reads to device $1 but writes and flushs to different device $2 + # splitting reads to device $1 but writes and flushes to different device $2 # to different offsets of 2048 and 4096 sectors respectively. # dmsetup create delayed --table "0 `blockdev --getsz $1` delay $1 2048 0 $2 4096 400" @@ -48,7 +48,7 @@ Example scripts :: #!/bin/sh # - # Create mapped device delaying reads for 50ms, writes for 100ms and flushs for 333ms + # Create mapped device delaying reads for 50ms, writes for 100ms and flushes for 333ms # onto the same backing device at offset 0 sectors. # dmsetup create delayed --table "0 `blockdev --getsz $1` delay $1 0 50 $2 0 100 $1 0 333" diff --git a/Documentation/admin-guide/device-mapper/dm-pcache.rst b/Documentation/admin-guide/device-mapper/dm-pcache.rst new file mode 100644 index 000000000000..09d327ef4b14 --- /dev/null +++ b/Documentation/admin-guide/device-mapper/dm-pcache.rst @@ -0,0 +1,202 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +dm-pcache — Persistent Cache +================================= + +*Author: Dongsheng Yang <dongsheng.yang@linux.dev>* + +This document describes *dm-pcache*, a Device-Mapper target that lets a +byte-addressable *DAX* (persistent-memory, “pmem”) region act as a +high-performance, crash-persistent cache in front of a slower block +device. The code lives in `drivers/md/dm-pcache/`. + +Quick feature summary +===================== + +* *Write-back* caching (only mode currently supported). +* *16 MiB segments* allocated on the pmem device. +* *Data CRC32* verification (optional, per cache). +* Crash-safe: every metadata structure is duplicated (`PCACHE_META_INDEX_MAX + == 2`) and protected with CRC+sequence numbers. +* *Multi-tree indexing* (indexing trees sharded by logical address) for high PMem parallelism +* Pure *DAX path* I/O – no extra BIO round-trips +* *Log-structured write-back* that preserves backend crash-consistency + + +Constructor +=========== + +:: + + pcache <cache_dev> <backing_dev> [<number_of_optional_arguments> <cache_mode writeback> <data_crc true|false>] + +========================= ==================================================== +``cache_dev`` Any DAX-capable block device (``/dev/pmem0``…). + All metadata *and* cached blocks are stored here. + +``backing_dev`` The slow block device to be cached. + +``cache_mode`` Optional, Only ``writeback`` is accepted at the + moment. + +``data_crc`` Optional, default to ``false`` + + * ``true`` – store CRC32 for every cached entry + and verify on reads + * ``false`` – skip CRC (faster) +========================= ==================================================== + +Example +------- + +.. code-block:: shell + + dmsetup create pcache_sdb --table \ + "0 $(blockdev --getsz /dev/sdb) pcache /dev/pmem0 /dev/sdb 4 cache_mode writeback data_crc true" + +The first time a pmem device is used, dm-pcache formats it automatically +(super-block, cache_info, etc.). + + +Status line +=========== + +``dmsetup status <device>`` (``STATUSTYPE_INFO``) prints: + +:: + + <sb_flags> <seg_total> <cache_segs> <segs_used> \ + <gc_percent> <cache_flags> \ + <key_head_seg>:<key_head_off> \ + <dirty_tail_seg>:<dirty_tail_off> \ + <key_tail_seg>:<key_tail_off> + +Field meanings +-------------- + +=============================== ============================================= +``sb_flags`` Super-block flags (e.g. endian marker). + +``seg_total`` Number of physical *pmem* segments. + +``cache_segs`` Number of segments used for cache. + +``segs_used`` Segments currently allocated (bitmap weight). + +``gc_percent`` Current GC high-water mark (0-90). + +``cache_flags`` Bit 0 – DATA_CRC enabled + Bit 1 – INIT_DONE (cache initialised) + Bits 2-5 – cache mode (0 == WB). + +``key_head`` Where new key-sets are being written. + +``dirty_tail`` First dirty key-set that still needs + write-back to the backing device. + +``key_tail`` First key-set that may be reclaimed by GC. +=============================== ============================================= + + +Messages +======== + +*Change GC trigger* + +:: + + dmsetup message <dev> 0 gc_percent <0-90> + + +Theory of operation +=================== + +Sub-devices +----------- + +==================== ========================================================= +backing_dev Any block device (SSD/HDD/loop/LVM, etc.). +cache_dev DAX device; must expose direct-access memory. +==================== ========================================================= + +Segments and key-sets +--------------------- + +* The pmem space is divided into *16 MiB segments*. +* Each write allocates space from a per-CPU *data_head* inside a segment. +* A *cache-key* records a logical range on the origin and where it lives + inside pmem (segment + offset + generation). +* 128 keys form a *key-set* (kset); ksets are written sequentially in pmem + and are themselves crash-safe (CRC). +* The pair *(key_tail, dirty_tail)* delimit clean/dirty and live/dead ksets. + +Write-back +---------- + +Dirty keys are queued into a tree; a background worker copies data +back to the backing_dev and advances *dirty_tail*. A FLUSH/FUA bio from the +upper layers forces an immediate metadata commit. + +Garbage collection +------------------ + +GC starts when ``segs_used >= seg_total * gc_percent / 100``. It walks +from *key_tail*, frees segments whose every key has been invalidated, and +advances *key_tail*. + +CRC verification +---------------- + +If ``data_crc is enabled`` dm-pcache computes a CRC32 over every cached data +range when it is inserted and stores it in the on-media key. Reads +validate the CRC before copying to the caller. + + +Failure handling +================ + +* *pmem media errors* – all metadata copies are read with + ``copy_mc_to_kernel``; an uncorrectable error logs and aborts initialisation. +* *Cache full* – if no free segment can be found, writes return ``-EBUSY``; + dm-pcache retries internally (request deferral). +* *System crash* – on attach, the driver replays ksets from *key_tail* to + rebuild the in-core trees; every segment’s generation guards against + use-after-free keys. + + +Limitations & TODO +================== + +* Only *write-back* mode; other modes planned. +* Only FIFO cache invalidate; other (LRU, ARC...) planned. +* Table reload is not supported currently. +* Discard planned. + + +Example workflow +================ + +.. code-block:: shell + + # 1. Create devices + dmsetup create pcache_sdb --table \ + "0 $(blockdev --getsz /dev/sdb) pcache /dev/pmem0 /dev/sdb 4 cache_mode writeback data_crc true" + + # 2. Put a filesystem on top + mkfs.ext4 /dev/mapper/pcache_sdb + mount /dev/mapper/pcache_sdb /mnt + + # 3. Tune GC threshold to 80 % + dmsetup message pcache_sdb 0 gc_percent 80 + + # 4. Observe status + watch -n1 'dmsetup status pcache_sdb' + + # 5. Shutdown + umount /mnt + dmsetup remove pcache_sdb + + +``dm-pcache`` is under active development; feedback, bug reports and patches +are very welcome! diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index cc5aec861576..f1c1f4b824ba 100644 --- a/Documentation/admin-guide/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -18,6 +18,7 @@ Device Mapper dm-integrity dm-io dm-log + dm-pcache dm-queue-length dm-raid dm-service-time diff --git a/Documentation/admin-guide/device-mapper/vdo-design.rst b/Documentation/admin-guide/device-mapper/vdo-design.rst index 3cd59decbec0..faa0ecd4a5ae 100644 --- a/Documentation/admin-guide/device-mapper/vdo-design.rst +++ b/Documentation/admin-guide/device-mapper/vdo-design.rst @@ -600,7 +600,7 @@ lock and return itself to the pool. All storage within vdo is managed as 4KB blocks, but it can accept writes as small as 512 bytes. Processing a write that is smaller than 4K requires a read-modify-write operation that reads the relevant 4K block, copies the -new data over the approriate sectors of the block, and then launches a +new data over the appropriate sectors of the block, and then launches a write operation for the modified data block. The read and write stages of this operation are nearly identical to the normal read and write operations, and a single data_vio is used throughout this operation. diff --git a/Documentation/admin-guide/device-mapper/vdo.rst b/Documentation/admin-guide/device-mapper/vdo.rst index a14e6d3e787c..8a67b320a97b 100644 --- a/Documentation/admin-guide/device-mapper/vdo.rst +++ b/Documentation/admin-guide/device-mapper/vdo.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0-only +====== dm-vdo ====== diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst index b857eb6ca1b6..ac0c709ea9e7 100644 --- a/Documentation/admin-guide/ext4.rst +++ b/Documentation/admin-guide/ext4.rst @@ -398,7 +398,7 @@ There are 3 different data modes: * writeback mode In data=writeback mode, ext4 does not journal data at all. This mode provides - a similar level of journaling as that of XFS, JFS, and ReiserFS in its default + a similar level of journaling as that of XFS and JFS in its default mode - metadata journaling. A crash+recovery can cause incorrect data to appear in files which were written shortly before the crash. This mode will typically provide the best ext4 performance. diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst index 48c7b0b72aed..754679db0ce8 100644 --- a/Documentation/admin-guide/hw-vuln/mds.rst +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -214,7 +214,7 @@ XEON PHI specific considerations command line with the 'ring3mwait=disable' command line option. XEON PHI is not affected by the other MDS variants and MSBDS is mitigated - before the CPU enters a idle state. As XEON PHI is not affected by L1TF + before the CPU enters an idle state. As XEON PHI is not affected by L1TF either disabling SMT is not required for full protection. .. _mds_smt_control: diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index 132e0bc6007e..991f12adef8d 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -664,7 +664,7 @@ Intel white papers: .. _spec_ref1: -[1] `Intel analysis of speculative execution side channels <https://newsroom.intel.com/wp-content/uploads/sites/11/2018/01/Intel-Analysis-of-Speculative-Execution-Side-Channels.pdf>`_. +[1] `Intel analysis of speculative execution side channels <https://www.intel.com/content/dam/www/public/us/en/documents/white-papers/analysis-of-speculative-execution-side-channels-white-paper.pdf>`_. .. _spec_ref2: @@ -682,7 +682,7 @@ AMD white papers: .. _spec_ref5: -[5] `AMD64 technology indirect branch control extension <https://developer.amd.com/wp-content/resources/Architecture_Guidelines_Update_Indirect_Branch_Control.pdf>`_. +[5] `AMD64 technology indirect branch control extension <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/white-papers/111006-architecture-guidelines-update-amd64-technology-indirect-branch-control-extension.pdf>`_. .. _spec_ref6: @@ -708,7 +708,7 @@ MIPS white paper: .. _spec_ref10: -[10] `MIPS: response on speculative execution and side channel vulnerabilities <https://www.mips.com/blog/mips-response-on-speculative-execution-and-side-channel-vulnerabilities/>`_. +[10] `MIPS: response on speculative execution and side channel vulnerabilities <https://web.archive.org/web/20220512003005if_/https://www.mips.com/blog/mips-response-on-speculative-execution-and-side-channel-vulnerabilities/>`_. Academic papers: diff --git a/Documentation/admin-guide/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst index 9c6cd52f69cf..7b011eb116a7 100644 --- a/Documentation/admin-guide/kdump/kdump.rst +++ b/Documentation/admin-guide/kdump/kdump.rst @@ -471,7 +471,7 @@ Notes on loading the dump-capture kernel: performance degradation. To enable multi-cpu support, you should bring up an SMP dump-capture kernel and specify maxcpus/nr_cpus options while loading it. -* For s390x there are two kdump modes: If a ELF header is specified with +* For s390x there are two kdump modes: If an ELF header is specified with the elfcorehdr= kernel parameter, it is used by the kdump kernel as it is done on all other architectures. If no elfcorehdr= kernel parameter is specified, the s390x kdump kernel dynamically creates the header. The diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 39d0e7ff0965..7bf8cc7df6b5 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _kernelparameters: The kernel's command-line parameters @@ -213,7 +215,7 @@ need or coordination with <Documentation/arch/x86/boot.rst>. There are also arch-specific kernel-parameters not documented here. Note that ALL kernel parameters listed below are CASE SENSITIVE, and that -a trailing = on the name of any parameter states that that parameter will +a trailing = on the name of any parameter states that the parameter will be entered as an environment variable, whereas its absence indicates that it will appear as a kernel argument readable via /proc/cmdline by programs running once the system is up. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 74ca438d2d6d..3edc5ce0e2a3 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -3705,7 +3705,7 @@ looking for corruption. Enabling this will both detect corruption and prevent the kernel from using the memory being corrupted. - However, its intended as a diagnostic tool; if + However, it's intended as a diagnostic tool; if repeatable BIOS-originated corruption always affects the same memory, you can use memmap= to prevent the kernel from using that memory. @@ -7400,7 +7400,7 @@ (converted into nanoseconds). Fast, but depending on the architecture, may not be in sync between CPUs. - global - Event time stamps are synchronize across + global - Event time stamps are synchronized across CPUs. May be slower than the local clock, but better for some race conditions. counter - Simple counting of events (1, 2, ..) @@ -7520,12 +7520,12 @@ section. trace_trigger=[trigger-list] - [FTRACE] Add a event trigger on specific events. + [FTRACE] Add an event trigger on specific events. Set a trigger on top of a specific event, with an optional filter. - The format is is "trace_trigger=<event>.<trigger>[ if <filter>],..." - Where more than one trigger may be specified that are comma deliminated. + The format is "trace_trigger=<event>.<trigger>[ if <filter>],..." + Where more than one trigger may be specified that are comma delimited. For example: @@ -7533,7 +7533,7 @@ The above will enable the "stacktrace" trigger on the "sched_switch" event but only trigger it if the "prev_state" of the "sched_switch" - event is "2" (TASK_UNINTERUPTIBLE). + event is "2" (TASK_UNINTERRUPTIBLE). See also "Event triggers" in Documentation/trace/events.rst diff --git a/Documentation/admin-guide/laptops/laptop-mode.rst b/Documentation/admin-guide/laptops/laptop-mode.rst index b61cc601d298..66eb9cd918b5 100644 --- a/Documentation/admin-guide/laptops/laptop-mode.rst +++ b/Documentation/admin-guide/laptops/laptop-mode.rst @@ -61,7 +61,7 @@ Caveats Check your drive's rating, and don't wear down your drive's lifetime if you don't need to. -* If you mount some of your ext3/reiserfs filesystems with the -n option, then +* If you mount some of your ext3 filesystems with the -n option, then the control script will not be able to remount them correctly. You must set DO_REMOUNTS=0 in the control script, otherwise it will remount them with the wrong options -- or it will fail because it cannot write to /etc/mtab. @@ -96,7 +96,7 @@ control script increases dirty_expire_centisecs and dirty_writeback_centisecs in dirtied are not forced to be written to disk as often. The control script also changes the dirty background ratio, so that background writeback of dirty pages is not done anymore. Combined with a higher commit value (also 10 minutes) for -ext3 or ReiserFS filesystems (also done automatically by the control script), +ext3 filesystem (also done automatically by the control script), this results in concentration of disk activity in a small time interval which occurs only once every 10 minutes, or whenever the disk is forced to spin up by a cache miss. The disk can then be spun down in the periods of inactivity. @@ -587,7 +587,7 @@ Control script:: FST=$(deduce_fstype $MP) fi case "$FST" in - "ext3"|"reiserfs") + "ext3") PARSEDOPTS="$(parse_mount_opts commit "$OPTS")" mount $DEV -t $FST $MP -o remount,$PARSEDOPTS,commit=$MAX_AGE$NOATIME_OPT ;; @@ -647,7 +647,7 @@ Control script:: FST=$(deduce_fstype $MP) fi case "$FST" in - "ext3"|"reiserfs") + "ext3") PARSEDOPTS="$(parse_mount_opts_wfstab $DEV commit $OPTS)" PARSEDOPTS="$(parse_yesno_opts_wfstab $DEV atime atime $PARSEDOPTS)" mount $DEV -t $FST $MP -o remount,$PARSEDOPTS diff --git a/Documentation/admin-guide/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst index 190da1234314..7541f56e0007 100644 --- a/Documentation/admin-guide/laptops/sonypi.rst +++ b/Documentation/admin-guide/laptops/sonypi.rst @@ -25,7 +25,7 @@ generate, like: (when available) Those events (see linux/sonypi.h) can be polled using the character device node -/dev/sonypi (major 10, minor auto allocated or specified as a option). +/dev/sonypi (major 10, minor auto allocated or specified as an option). A simple daemon which translates the jogdial movements into mouse wheel events can be downloaded at: <http://popies.net/sonypi/> diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index 1c2eacc94758..deed823eab01 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -794,7 +794,7 @@ These currently include: journal_mode (currently raid5 only) The cache mode for raid5. raid5 could include an extra disk for - caching. The mode can be "write-throuth" and "write-back". The + caching. The mode can be "write-through" or "write-back". The default is "write-through". ppl_write_hint diff --git a/Documentation/admin-guide/media/imx.rst b/Documentation/admin-guide/media/imx.rst index b8fa70f854fd..bb68100d8acb 100644 --- a/Documentation/admin-guide/media/imx.rst +++ b/Documentation/admin-guide/media/imx.rst @@ -96,7 +96,7 @@ Some of the features of this driver include: motion compensation modes: low, medium, and high motion. Pipelines are defined that allow sending frames to the VDIC subdev directly from the CSI. There is also support in the future for sending frames to the - VDIC from memory buffers via a output/mem2mem devices. + VDIC from memory buffers via output/mem2mem devices. - Includes a Frame Interval Monitor (FIM) that can correct vertical sync problems with the ADV718x video decoders. diff --git a/Documentation/admin-guide/media/si4713.rst b/Documentation/admin-guide/media/si4713.rst index be8e6b49b7b4..85dcf1cd2df8 100644 --- a/Documentation/admin-guide/media/si4713.rst +++ b/Documentation/admin-guide/media/si4713.rst @@ -13,7 +13,7 @@ Contact: Eduardo Valentin <eduardo.valentin@nokia.com> Information about the Device ---------------------------- -This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address. +This chip is a Silicon Labs product. It is an I2C device, currently on 0x63 address. Basically, it has transmission and signal noise level measurement features. The Si4713 integrates transmit functions for FM broadcast stereo transmission. @@ -28,7 +28,7 @@ Users must comply with local regulations on radio frequency (RF) transmission. Device driver description ------------------------- -There are two modules to handle this device. One is a I2C device driver +There are two modules to handle this device. One is an I2C device driver and the other is a platform driver. The I2C device driver exports a v4l2-subdev interface to the kernel. @@ -113,7 +113,7 @@ Here is a summary of them: - acomp_attack_time - Sets the attack time for audio dynamic range control. - acomp_release_time - Sets the release time for audio dynamic range control. -* Limiter setups audio deviation limiter feature. Once a over deviation occurs, +* Limiter sets up the audio deviation limiter feature. Once an over deviation occurs, it is possible to adjust the front-end gain of the audio input and always prevent over deviation. diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index 2cae60b6f3ca..eae534bc1bee 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -360,7 +360,7 @@ The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given DAMON-based operation scheme. Under ``quotas`` directory, four files (``ms``, ``bytes``, -``reset_interval_ms``, ``effective_bytes``) and two directores (``weights`` and +``reset_interval_ms``, ``effective_bytes``) and two directories (``weights`` and ``goals``) exist. You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and diff --git a/Documentation/admin-guide/nfs/nfsroot.rst b/Documentation/admin-guide/nfs/nfsroot.rst index 135218f33394..06990309c6ff 100644 --- a/Documentation/admin-guide/nfs/nfsroot.rst +++ b/Documentation/admin-guide/nfs/nfsroot.rst @@ -342,7 +342,7 @@ They depend on various facilities being available: When using pxelinux, the kernel image is specified using "kernel <relative-path-below /tftpboot>". The nfsroot parameters are passed to the kernel by adding them to the "append" line. - It is common to use serial console in conjunction with pxeliunx, + It is common to use serial console in conjunction with pxelinux, see Documentation/admin-guide/serial-console.rst for more information. For more information on isolinux, including how to create bootdisks diff --git a/Documentation/admin-guide/perf/hisi-pmu.rst b/Documentation/admin-guide/perf/hisi-pmu.rst index c4c2cbbf88cb..f3d9871906a2 100644 --- a/Documentation/admin-guide/perf/hisi-pmu.rst +++ b/Documentation/admin-guide/perf/hisi-pmu.rst @@ -110,8 +110,8 @@ uring channel. It is 2 bits. Some important codes are as follows: - 2'b11: count the events which sent to the uring_ext (MATA) channel; - 2'b01: is the same as 2'b11; - 2'b10: count the events which sent to the uring (non-MATA) channel; -- 2'b00: default value, count the events which sent to the both uring and - uring_ext channel; +- 2'b00: default value, count the events which sent to both uring and + uring_ext channels; 6. ch: NoC PMU supports filtering the event counts of certain transaction channel with this option. The current supported channels are as follows: diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst b/Documentation/admin-guide/quickly-build-trimmed-linux.rst index 4a5ffb0996a3..cb4b78468a93 100644 --- a/Documentation/admin-guide/quickly-build-trimmed-linux.rst +++ b/Documentation/admin-guide/quickly-build-trimmed-linux.rst @@ -273,7 +273,7 @@ again. does nothing at all; in that case you have to manually install your kernel, as outlined in the reference section. - If you are running a immutable Linux distribution, check its documentation + If you are running an immutable Linux distribution, check its documentation and the web to find out how to install your own kernel there. [:ref:`details<install>`] @@ -884,7 +884,7 @@ When a build error occurs, it might be caused by some aspect of your machine's setup that often can be fixed quickly; other times though the problem lies in the code and can only be fixed by a developer. A close examination of the failure messages coupled with some research on the internet will often tell you -which of the two it is. To perform such a investigation, restart the build +which of the two it is. To perform such an investigation, restart the build process like this:: make V=1 diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index 9a847506f6ec..a68e6d909274 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -611,7 +611,7 @@ better place. How to read the MAINTAINERS file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To illustrate how to use the :ref:`MAINTAINERS <maintainers>` file, lets assume +To illustrate how to use the :ref:`MAINTAINERS <maintainers>` file, let's assume the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that case it's likely an issue in the WiFi driver. Obviously it could also be some code it builds upon, but unless you suspect something like that stick to the @@ -1543,7 +1543,7 @@ as well, because that will speed things up. And note, it helps developers a great deal if you can specify the exact version that introduced the problem. Hence if possible within a reasonable time frame, -try to find that version using vanilla kernels. Lets assume something broke when +try to find that version using vanilla kernels. Let's assume something broke when your distributor released a update from Linux kernel 5.10.5 to 5.10.8. Then as instructed above go and check the latest kernel from that version line, say 5.10.9. If it shows the problem, try a vanilla 5.10.5 to ensure that no patches diff --git a/Documentation/admin-guide/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst index 6c54718c9d04..9b7f65c3efd8 100644 --- a/Documentation/admin-guide/sysctl/fs.rst +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -164,8 +164,8 @@ pipe-user-pages-soft -------------------- Maximum total number of pages a non-privileged user may allocate for pipes -before the pipe size gets limited to a single page. Once this limit is reached, -new pipes will be limited to a single page in size for this user in order to +before the pipe size gets limited to two pages. Once this limit is reached, +new pipes will be limited to two pages in size for this user in order to limit total memory usage, and trying to increase them using ``fcntl()`` will be denied until usage goes below the limit again. The default value allows to allocate up to 1024 pipes at their default size. When set to 0, no limit is diff --git a/Documentation/admin-guide/sysctl/index.rst b/Documentation/admin-guide/sysctl/index.rst index 03346f98c7b9..4dd2c9b5d752 100644 --- a/Documentation/admin-guide/sysctl/index.rst +++ b/Documentation/admin-guide/sysctl/index.rst @@ -66,25 +66,31 @@ This documentation is about: =============== =============================================================== abi/ execution domains & personalities -debug/ <empty> -dev/ device specific information (eg dev/cdrom/info) +<$ARCH> tuning controls for various CPU architecture (e.g. csky, s390) +crypto/ <undocumented> +debug/ <undocumented> +dev/ device specific information (e.g. dev/cdrom/info) fs/ specific filesystems filehandle, inode, dentry and quota tuning binfmt_misc <Documentation/admin-guide/binfmt-misc.rst> kernel/ global kernel info / tuning miscellaneous stuff + some architecture-specific controls + security (LSM) stuff net/ networking stuff, for documentation look in: <Documentation/networking/> proc/ <empty> sunrpc/ SUN Remote Procedure Call (NFS) +user/ Per user namespace limits vm/ memory management tuning buffer and cache management -user/ Per user per user namespace limits +xen/ <undocumented> =============== =============================================================== -These are the subdirs I have on my system. There might be more -or other subdirs in another setup. If you see another dir, I'd -really like to hear about it :-) +These are the subdirs I have on my system or have been discovered by +searching through the source code. There might be more or other subdirs +in another setup. If you see another dir, I'd really like to hear about +it :-) .. toctree:: :maxdepth: 1 diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst index d8946b084b1e..d83601f2a459 100644 --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst @@ -1757,7 +1757,7 @@ or all of these tasks: to your bootloader's configuration. You have to take care of some or all of the tasks yourself, if your -distribution lacks a installkernel script or does only handle part of them. +distribution lacks an installkernel script or does only handle part of them. Consult the distribution's documentation for details. If in doubt, install the kernel manually:: diff --git a/Documentation/arch/arm/stm32/stm32f746-overview.rst b/Documentation/arch/arm/stm32/stm32f746-overview.rst index 78befddc7740..335f0855a858 100644 --- a/Documentation/arch/arm/stm32/stm32f746-overview.rst +++ b/Documentation/arch/arm/stm32/stm32f746-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support - Ethernet controller - USB OTFG FS & HS controllers -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32f769-overview.rst b/Documentation/arch/arm/stm32/stm32f769-overview.rst index e482980ddf21..ef31aadee68f 100644 --- a/Documentation/arch/arm/stm32/stm32f769-overview.rst +++ b/Documentation/arch/arm/stm32/stm32f769-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support*2 - Ethernet controller - USB OTFG FS & HS controllers -- I2C*4, SPI*6, CAN*3 busses support +- I2C*4, SPI*6, CAN*3 buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface*2 - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32h743-overview.rst b/Documentation/arch/arm/stm32/stm32h743-overview.rst index 4e15f1a42730..7659df24d362 100644 --- a/Documentation/arch/arm/stm32/stm32h743-overview.rst +++ b/Documentation/arch/arm/stm32/stm32h743-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support - Ethernet controller - USB OTFG FS & HS controllers -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32h750-overview.rst b/Documentation/arch/arm/stm32/stm32h750-overview.rst index 0e51235c9547..be032b77d1f1 100644 --- a/Documentation/arch/arm/stm32/stm32h750-overview.rst +++ b/Documentation/arch/arm/stm32/stm32h750-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support - Ethernet controller - USB OTFG FS & HS controllers -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32mp13-overview.rst b/Documentation/arch/arm/stm32/stm32mp13-overview.rst index 3bb9492dad49..b5e9589fb06f 100644 --- a/Documentation/arch/arm/stm32/stm32mp13-overview.rst +++ b/Documentation/arch/arm/stm32/stm32mp13-overview.rst @@ -24,7 +24,7 @@ More details: - ADC/DAC - USB EHCI/OHCI controllers - USB OTG -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32mp151-overview.rst b/Documentation/arch/arm/stm32/stm32mp151-overview.rst index f42a2ac309c0..b58c256ede9a 100644 --- a/Documentation/arch/arm/stm32/stm32mp151-overview.rst +++ b/Documentation/arch/arm/stm32/stm32mp151-overview.rst @@ -23,7 +23,7 @@ More details: - ADC/DAC - USB EHCI/OHCI controllers - USB OTG -- I2C, SPI busses support +- I2C, SPI buses support - Several general purpose timers - Serial Audio interface - LCD-TFT controller diff --git a/Documentation/arch/loongarch/irq-chip-model.rst b/Documentation/arch/loongarch/irq-chip-model.rst index a7ecce11e445..8f5c3345109e 100644 --- a/Documentation/arch/loongarch/irq-chip-model.rst +++ b/Documentation/arch/loongarch/irq-chip-model.rst @@ -139,13 +139,13 @@ Feature EXTIOI_HAS_INT_ENCODE is part of standard EIOINTC. If it is 1, it indicates that CPU Interrupt Pin selection can be normal method rather than bitmap method, so interrupt can be routed to IP0 - IP15. -Feature EXTIOI_HAS_CPU_ENCODE is entension of V-EIOINTC. If it is 1, it +Feature EXTIOI_HAS_CPU_ENCODE is extension of V-EIOINTC. If it is 1, it indicates that CPU selection can be normal method rather than bitmap method, so interrupt can be routed to CPU0 - CPU255. EXTIOI_VIRT_CONFIG ------------------ -This register is read-write register, for compatibility intterupt routed uses +This register is read-write register, for compatibility interrupt routed uses the default method which is the same with standard EIOINTC. If the bit is set with 1, it indicated HW to use normal method rather than bitmap method. diff --git a/Documentation/arch/powerpc/eeh-pci-error-recovery.rst b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst index d6643a91bdf8..153d0af055b6 100644 --- a/Documentation/arch/powerpc/eeh-pci-error-recovery.rst +++ b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst @@ -315,7 +315,6 @@ network daemons and file systems that didn't need to be disturbed. ideally, the reset should happen at or below the block layer, so that the file systems are not disturbed. - Reiserfs does not tolerate errors returned from the block device. Ext3fs seems to be tolerant, retrying reads/writes until it does succeed. Both have been only lightly tested in this scenario. diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst index dd8b7806944e..9f2e47c4b1c8 100644 --- a/Documentation/arch/x86/cpuinfo.rst +++ b/Documentation/arch/x86/cpuinfo.rst @@ -11,7 +11,7 @@ The list of feature flags in /proc/cpuinfo is not complete and represents an ill-fated attempt from long time ago to put feature flags in an easy to find place for userspace. -However, the amount of feature flags is growing by the CPU generation, +However, the number of feature flags is growing with each CPU generation, leading to unparseable and unwieldy /proc/cpuinfo. What is more, those feature flags do not even need to be in that file diff --git a/Documentation/arch/x86/tdx.rst b/Documentation/arch/x86/tdx.rst index 719043cd8b46..61670e7df2f7 100644 --- a/Documentation/arch/x86/tdx.rst +++ b/Documentation/arch/x86/tdx.rst @@ -142,13 +142,6 @@ but depends on the BIOS to behave correctly. Note TDX works with CPU logical online/offline, thus the kernel still allows to offline logical CPU and online it again. -Kexec() -~~~~~~~ - -TDX host support currently lacks the ability to handle kexec. For -simplicity only one of them can be enabled in the Kconfig. This will be -fixed in the future. - Erratum ~~~~~~~ @@ -171,6 +164,13 @@ If the platform has such erratum, the kernel prints additional message in machine check handler to tell user the machine check may be caused by kernel bug on TDX private memory. +Kexec +~~~~~~~ + +Currently kexec doesn't work on the TDX platforms with the aforementioned +erratum. It fails when loading the kexec kernel image. Otherwise it +works normally. + Interaction vs S3 and deeper states ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/conf.py b/Documentation/conf.py index f9828f3862f9..574896cca198 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -9,6 +9,8 @@ import os import shutil import sys +from textwrap import dedent + import sphinx # If extensions (or modules to document with autodoc) are in another directory, @@ -51,11 +53,13 @@ else: dyn_exclude_patterns.append("devicetree/bindings/**.yaml") dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml") -# Properly handle include/exclude patterns -# ---------------------------------------- +# Properly handle directory patterns and LaTeX docs +# ------------------------------------------------- -def update_patterns(app, config): +def config_init(app, config): """ + Initialize path-dependent variabled + On Sphinx, all directories are relative to what it is passed as SOURCEDIR parameter for sphinx-build. Due to that, all patterns that have directory names on it need to be dynamically set, after @@ -86,6 +90,38 @@ def update_patterns(app, config): config.exclude_patterns.append(rel_path) + # LaTeX and PDF output require a list of documents with are dependent + # of the app.srcdir. Add them here + + # When SPHINXDIRS is used, we just need to get index.rst, if it exists + if not os.path.samefile(doctree, app.srcdir): + doc = os.path.basename(app.srcdir) + fname = "index" + if os.path.exists(os.path.join(app.srcdir, fname + ".rst")): + latex_documents.append((fname, doc + ".tex", + "Linux %s Documentation" % doc.capitalize(), + "The kernel development community", + "manual")) + return + + # When building all docs, or when a main index.rst doesn't exist, seek + # for it on subdirectories + for doc in os.listdir(app.srcdir): + fname = os.path.join(doc, "index") + if not os.path.exists(os.path.join(app.srcdir, fname + ".rst")): + continue + + has = False + for l in latex_documents: + if l[0] == fname: + has = True + break + + if not has: + latex_documents.append((fname, doc + ".tex", + "Linux %s Documentation" % doc.capitalize(), + "The kernel development community", + "manual")) # helper # ------ @@ -234,7 +270,7 @@ author = "The kernel development community" # |version| and |release|, also used in various other places throughout the # built documents. # -# In a normal build, version and release are are set to KERNELVERSION and +# In a normal build, version and release are set to KERNELVERSION and # KERNELRELEASE, respectively, from the Makefile via Sphinx command line # arguments. # @@ -420,19 +456,25 @@ htmlhelp_basename = "TheLinuxKerneldoc" latex_elements = { # The paper size ('letterpaper' or 'a4paper'). "papersize": "a4paper", + "passoptionstopackages": dedent(r""" + \PassOptionsToPackage{svgnames}{xcolor} + """), # The font size ('10pt', '11pt' or '12pt'). "pointsize": "11pt", + # Needed to generate a .ind file + "printindex": r"\footnotesize\raggedright\printindex", # Latex figure (float) alignment # 'figure_align': 'htbp', # Don't mangle with UTF-8 chars + "fontenc": "", "inputenc": "", "utf8extra": "", # Set document margins - "sphinxsetup": """ + "sphinxsetup": dedent(r""" hmargin=0.5in, vmargin=1in, parsedliteralwraps=true, verbatimhintsturnover=false, - """, + """), # # Some of our authors are fond of deep nesting; tell latex to # cope. @@ -440,48 +482,22 @@ latex_elements = { "maxlistdepth": "10", # For CJK One-half spacing, need to be in front of hyperref "extrapackages": r"\usepackage{setspace}", - # Additional stuff for the LaTeX preamble. - "preamble": """ - % Use some font with UTF-8 support with XeLaTeX - \\usepackage{fontspec} - \\setsansfont{DejaVu Sans} - \\setromanfont{DejaVu Serif} - \\setmonofont{DejaVu Sans Mono} - """, -} - -# Load kerneldoc specific LaTeX settings -latex_elements["preamble"] += """ + "fontpkg": dedent(r""" + \usepackage{fontspec} + \setmainfont{DejaVu Serif} + \setsansfont{DejaVu Sans} + \setmonofont{DejaVu Sans Mono} + \newfontfamily\headingfont{DejaVu Serif} + """), + "preamble": dedent(r""" % Load kerneldoc specific LaTeX settings - \\input{kerneldoc-preamble.sty} -""" + \input{kerneldoc-preamble.sty} + """) +} -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -# Sorted in alphabetical order +# This will be filled up by config-inited event latex_documents = [] -# Add all other index files from Documentation/ subdirectories -for fn in os.listdir("."): - doc = os.path.join(fn, "index") - if os.path.exists(doc + ".rst"): - has = False - for l in latex_documents: - if l[0] == doc: - has = True - break - if not has: - latex_documents.append( - ( - doc, - fn + ".tex", - "Linux %s Documentation" % fn.capitalize(), - "The kernel development community", - "manual", - ) - ) - # The name of an image file (relative to this directory) to place at the top of # the title page. # latex_logo = None @@ -577,4 +593,4 @@ loadConfig(globals()) def setup(app): """Patterns need to be updated at init time on older Sphinx versions""" - app.connect('config-inited', update_patterns) + app.connect('config-inited', config_init) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index 3087bea715ed..ca75b3541679 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -761,7 +761,7 @@ example warning message may look like this:: [<ffffffff80235177>] find_busiest_group+0x207/0x8a0 [<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50 [<ffffffff803c7ea3>] check_unmap+0x203/0x490 - [<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50 + [<ffffffff803c8259>] debug_dma_unmap_phys+0x49/0x50 [<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0 [<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0 [<ffffffff8026df84>] handle_IRQ_event+0x34/0x70 @@ -855,7 +855,7 @@ that a driver may be leaking mappings. dma-debug interface debug_dma_mapping_error() to debug drivers that fail to check DMA mapping errors on addresses returned by dma_map_single() and dma_map_page() interfaces. This interface clears a flag set by -debug_dma_map_page() to indicate that dma_mapping_error() has been called by +debug_dma_map_phys() to indicate that dma_mapping_error() has been called by the driver. When driver does unmap, debug_dma_unmap() checks the flag and if this flag is still set, prints warning message that includes call trace that leads up to the unmap. This interface can be called from dma_mapping_error() diff --git a/Documentation/core-api/dma-attributes.rst b/Documentation/core-api/dma-attributes.rst index 1887d92e8e92..0bdc2be65e57 100644 --- a/Documentation/core-api/dma-attributes.rst +++ b/Documentation/core-api/dma-attributes.rst @@ -130,3 +130,21 @@ accesses to DMA buffers in both privileged "supervisor" and unprivileged subsystem that the buffer is fully accessible at the elevated privilege level (and ideally inaccessible or at least read-only at the lesser-privileged levels). + +DMA_ATTR_MMIO +------------- + +This attribute indicates the physical address is not normal system +memory. It may not be used with kmap*()/phys_to_virt()/phys_to_page() +functions, it may not be cacheable, and access using CPU load/store +instructions may not be allowed. + +Usually this will be used to describe MMIO addresses, or other non-cacheable +register addresses. When DMA mapping this sort of address we call +the operation Peer to Peer as a one device is DMA'ing to another device. +For PCI devices the p2pdma APIs must be used to determine if +DMA_ATTR_MMIO is appropriate. + +For architectures that require cache flushing for DMA coherence +DMA_ATTR_MMIO will not perform any cache flushing. The address +provided must never be mapped cacheable into the CPU. diff --git a/Documentation/core-api/folio_queue.rst b/Documentation/core-api/folio_queue.rst index 83cfbc157e49..b7628896d2b6 100644 --- a/Documentation/core-api/folio_queue.rst +++ b/Documentation/core-api/folio_queue.rst @@ -44,7 +44,7 @@ Each segment in the list also stores: * the size of each folio and * three 1-bit marks per folio, -but hese should not be accessed directly as the underlying data structure may +but these should not be accessed directly as the underlying data structure may change, but rather the access functions outlined below should be used. The facility can be made accessible by:: diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index a03a99c2cac5..6cbdcbfa79c3 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -24,6 +24,7 @@ it. printk-index symbol-namespaces asm-annotations + real-time/index Data structures and low-level utilities ======================================= diff --git a/Documentation/core-api/irq/irq-affinity.rst b/Documentation/core-api/irq/irq-affinity.rst index 29da5000836a..9cb460cf60b6 100644 --- a/Documentation/core-api/irq/irq-affinity.rst +++ b/Documentation/core-api/irq/irq-affinity.rst @@ -9,9 +9,9 @@ ChangeLog: /proc/irq/IRQ#/smp_affinity and /proc/irq/IRQ#/smp_affinity_list specify which target CPUs are permitted for a given IRQ source. It's a bitmask -(smp_affinity) or cpu list (smp_affinity_list) of allowed CPUs. It's not +(smp_affinity) or CPU list (smp_affinity_list) of allowed CPUs. It's not allowed to turn off all CPUs, and if an IRQ controller does not support -IRQ affinity then the value will not change from the default of all cpus. +IRQ affinity then the value will not change from the default of all CPUs. /proc/irq/default_smp_affinity specifies default affinity mask that applies to all non-active IRQs. Once IRQ is allocated/activated its affinity bitmask @@ -60,7 +60,7 @@ Now lets restrict that IRQ to CPU(4-7). This time around IRQ44 was delivered only to the last four processors. i.e counters for the CPU0-3 did not change. -Here is an example of limiting that same irq (44) to cpus 1024 to 1031:: +Here is an example of limiting that same IRQ (44) to CPUs 1024 to 1031:: [root@moon 44]# echo 1024-1031 > smp_affinity_list [root@moon 44]# cat smp_affinity_list diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst index a01c6ead1bc0..68eb2612e8a4 100644 --- a/Documentation/core-api/irq/irq-domain.rst +++ b/Documentation/core-api/irq/irq-domain.rst @@ -18,8 +18,8 @@ handlers as irqchips. I.e. in effect cascading interrupt controllers. So in the past, IRQ numbers could be chosen so that they match the hardware IRQ line into the root interrupt controller (i.e. the component actually firing the interrupt line to the CPU). Nowadays, -this number is just a number and the number loose all kind of -correspondence to hardware interrupt numbers. +this number is just a number and the number has no +relationship to hardware interrupt numbers. For this reason, we need a mechanism to separate controller-local interrupt numbers, called hardware IRQs, from Linux IRQ numbers. @@ -77,15 +77,15 @@ Once a mapping has been established, it can be retrieved or used via a variety of methods: - irq_resolve_mapping() returns a pointer to the irq_desc structure - for a given domain and hwirq number, and NULL if there was no + for a given domain and hwirq number, or NULL if there was no mapping. - irq_find_mapping() returns a Linux IRQ number for a given domain and - hwirq number, and 0 if there was no mapping + hwirq number, or 0 if there was no mapping - generic_handle_domain_irq() handles an interrupt described by a domain and a hwirq number -Note that irq domain lookups must happen in contexts that are -compatible with a RCU read-side critical section. +Note that irq_domain lookups must happen in contexts that are +compatible with an RCU read-side critical section. The irq_create_mapping() function must be called *at least once* before any call to irq_find_mapping(), lest the descriptor will not @@ -100,7 +100,7 @@ Types of irq_domain Mappings ============================ There are several mechanisms available for reverse mapping from hwirq -to Linux irq, and each mechanism uses a different allocation function. +to Linux IRQ, and each mechanism uses a different allocation function. Which reverse map type should be used depends on the use case. Each of the reverse map types are described below: @@ -111,13 +111,13 @@ Linear irq_domain_create_linear() -The linear reverse map maintains a fixed size table indexed by the +The linear reverse map maintains a fixed-size table indexed by the hwirq number. When a hwirq is mapped, an irq_desc is allocated for the hwirq, and the IRQ number is stored in the table. The Linear map is a good choice when the maximum number of hwirqs is fixed and a relatively small number (~ < 256). The advantages of this -map are fixed time lookup for IRQ numbers, and irq_descs are only +map are fixed-time lookup for IRQ numbers, and irq_descs are only allocated for in-use IRQs. The disadvantage is that the table must be as large as the largest possible hwirq number. @@ -134,7 +134,7 @@ The irq_domain maintains a radix tree map from hwirq numbers to Linux IRQs. When an hwirq is mapped, an irq_desc is allocated and the hwirq is used as the lookup key for the radix tree. -The tree map is a good choice if the hwirq number can be very large +The Tree map is a good choice if the hwirq number can be very large since it doesn't need to allocate a table as large as the largest hwirq number. The disadvantage is that hwirq to IRQ number lookup is dependent on how many entries are in the table. @@ -169,10 +169,10 @@ Legacy The Legacy mapping is a special case for drivers that already have a range of irq_descs allocated for the hwirqs. It is used when the -driver cannot be immediately converted to use the linear mapping. For +driver cannot be immediately converted to use the Linear mapping. For example, many embedded system board support files use a set of #defines for IRQ numbers that are passed to struct device registrations. In that -case the Linux IRQ numbers cannot be dynamically assigned and the legacy +case the Linux IRQ numbers cannot be dynamically assigned and the Legacy mapping should be used. As the name implies, the \*_legacy() functions are deprecated and only @@ -180,15 +180,15 @@ exist to ease the support of ancient platforms. No new users should be added. Same goes for the \*_simple() functions when their use results in the legacy behaviour. -The legacy map assumes a contiguous range of IRQ numbers has already +The Legacy map assumes a contiguous range of IRQ numbers has already been allocated for the controller and that the IRQ number can be calculated by adding a fixed offset to the hwirq number, and visa-versa. The disadvantage is that it requires the interrupt controller to manage IRQ allocations and it requires an irq_desc to be allocated for every hwirq, even if it is unused. -The legacy map should only be used if fixed IRQ mappings must be -supported. For example, ISA controllers would use the legacy map for +The Legacy map should only be used if fixed IRQ mappings must be +supported. For example, ISA controllers would use the Legacy map for mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ numbers. @@ -197,7 +197,7 @@ which will use a legacy domain only if an IRQ range is supplied by the system and will otherwise use a linear domain mapping. The semantics of this call are such that if an IRQ range is specified then descriptors will be allocated on-the-fly for it, and if no range is specified it -will fall through to irq_domain_create_linear() which means *no* irq +will fall through to irq_domain_create_linear() which means *no* IRQ descriptors will be allocated. A typical use case for simple domains is where an irqchip provider @@ -214,7 +214,7 @@ Hierarchy IRQ Domain On some architectures, there may be multiple interrupt controllers involved in delivering an interrupt from the device to the target CPU. -Let's look at a typical interrupt delivering path on x86 platforms:: +Let's look at a typical interrupt delivery path on x86 platforms:: Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU @@ -227,8 +227,8 @@ There are three interrupt controllers involved: To support such a hardware topology and make software architecture match hardware architecture, an irq_domain data structure is built for each interrupt controller and those irq_domains are organized into hierarchy. -When building irq_domain hierarchy, the irq_domain near to the device is -child and the irq_domain near to CPU is parent. So a hierarchy structure +When building irq_domain hierarchy, the irq_domain nearest the device is +child and the irq_domain nearest the CPU is parent. So a hierarchy structure as below will be built for the example above:: CPU Vector irq_domain (root irq_domain to manage CPU vectors) diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 4b7f3646ec6c..7f2f11b48286 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -521,7 +521,7 @@ Fwnode handles %pfw[fP] -For printing information on fwnode handles. The default is to print the full +For printing information on an fwnode_handle. The default is to print the full node name, including the path. The modifiers are functionally equivalent to %pOF above. diff --git a/Documentation/core-api/real-time/architecture-porting.rst b/Documentation/core-api/real-time/architecture-porting.rst new file mode 100644 index 000000000000..d822fac29922 --- /dev/null +++ b/Documentation/core-api/real-time/architecture-porting.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================= +Porting an architecture to support PREEMPT_RT +============================================= + +:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de> + +This list outlines the architecture specific requirements that must be +implemented in order to enable PREEMPT_RT. Once all required features are +implemented, ARCH_SUPPORTS_RT can be selected in architecture’s Kconfig to make +PREEMPT_RT selectable. +Many prerequisites (genirq support for example) are enforced by the common code +and are omitted here. + +The optional features are not strictly required but it is worth to consider +them. + +Requirements +------------ + +Forced threaded interrupts + CONFIG_IRQ_FORCED_THREADING must be selected. Any interrupts that must + remain in hard-IRQ context must be marked with IRQF_NO_THREAD. This + requirement applies for instance to clocksource event interrupts, + perf interrupts and cascading interrupt-controller handlers. + +PREEMPTION support + Kernel preemption must be supported and requires that + CONFIG_ARCH_NO_PREEMPT remain unselected. Scheduling requests, such as those + issued from an interrupt or other exception handler, must be processed + immediately. + +POSIX CPU timers and KVM + POSIX CPU timers must expire from thread context rather than directly within + the timer interrupt. This behavior is enabled by setting the configuration + option CONFIG_HAVE_POSIX_CPU_TIMERS_TASK_WORK. + When KVM is enabled, CONFIG_KVM_XFER_TO_GUEST_WORK must also be set to ensure + that any pending work, such as POSIX timer expiration, is handled before + transitioning into guest mode. + +Hard-IRQ and Soft-IRQ stacks + Soft interrupts are handled in the thread context in which they are raised. If + a soft interrupt is triggered from hard-IRQ context, its execution is deferred + to the ksoftirqd thread. Preemption is never disabled during soft interrupt + handling, which makes soft interrupts preemptible. + If an architecture provides a custom __do_softirq() implementation that uses a + separate stack, it must select CONFIG_HAVE_SOFTIRQ_ON_OWN_STACK. The + functionality should only be enabled when CONFIG_SOFTIRQ_ON_OWN_STACK is set. + +FPU and SIMD access in kernel mode + FPU and SIMD registers are typically not used in kernel mode and are therefore + not saved during kernel preemption. As a result, any kernel code that uses + these registers must be enclosed within a kernel_fpu_begin() and + kernel_fpu_end() section. + The kernel_fpu_begin() function usually invokes local_bh_disable() to prevent + interruptions from softirqs and to disable regular preemption. This allows the + protected code to run safely in both thread and softirq contexts. + On PREEMPT_RT kernels, however, kernel_fpu_begin() must not call + local_bh_disable(). Instead, it should use preempt_disable(), since softirqs + are always handled in thread context under PREEMPT_RT. In this case, disabling + preemption alone is sufficient. + The crypto subsystem operates on memory pages and requires users to "walk and + map" these pages while processing a request. This operation must occur outside + the kernel_fpu_begin()/ kernel_fpu_end() section because it requires preemption + to be enabled. These preemption points are generally sufficient to avoid + excessive scheduling latency. + +Exception handlers + Exception handlers, such as the page fault handler, typically enable interrupts + early, before invoking any generic code to process the exception. This is + necessary because handling a page fault may involve operations that can sleep. + Enabling interrupts is especially important on PREEMPT_RT, where certain + locks, such as spinlock_t, become sleepable. For example, handling an + invalid opcode may result in sending a SIGILL signal to the user task. A + debug excpetion will send a SIGTRAP signal. + In both cases, if the exception occurred in user space, it is safe to enable + interrupts early. Sending a signal requires both interrupts and kernel + preemption to be enabled. + +Optional features +----------------- + +Timer and clocksource + A high-resolution clocksource and clockevents device are recommended. The + clockevents device should support the CLOCK_EVT_FEAT_ONESHOT feature for + optimal timer behavior. In most cases, microsecond-level accuracy is + sufficient + +Lazy preemption + This mechanism allows an in-kernel scheduling request for non-real-time tasks + to be delayed until the task is about to return to user space. It helps avoid + preempting a task that holds a sleeping lock at the time of the scheduling + request. + With CONFIG_GENERIC_IRQ_ENTRY enabled, supporting this feature requires + defining a bit for TIF_NEED_RESCHED_LAZY, preferably near TIF_NEED_RESCHED. + +Serial console with NBCON + With PREEMPT_RT enabled, all console output is handled by a dedicated thread + rather than directly from the context in which printk() is invoked. This design + allows printk() to be safely used in atomic contexts. + However, this also means that if the kernel crashes and cannot switch to the + printing thread, no output will be visible preventing the system from printing + its final messages. + There are exceptions for immediate output, such as during panic() handling. To + support this, the console driver must implement new-style lock handling. This + involves setting the CON_NBCON flag in console::flags and providing + implementations for the write_atomic, write_thread, device_lock, and + device_unlock callbacks. diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst new file mode 100644 index 000000000000..83ec9aa1c61a --- /dev/null +++ b/Documentation/core-api/real-time/differences.rst @@ -0,0 +1,242 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +How realtime kernels differ +=========================== + +:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de> + +Preface +======= + +With forced-threaded interrupts and sleeping spin locks, code paths that +previously caused long scheduling latencies have been made preemptible and +moved into process context. This allows the scheduler to manage them more +effectively and respond to higher-priority tasks with reduced latency. + +The following chapters provide an overview of key differences between a +PREEMPT_RT kernel and a standard, non-PREEMPT_RT kernel. + +Locking +======= + +Spinning locks such as spinlock_t are used to provide synchronization for data +structures accessed from both interrupt context and process context. For this +reason, locking functions are also available with the _irq() or _irqsave() +suffixes, which disable interrupts before acquiring the lock. This ensures that +the lock can be safely acquired in process context when interrupts are enabled. + +However, on a PREEMPT_RT system, interrupts are forced-threaded and no longer +run in hard IRQ context. As a result, there is no need to disable interrupts as +part of the locking procedure when using spinlock_t. + +For low-level core components such as interrupt handling, the scheduler, or the +timer subsystem the kernel uses raw_spinlock_t. This lock type preserves +traditional semantics: it disables preemption and, when used with _irq() or +_irqsave(), also disables interrupts. This ensures proper synchronization in +critical sections that must remain non-preemptible or with interrupts disabled. + +Execution context +================= + +Interrupt handling in a PREEMPT_RT system is invoked in process context through +the use of threaded interrupts. Other parts of the kernel also shift their +execution into threaded context by different mechanisms. The goal is to keep +execution paths preemptible, allowing the scheduler to interrupt them when a +higher-priority task needs to run. + +Below is an overview of the kernel subsystems involved in this transition to +threaded, preemptible execution. + +Interrupt handling +------------------ + +All interrupts are forced-threaded in a PREEMPT_RT system. The exceptions are +interrupts that are requested with the IRQF_NO_THREAD, IRQF_PERCPU, or +IRQF_ONESHOT flags. + +The IRQF_ONESHOT flag is used together with threaded interrupts, meaning those +registered using request_threaded_irq() and providing only a threaded handler. +Its purpose is to keep the interrupt line masked until the threaded handler has +completed. + +If a primary handler is also provided in this case, it is essential that the +handler does not acquire any sleeping locks, as it will not be threaded. The +handler should be minimal and must avoid introducing delays, such as +busy-waiting on hardware registers. + + +Soft interrupts, bottom half handling +------------------------------------- + +Soft interrupts are raised by the interrupt handler and are executed after the +handler returns. Since they run in thread context, they can be preempted by +other threads. Do not assume that softirq context runs with preemption +disabled. This means you must not rely on mechanisms like local_bh_disable() in +process context to protect per-CPU variables. Because softirq handlers are +preemptible under PREEMPT_RT, this approach does not provide reliable +synchronization. + +If this kind of protection is required for performance reasons, consider using +local_lock_nested_bh(). On non-PREEMPT_RT kernels, this allows lockdep to +verify that bottom halves are disabled. On PREEMPT_RT systems, it adds the +necessary locking to ensure proper protection. + +Using local_lock_nested_bh() also makes the locking scope explicit and easier +for readers and maintainers to understand. + + +per-CPU variables +----------------- + +Protecting access to per-CPU variables solely by using preempt_disable() should +be avoided, especially if the critical section has unbounded runtime or may +call APIs that can sleep. + +If using a spinlock_t is considered too costly for performance reasons, +consider using local_lock_t. On non-PREEMPT_RT configurations, this introduces +no runtime overhead when lockdep is disabled. With lockdep enabled, it verifies +that the lock is only acquired in process context and never from softirq or +hard IRQ context. + +On a PREEMPT_RT kernel, local_lock_t is implemented using a per-CPU spinlock_t, +which provides safe local protection for per-CPU data while keeping the system +preemptible. + +Because spinlock_t on PREEMPT_RT does not disable preemption, it cannot be used +to protect per-CPU data by relying on implicit preemption disabling. If this +inherited preemption disabling is essential and if local_lock_t cannot be used +due to performance constraints, brevity of the code, or abstraction boundaries +within an API then preempt_disable_nested() may be a suitable alternative. On +non-PREEMPT_RT kernels, it verifies with lockdep that preemption is already +disabled. On PREEMPT_RT, it explicitly disables preemption. + +Timers +------ + +By default, an hrtimer is executed in hard interrupt context. The exception is +timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in +softirq context. + +On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in +softirq context by default, typically within the ktimersd thread. This thread +runs at the lowest real-time priority, ensuring it executes before any +SCHED_OTHER tasks but does not interfere with higher-priority real-time +threads. To explicitly request execution in hard interrupt context on +PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag. + +Memory allocation +----------------- + +The memory allocation APIs, such as kmalloc() and alloc_pages(), require a +gfp_t flag to indicate the allocation context. On non-PREEMPT_RT kernels, it is +necessary to use GFP_ATOMIC when allocating memory from interrupt context or +from sections where preemption is disabled. This is because the allocator must +not sleep in these contexts waiting for memory to become available. + +However, this approach does not work on PREEMPT_RT kernels. The memory +allocator in PREEMPT_RT uses sleeping locks internally, which cannot be +acquired when preemption is disabled. Fortunately, this is generally not a +problem, because PREEMPT_RT moves most contexts that would traditionally run +with preemption or interrupts disabled into threaded context, where sleeping is +allowed. + +What remains problematic is code that explicitly disables preemption or +interrupts. In such cases, memory allocation must be performed outside the +critical section. + +This restriction also applies to memory deallocation routines such as kfree() +and free_pages(), which may also involve internal locking and must not be +called from non-preemptible contexts. + +IRQ work +-------- + +The irq_work API provides a mechanism to schedule a callback in interrupt +context. It is designed for use in contexts where traditional scheduling is not +possible, such as from within NMI handlers or from inside the scheduler, where +using a workqueue would be unsafe. + +On non-PREEMPT_RT systems, all irq_work items are executed immediately in +interrupt context. Items marked with IRQ_WORK_LAZY are deferred until the next +timer tick but are still executed in interrupt context. + +On PREEMPT_RT systems, the execution model changes. Because irq_work callbacks +may acquire sleeping locks or have unbounded execution time, they are handled +in thread context by a per-CPU irq_work kernel thread. This thread runs at the +lowest real-time priority, ensuring it executes before any SCHED_OTHER tasks +but does not interfere with higher-priority real-time threads. + +The exception are work items marked with IRQ_WORK_HARD_IRQ, which are still +executed in hard interrupt context. Lazy items (IRQ_WORK_LAZY) continue to be +deferred until the next timer tick and are also executed by the irq_work/ +thread. + +RCU callbacks +------------- + +RCU callbacks are invoked by default in softirq context. Their execution is +important because, depending on the use case, they either free memory or ensure +progress in state transitions. Running these callbacks as part of the softirq +chain can lead to undesired situations, such as contention for CPU resources +with other SCHED_OTHER tasks when executed within ksoftirqd. + +To avoid running callbacks in softirq context, the RCU subsystem provides a +mechanism to execute them in process context instead. This behavior can be +enabled by setting the boot command-line parameter rcutree.use_softirq=0. This +setting is enforced in kernels configured with PREEMPT_RT. + +Spin until ready +================ + +The "spin until ready" pattern involves repeatedly checking (spinning on) the +state of a data structure until it becomes available. This pattern assumes that +preemption, soft interrupts, or interrupts are disabled. If the data structure +is marked busy, it is presumed to be in use by another CPU, and spinning should +eventually succeed as that CPU makes progress. + +Some examples are hrtimer_cancel() or timer_delete_sync(). These functions +cancel timers that execute with interrupts or soft interrupts disabled. If a +thread attempts to cancel a timer and finds it active, spinning until the +callback completes is safe because the callback can only run on another CPU and +will eventually finish. + +On PREEMPT_RT kernels, however, timer callbacks run in thread context. This +introduces a challenge: a higher-priority thread attempting to cancel the timer +may preempt the timer callback thread. Since the scheduler cannot migrate the +callback thread to another CPU due to affinity constraints, spinning can result +in livelock even on multiprocessor systems. + +To avoid this, both the canceling and callback sides must use a handshake +mechanism that supports priority inheritance. This allows the canceling thread +to suspend until the callback completes, ensuring forward progress without +risking livelock. + +In order to solve the problem at the API level, the sequence locks were extended +to allow a proper handover between the the spinning reader and the maybe +blocked writer. + +Sequence locks +-------------- + +Sequence counters and sequential locks are documented in +Documentation/locking/seqlock.rst. + +The interface has been extended to ensure proper preemption states for the +writer and spinning reader contexts. This is achieved by embedding the writer +serialization lock directly into the sequence counter type, resulting in +composite types such as seqcount_spinlock_t or seqcount_mutex_t. + +These composite types allow readers to detect an ongoing write and actively +boost the writer’s priority to help it complete its update instead of spinning +and waiting for its completion. + +If the plain seqcount_t is used, extra care must be taken to synchronize the +reader with the writer during updates. The writer must ensure its update is +serialized and non-preemptible relative to the reader. This cannot be achieved +using a regular spinlock_t because spinlock_t on PREEMPT_RT does not disable +preemption. In such cases, using seqcount_spinlock_t is the preferred solution. + +However, if there is no spinning involved i.e., if the reader only needs to +detect whether a write has started and not serialize against it then using +seqcount_t is reasonable. diff --git a/Documentation/core-api/real-time/index.rst b/Documentation/core-api/real-time/index.rst new file mode 100644 index 000000000000..7e14c4ea3d59 --- /dev/null +++ b/Documentation/core-api/real-time/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Real-time preemption +===================== + +This documentation is intended for Linux kernel developers and contributors +interested in the inner workings of PREEMPT_RT. It explains key concepts and +the required changes compared to a non-PREEMPT_RT configuration. + +.. toctree:: + :maxdepth: 2 + + theory + differences + architecture-porting diff --git a/Documentation/core-api/real-time/theory.rst b/Documentation/core-api/real-time/theory.rst new file mode 100644 index 000000000000..43d0120737f8 --- /dev/null +++ b/Documentation/core-api/real-time/theory.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Theory of operation +===================== + +:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de> + +Preface +======= + +PREEMPT_RT transforms the Linux kernel into a real-time kernel. It achieves +this by replacing locking primitives, such as spinlock_t, with a preemptible +and priority-inheritance aware implementation known as rtmutex, and by enforcing +the use of threaded interrupts. As a result, the kernel becomes fully +preemptible, with the exception of a few critical code paths, including entry +code, the scheduler, and low-level interrupt handling routines. + +This transformation places the majority of kernel execution contexts under the +control of the scheduler and significantly increasing the number of preemption +points. Consequently, it reduces the latency between a high-priority task +becoming runnable and its actual execution on the CPU. + +Scheduling +========== + +The core principles of Linux scheduling and the associated user-space API are +documented in the man page sched(7) +`sched(7) <https://man7.org/linux/man-pages/man7/sched.7.html>`_. +By default, the Linux kernel uses the SCHED_OTHER scheduling policy. Under +this policy, a task is preempted when the scheduler determines that it has +consumed a fair share of CPU time relative to other runnable tasks. However, +the policy does not guarantee immediate preemption when a new SCHED_OTHER task +becomes runnable. The currently running task may continue executing. + +This behavior differs from that of real-time scheduling policies such as +SCHED_FIFO. When a task with a real-time policy becomes runnable, the +scheduler immediately selects it for execution if it has a higher priority than +the currently running task. The task continues to run until it voluntarily +yields the CPU, typically by blocking on an event. + +Sleeping spin locks +=================== + +The various lock types and their behavior under real-time configurations are +described in detail in Documentation/locking/locktypes.rst. +In a non-PREEMPT_RT configuration, a spinlock_t is acquired by first disabling +preemption and then actively spinning until the lock becomes available. Once +the lock is released, preemption is enabled. From a real-time perspective, +this approach is undesirable because disabling preemption prevents the +scheduler from switching to a higher-priority task, potentially increasing +latency. + +To address this, PREEMPT_RT replaces spinning locks with sleeping spin locks +that do not disable preemption. On PREEMPT_RT, spinlock_t is implemented using +rtmutex. Instead of spinning, a task attempting to acquire a contended lock +disables CPU migration, donates its priority to the lock owner (priority +inheritance), and voluntarily schedules out while waiting for the lock to +become available. + +Disabling CPU migration provides the same effect as disabling preemption, while +still allowing preemption and ensuring that the task continues to run on the +same CPU while holding a sleeping lock. + +Priority inheritance +==================== + +Lock types such as spinlock_t and mutex_t in a PREEMPT_RT enabled kernel are +implemented on top of rtmutex, which provides support for priority inheritance +(PI). When a task blocks on such a lock, the PI mechanism temporarily +propagates the blocked task’s scheduling parameters to the lock owner. + +For example, if a SCHED_FIFO task A blocks on a lock currently held by a +SCHED_OTHER task B, task A’s scheduling policy and priority are temporarily +inherited by task B. After this inheritance, task A is put to sleep while +waiting for the lock, and task B effectively becomes the highest-priority task +in the system. This allows B to continue executing, make progress, and +eventually release the lock. + +Once B releases the lock, it reverts to its original scheduling parameters, and +task A can resume execution. + +Threaded interrupts +=================== + +Interrupt handlers are another source of code that executes with preemption +disabled and outside the control of the scheduler. To bring interrupt handling +under scheduler control, PREEMPT_RT enforces threaded interrupt handlers. + +With forced threading, interrupt handling is split into two stages. The first +stage, the primary handler, is executed in IRQ context with interrupts disabled. +Its sole responsibility is to wake the associated threaded handler. The second +stage, the threaded handler, is the function passed to request_irq() as the +interrupt handler. It runs in process context, scheduled by the kernel. + +From waking the interrupt thread until threaded handling is completed, the +interrupt source is masked in the interrupt controller. This ensures that the +device interrupt remains pending but does not retrigger the CPU, allowing the +system to exit IRQ context and handle the interrupt in a scheduled thread. + +By default, the threaded handler executes with the SCHED_FIFO scheduling policy +and a priority of 50 (MAX_RT_PRIO / 2), which is midway between the minimum and +maximum real-time priorities. + +If the threaded interrupt handler raises any soft interrupts during its +execution, those soft interrupt routines are invoked after the threaded handler +completes, within the same thread. Preemption remains enabled during the +execution of the soft interrupt handler. + +Summary +======= + +By using sleeping locks and forced-threaded interrupts, PREEMPT_RT +significantly reduces sections of code where interrupts or preemption is +disabled, allowing the scheduler to preempt the current execution context and +switch to a higher-priority task. diff --git a/Documentation/dev-tools/autofdo.rst b/Documentation/dev-tools/autofdo.rst index 1f0a451e9ccd..bcf06e7d6ffa 100644 --- a/Documentation/dev-tools/autofdo.rst +++ b/Documentation/dev-tools/autofdo.rst @@ -131,11 +131,11 @@ Here is an example workflow for AutoFDO kernel: For Zen3:: - $ cat proc/cpuinfo | grep " brs" + $ cat /proc/cpuinfo | grep " brs" For Zen4:: - $ cat proc/cpuinfo | grep amd_lbr_v2 + $ cat /proc/cpuinfo | grep amd_lbr_v2 The following command generated the perf data file:: diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 65c54b27a60b..4b8425e348ab 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -29,6 +29,7 @@ Documentation/process/debugging/index.rst ubsan kmemleak kcsan + lkmm/index kfence kselftest kunit/index diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst index 414c105b10a9..a9810bed5fd4 100644 --- a/Documentation/dev-tools/ktap.rst +++ b/Documentation/dev-tools/ktap.rst @@ -5,7 +5,7 @@ The Kernel Test Anything Protocol (KTAP), version 1 =================================================== TAP, or the Test Anything Protocol is a format for specifying test results used -by a number of projects. It's website and specification are found at this `link +by a number of projects. Its website and specification are found at this `link <https://testanything.org/>`_. The Linux Kernel largely uses TAP output for test results. However, Kernel testing frameworks have special needs for test results which don't align with the original TAP specification. Thus, a "Kernel TAP" @@ -20,6 +20,7 @@ machine-readable, whereas the diagnostic data is unstructured and is there to aid human debugging. KTAP output is built from four different types of lines: + - Version lines - Plan lines - Test case result lines @@ -38,6 +39,7 @@ All KTAP-formatted results begin with a "version line" which specifies which version of the (K)TAP standard the result is compliant with. For example: + - "KTAP version 1" - "TAP version 13" - "TAP version 14" @@ -276,6 +278,7 @@ Example KTAP output This output defines the following hierarchy: A single test called "main_test", which fails, and has three subtests: + - "example_test_1", which passes, and has one subtest: - "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1" diff --git a/Documentation/dev-tools/lkmm/docs/access-marking.rst b/Documentation/dev-tools/lkmm/docs/access-marking.rst new file mode 100644 index 000000000000..80058a4da980 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/access-marking.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Access Marking +-------------- + +Literal include of ``tools/memory-model/Documentation/access-marking.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/access-marking.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/cheatsheet.rst b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst new file mode 100644 index 000000000000..37681f6a6a8c --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Cheatsheet +---------- + +Literal include of ``tools/memory-model/Documentation/cheatsheet.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/cheatsheet.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/control-dependencies.rst b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst new file mode 100644 index 000000000000..5ae97e8861eb --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Control Dependencies +-------------------- + +Literal include of ``tools/memory-model/Documentation/control-dependencies.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/control-dependencies.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/explanation.rst b/Documentation/dev-tools/lkmm/docs/explanation.rst new file mode 100644 index 000000000000..0bcba9a5ddf7 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/explanation.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Explanation +----------- + +Literal include of ``tools/memory-model/Documentation/explanation.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/explanation.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/glossary.rst b/Documentation/dev-tools/lkmm/docs/glossary.rst new file mode 100644 index 000000000000..849aefdf3d6e --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/glossary.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Glossary +-------- + +Literal include of ``tools/memory-model/Documentation/glossary.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/glossary.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/herd-representation.rst b/Documentation/dev-tools/lkmm/docs/herd-representation.rst new file mode 100644 index 000000000000..f7b41f286eb9 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/herd-representation.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +herd-representation +------------------- + +Literal include of ``tools/memory-model/Documentation/herd-representation.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/herd-representation.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/index.rst b/Documentation/dev-tools/lkmm/docs/index.rst new file mode 100644 index 000000000000..abbddcc009de --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Documentation +============= + +.. toctree:: + :maxdepth: 1 + + readme + simple + ordering + litmus-tests + locking + recipes + control-dependencies + access-marking + cheatsheet + explanation + herd-representation + glossary + references diff --git a/Documentation/dev-tools/lkmm/docs/litmus-tests.rst b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst new file mode 100644 index 000000000000..3293f4540156 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Litmus Tests +------------ + +Literal include of ``tools/memory-model/Documentation/litmus-tests.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/litmus-tests.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/locking.rst b/Documentation/dev-tools/lkmm/docs/locking.rst new file mode 100644 index 000000000000..b5eae4c0acb7 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/locking.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Locking +------- + +Literal include of ``tools/memory-model/Documentation/locking.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/locking.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/ordering.rst b/Documentation/dev-tools/lkmm/docs/ordering.rst new file mode 100644 index 000000000000..a2343c12462d --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/ordering.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Ordering +-------- + +Literal include of ``tools/memory-model/Documentation/ordering.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/ordering.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/readme.rst b/Documentation/dev-tools/lkmm/docs/readme.rst new file mode 100644 index 000000000000..51e7a64e4435 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/readme.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +README (for LKMM Documentation) +------------------------------- + +Literal include of ``tools/memory-model/Documentation/README``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/README + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/recipes.rst b/Documentation/dev-tools/lkmm/docs/recipes.rst new file mode 100644 index 000000000000..e55952640047 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/recipes.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Recipes +------- + +Literal include of ``tools/memory-model/Documentation/recipes.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/recipes.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/references.rst b/Documentation/dev-tools/lkmm/docs/references.rst new file mode 100644 index 000000000000..c6831b3c9c02 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/references.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +References +---------- + +Literal include of ``tools/memory-model/Documentation/references.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/references.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/simple.rst b/Documentation/dev-tools/lkmm/docs/simple.rst new file mode 100644 index 000000000000..5c1094c95f45 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/simple.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Simple +------ + +Literal include of ``tools/memory-model/Documentation/simple.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/simple.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/index.rst b/Documentation/dev-tools/lkmm/index.rst new file mode 100644 index 000000000000..e52782449ca3 --- /dev/null +++ b/Documentation/dev-tools/lkmm/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================ +Linux Kernel Memory Consistency Model (LKMM) +============================================ + +This section literally renders documents under ``tools/memory-model/`` +and ``tools/memory-model/Documentation/``, which are maintained in +the *pure* plain text form. + +.. toctree:: + :maxdepth: 2 + + readme + docs/index diff --git a/Documentation/dev-tools/lkmm/readme.rst b/Documentation/dev-tools/lkmm/readme.rst new file mode 100644 index 000000000000..a7f847109584 --- /dev/null +++ b/Documentation/dev-tools/lkmm/readme.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +README (for LKMM) +================= + +Literal include of ``tools/memory-model/README``. + +------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/README + :literal: diff --git a/Documentation/devicetree/bindings/clock/axis,artpec8-clock.yaml b/Documentation/devicetree/bindings/clock/axis,artpec8-clock.yaml new file mode 100644 index 000000000000..277af48ac841 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/axis,artpec8-clock.yaml @@ -0,0 +1,213 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/axis,artpec8-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Axis ARTPEC-8 SoC clock controller + +maintainers: + - Jesper Nilsson <jesper.nilsson@axis.com> + +description: | + ARTPEC-8 clock controller is comprised of several CMU (Clock Management Unit) + units, generating clocks for different domains. Those CMU units are modeled + as separate device tree nodes, and might depend on each other. + The root clock in that root tree is an external clock: OSCCLK (25 MHz). + This external clock must be defined as a fixed-rate clock in dts. + + CMU_CMU is a top-level CMU, where all base clocks are prepared using PLLs and + dividers; all other clocks of function blocks (other CMUs) are usually + derived from CMU_CMU. + + Each clock is assigned an identifier and client nodes can use this identifier + to specify the clock which they consume. All clocks available for usage + in clock consumer nodes are defined as preprocessor macros in + 'include/dt-bindings/clock/axis,artpec8-clk.h' header. + +properties: + compatible: + enum: + - axis,artpec8-cmu-cmu + - axis,artpec8-cmu-bus + - axis,artpec8-cmu-core + - axis,artpec8-cmu-cpucl + - axis,artpec8-cmu-fsys + - axis,artpec8-cmu-imem + - axis,artpec8-cmu-peri + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 5 + + clock-names: + minItems: 1 + maxItems: 5 + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - "#clock-cells" + +allOf: + - if: + properties: + compatible: + const: axis,artpec8-cmu-cmu + + then: + properties: + clocks: + items: + - description: External reference clock (25 MHz) + + clock-names: + items: + - const: fin_pll + + - if: + properties: + compatible: + const: axis,artpec8-cmu-bus + + then: + properties: + clocks: + items: + - description: External reference clock (25 MHz) + - description: CMU_BUS BUS clock (from CMU_CMU) + - description: CMU_BUS DLP clock (from CMU_CMU) + + clock-names: + items: + - const: fin_pll + - const: bus + - const: dlp + + - if: + properties: + compatible: + const: axis,artpec8-cmu-core + + then: + properties: + clocks: + items: + - description: External reference clock (25 MHz) + - description: CMU_CORE main clock (from CMU_CMU) + - description: CMU_CORE DLP clock (from CMU_CMU) + + clock-names: + items: + - const: fin_pll + - const: main + - const: dlp + + - if: + properties: + compatible: + const: axis,artpec8-cmu-cpucl + + then: + properties: + clocks: + items: + - description: External reference clock (25 MHz) + - description: CMU_CPUCL switch clock (from CMU_CMU) + + clock-names: + items: + - const: fin_pll + - const: switch + + - if: + properties: + compatible: + const: axis,artpec8-cmu-fsys + + then: + properties: + clocks: + items: + - description: External reference clock (25 MHz) + - description: CMU_FSYS SCAN0 clock (from CMU_CMU) + - description: CMU_FSYS SCAN1 clock (from CMU_CMU) + - description: CMU_FSYS BUS clock (from CMU_CMU) + - description: CMU_FSYS IP clock (from CMU_CMU) + + clock-names: + items: + - const: fin_pll + - const: scan0 + - const: scan1 + - const: bus + - const: ip + + - if: + properties: + compatible: + const: axis,artpec8-cmu-imem + + then: + properties: + clocks: + items: + - description: External reference clock (25 MHz) + - description: CMU_IMEM ACLK clock (from CMU_CMU) + - description: CMU_IMEM JPEG clock (from CMU_CMU) + + clock-names: + items: + - const: fin_pll + - const: aclk + - const: jpeg + + - if: + properties: + compatible: + const: axis,artpec8-cmu-peri + + then: + properties: + clocks: + items: + - description: External reference clock (25 MHz) + - description: CMU_PERI IP clock (from CMU_CMU) + - description: CMU_PERI AUDIO clock (from CMU_CMU) + - description: CMU_PERI DISP clock (from CMU_CMU) + + clock-names: + items: + - const: fin_pll + - const: ip + - const: audio + - const: disp + +additionalProperties: false + +examples: + # Clock controller node for CMU_FSYS + - | + #include <dt-bindings/clock/axis,artpec8-clk.h> + + cmu_fsys: clock-controller@16c10000 { + compatible = "axis,artpec8-cmu-fsys"; + reg = <0x16c10000 0x4000>; + #clock-cells = <1>; + clocks = <&fin_pll>, + <&cmu_cmu CLK_DOUT_CMU_FSYS_SCAN0>, + <&cmu_cmu CLK_DOUT_CMU_FSYS_SCAN1>, + <&cmu_cmu CLK_DOUT_CMU_FSYS_BUS>, + <&cmu_cmu CLK_DOUT_CMU_FSYS_IP>; + clock-names = "fin_pll", "scan0", "scan1", "bus", "ip"; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/riscv,rpmi-clock.yaml b/Documentation/devicetree/bindings/clock/riscv,rpmi-clock.yaml new file mode 100644 index 000000000000..5d62bf8215c8 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/riscv,rpmi-clock.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/riscv,rpmi-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V RPMI clock service group based clock controller + +maintainers: + - Anup Patel <anup@brainfault.org> + +description: | + The RISC-V Platform Management Interface (RPMI) [1] defines a + messaging protocol which is modular and extensible. The supervisor + software can send/receive RPMI messages via SBI MPXY extension [2] + or some dedicated supervisor-mode RPMI transport. + + The RPMI specification [1] defines clock service group for accessing + system clocks managed by a platform microcontroller. The supervisor + software can access RPMI clock service group via SBI MPXY channel or + some dedicated supervisor-mode RPMI transport. + + =========================================== + References + =========================================== + + [1] RISC-V Platform Management Interface (RPMI) v1.0 (or higher) + https://github.com/riscv-non-isa/riscv-rpmi/releases + + [2] RISC-V Supervisor Binary Interface (SBI) v3.0 (or higher) + https://github.com/riscv-non-isa/riscv-sbi-doc/releases + +properties: + compatible: + description: + Intended for use by the supervisor software. + const: riscv,rpmi-clock + + mboxes: + maxItems: 1 + description: + Mailbox channel of the underlying RPMI transport or SBI message proxy channel. + + "#clock-cells": + const: 1 + description: + Platform specific CLOCK_ID as defined by the RISC-V Platform Management + Interface (RPMI) specification. + +required: + - compatible + - mboxes + - "#clock-cells" + +additionalProperties: false + +examples: + - | + clock-controller { + compatible = "riscv,rpmi-clock"; + mboxes = <&mpxy_mbox 0x1000 0x0>; + #clock-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml b/Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml new file mode 100644 index 000000000000..76f2a1b3d30d --- /dev/null +++ b/Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/riscv,rpmi-mpxy-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V RPMI clock service group based message proxy + +maintainers: + - Anup Patel <anup@brainfault.org> + +description: | + The RISC-V Platform Management Interface (RPMI) [1] defines a + messaging protocol which is modular and extensible. The supervisor + software can send/receive RPMI messages via SBI MPXY extension [2] + or some dedicated supervisor-mode RPMI transport. + + The RPMI specification [1] defines clock service group for accessing + system clocks managed by a platform microcontroller. The SBI implementation + (machine mode firmware or hypervisor) can implement an SBI MPXY channel + to allow RPMI clock service group access to the supervisor software. + + =========================================== + References + =========================================== + + [1] RISC-V Platform Management Interface (RPMI) v1.0 (or higher) + https://github.com/riscv-non-isa/riscv-rpmi/releases + + [2] RISC-V Supervisor Binary Interface (SBI) v3.0 (or higher) + https://github.com/riscv-non-isa/riscv-sbi-doc/releases + +properties: + compatible: + description: + Intended for use by the SBI implementation. + const: riscv,rpmi-mpxy-clock + + mboxes: + maxItems: 1 + description: + Mailbox channel of the underlying RPMI transport. + + riscv,sbi-mpxy-channel-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The SBI MPXY channel id to be used for providing RPMI access to + the supervisor software. + +required: + - compatible + - mboxes + - riscv,sbi-mpxy-channel-id + +additionalProperties: false + +examples: + - | + clock-service { + compatible = "riscv,rpmi-mpxy-clock"; + mboxes = <&rpmi_shmem_mbox 0x8>; + riscv,sbi-mpxy-channel-id = <0x1000>; + }; +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-mpxy-system-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-mpxy-system-msi.yaml new file mode 100644 index 000000000000..1991f5c7446a --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-mpxy-system-msi.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/riscv,rpmi-mpxy-system-msi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V RPMI system MSI service group based message proxy + +maintainers: + - Anup Patel <anup@brainfault.org> + +description: | + The RISC-V Platform Management Interface (RPMI) [1] defines a + messaging protocol which is modular and extensible. The supervisor + software can send/receive RPMI messages via SBI MPXY extension [2] + or some dedicated supervisor-mode RPMI transport. + + The RPMI specification [1] defines system MSI service group which + allow application processors to receive MSIs upon system events + such as P2A doorbell, graceful shutdown/reboot request, CPU hotplug + event, memory hotplug event, etc from the platform microcontroller. + The SBI implementation (machine mode firmware or hypervisor) can + implement an SBI MPXY channel to allow RPMI system MSI service + group access to the supervisor software. + + =========================================== + References + =========================================== + + [1] RISC-V Platform Management Interface (RPMI) v1.0 (or higher) + https://github.com/riscv-non-isa/riscv-rpmi/releases + + [2] RISC-V Supervisor Binary Interface (SBI) v3.0 (or higher) + https://github.com/riscv-non-isa/riscv-sbi-doc/releases + +properties: + compatible: + description: + Intended for use by the SBI implementation. + const: riscv,rpmi-mpxy-system-msi + + mboxes: + maxItems: 1 + description: + Mailbox channel of the underlying RPMI transport. + + riscv,sbi-mpxy-channel-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The SBI MPXY channel id to be used for providing RPMI access to + the supervisor software. + +required: + - compatible + - mboxes + - riscv,sbi-mpxy-channel-id + +additionalProperties: false + +examples: + - | + interrupt-controller { + compatible = "riscv,rpmi-mpxy-system-msi"; + mboxes = <&rpmi_shmem_mbox 0x2>; + riscv,sbi-mpxy-channel-id = <0x2000>; + }; +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-system-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-system-msi.yaml new file mode 100644 index 000000000000..b10a0532e586 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-system-msi.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/riscv,rpmi-system-msi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V RPMI system MSI service group based interrupt controller + +maintainers: + - Anup Patel <anup@brainfault.org> + +description: | + The RISC-V Platform Management Interface (RPMI) [1] defines a + messaging protocol which is modular and extensible. The supervisor + software can send/receive RPMI messages via SBI MPXY extension [2] + or some dedicated supervisor-mode RPMI transport. + + The RPMI specification [1] defines system MSI service group which + allow application processors to receive MSIs upon system events + such as P2A doorbell, graceful shutdown/reboot request, CPU hotplug + event, memory hotplug event, etc from the platform microcontroller. + The supervisor software can access RPMI system MSI service group via + SBI MPXY channel or some dedicated supervisor-mode RPMI transport. + + =========================================== + References + =========================================== + + [1] RISC-V Platform Management Interface (RPMI) v1.0 (or higher) + https://github.com/riscv-non-isa/riscv-rpmi/releases + + [2] RISC-V Supervisor Binary Interface (SBI) v3.0 (or higher) + https://github.com/riscv-non-isa/riscv-sbi-doc/releases + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + description: + Intended for use by the supervisor software. + const: riscv,rpmi-system-msi + + mboxes: + maxItems: 1 + description: + Mailbox channel of the underlying RPMI transport or SBI message proxy channel. + + msi-parent: true + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + +required: + - compatible + - mboxes + - msi-parent + - interrupt-controller + - "#interrupt-cells" + +additionalProperties: false + +examples: + - | + interrupt-controller { + compatible = "riscv,rpmi-system-msi"; + mboxes = <&mpxy_mbox 0x2000 0x0>; + msi-parent = <&imsic_slevel>; + interrupt-controller; + #interrupt-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/mailbox/riscv,rpmi-shmem-mbox.yaml b/Documentation/devicetree/bindings/mailbox/riscv,rpmi-shmem-mbox.yaml new file mode 100644 index 000000000000..3aabc52a0c03 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/riscv,rpmi-shmem-mbox.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/riscv,rpmi-shmem-mbox.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V Platform Management Interface (RPMI) shared memory mailbox + +maintainers: + - Anup Patel <anup@brainfault.org> + +description: | + The RISC-V Platform Management Interface (RPMI) [1] defines a common shared + memory based RPMI transport. This RPMI shared memory transport integrates as + mailbox controller in the SBI implementation or supervisor software whereas + each RPMI service group is mailbox client in the SBI implementation and + supervisor software. + + =========================================== + References + =========================================== + + [1] RISC-V Platform Management Interface (RPMI) v1.0 (or higher) + https://github.com/riscv-non-isa/riscv-rpmi/releases + +properties: + compatible: + const: riscv,rpmi-shmem-mbox + + reg: + minItems: 2 + items: + - description: A2P request queue base address + - description: P2A acknowledgment queue base address + - description: P2A request queue base address + - description: A2P acknowledgment queue base address + - description: A2P doorbell address + + reg-names: + minItems: 2 + items: + - const: a2p-req + - const: p2a-ack + - enum: [ p2a-req, a2p-doorbell ] + - const: a2p-ack + - const: a2p-doorbell + + interrupts: + maxItems: 1 + description: + The RPMI shared memory transport supports P2A doorbell as a wired + interrupt and this property specifies the interrupt source. + + msi-parent: + description: + The RPMI shared memory transport supports P2A doorbell as a system MSI + and this property specifies the target MSI controller. + + riscv,slot-size: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 64 + description: + Power-of-2 RPMI slot size of the RPMI shared memory transport. + + riscv,a2p-doorbell-value: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 0x1 + description: + Value written to the 32-bit A2P doorbell register. + + riscv,p2a-doorbell-sysmsi-index: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The RPMI shared memory transport supports P2A doorbell as a system MSI + and this property specifies system MSI index to be used for configuring + the P2A doorbell MSI. + + "#mbox-cells": + const: 1 + description: + The first cell specifies RPMI service group ID. + +required: + - compatible + - reg + - reg-names + - riscv,slot-size + - "#mbox-cells" + +anyOf: + - required: + - interrupts + - required: + - msi-parent + +additionalProperties: false + +examples: + - | + // Example 1 (RPMI shared memory with only 2 queues): + mailbox@10080000 { + compatible = "riscv,rpmi-shmem-mbox"; + reg = <0x10080000 0x10000>, + <0x10090000 0x10000>; + reg-names = "a2p-req", "p2a-ack"; + msi-parent = <&imsic_mlevel>; + riscv,slot-size = <64>; + #mbox-cells = <1>; + }; + - | + // Example 2 (RPMI shared memory with only 4 queues): + mailbox@10001000 { + compatible = "riscv,rpmi-shmem-mbox"; + reg = <0x10001000 0x800>, + <0x10001800 0x800>, + <0x10002000 0x800>, + <0x10002800 0x800>, + <0x10003000 0x4>; + reg-names = "a2p-req", "p2a-ack", "p2a-req", "a2p-ack", "a2p-doorbell"; + msi-parent = <&imsic_mlevel>; + riscv,slot-size = <64>; + riscv,a2p-doorbell-value = <0x00008000>; + #mbox-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/mailbox/riscv,sbi-mpxy-mbox.yaml b/Documentation/devicetree/bindings/mailbox/riscv,sbi-mpxy-mbox.yaml new file mode 100644 index 000000000000..061437a0b45a --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/riscv,sbi-mpxy-mbox.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/riscv,sbi-mpxy-mbox.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V SBI Message Proxy (MPXY) extension based mailbox + +maintainers: + - Anup Patel <anup@brainfault.org> + +description: | + The RISC-V SBI Message Proxy (MPXY) extension [1] allows supervisor + software to send messages through the SBI implementation (M-mode + firmware or HS-mode hypervisor). The underlying message protocol + and message format used by the supervisor software could be some + other standard protocol compatible with the SBI MPXY extension + (such as RISC-V Platform Management Interface (RPMI) [2]). + + =========================================== + References + =========================================== + + [1] RISC-V Supervisor Binary Interface (SBI) v3.0 (or higher) + https://github.com/riscv-non-isa/riscv-sbi-doc/releases + + [2] RISC-V Platform Management Interface (RPMI) v1.0 (or higher) + https://github.com/riscv-non-isa/riscv-rpmi/releases + +properties: + compatible: + const: riscv,sbi-mpxy-mbox + + "#mbox-cells": + const: 2 + description: + The first cell specifies channel_id of the SBI MPXY channel, + the second cell specifies MSG_PROT_ID of the SBI MPXY channel + +required: + - compatible + - "#mbox-cells" + +additionalProperties: false + +examples: + - | + mailbox { + compatible = "riscv,sbi-mpxy-mbox"; + #mbox-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst index 5f24570f72e9..ce767b1eccf2 100644 --- a/Documentation/devicetree/bindings/submitting-patches.rst +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -66,7 +66,7 @@ I. For patch submitters any DTS patches, regardless whether using existing or new bindings, should be placed at the end of patchset to indicate no dependency of drivers on the DTS. DTS will be anyway applied through separate tree or branch, so - different order would indicate the serie is non-bisectable. + different order would indicate the series is non-bisectable. If a driver subsystem maintainer prefers to apply entire set, instead of their relevant portion of patchset, please split the DTS patches into diff --git a/Documentation/devicetree/bindings/ufs/qcom,sc7180-ufshc.yaml b/Documentation/devicetree/bindings/ufs/qcom,sc7180-ufshc.yaml new file mode 100644 index 000000000000..d94ef4e6b85a --- /dev/null +++ b/Documentation/devicetree/bindings/ufs/qcom,sc7180-ufshc.yaml @@ -0,0 +1,167 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ufs/qcom,sc7180-ufshc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SC7180 and Other SoCs UFS Controllers + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +# Select only our matches, not all jedec,ufs-2.0 +select: + properties: + compatible: + contains: + enum: + - qcom,msm8998-ufshc + - qcom,qcs8300-ufshc + - qcom,sa8775p-ufshc + - qcom,sc7180-ufshc + - qcom,sc7280-ufshc + - qcom,sc8180x-ufshc + - qcom,sc8280xp-ufshc + - qcom,sm8250-ufshc + - qcom,sm8350-ufshc + - qcom,sm8450-ufshc + - qcom,sm8550-ufshc + required: + - compatible + +properties: + compatible: + items: + - enum: + - qcom,msm8998-ufshc + - qcom,qcs8300-ufshc + - qcom,sa8775p-ufshc + - qcom,sc7180-ufshc + - qcom,sc7280-ufshc + - qcom,sc8180x-ufshc + - qcom,sc8280xp-ufshc + - qcom,sm8250-ufshc + - qcom,sm8350-ufshc + - qcom,sm8450-ufshc + - qcom,sm8550-ufshc + - const: qcom,ufshc + - const: jedec,ufs-2.0 + + reg: + maxItems: 1 + + reg-names: + items: + - const: std + + clocks: + minItems: 7 + maxItems: 8 + + clock-names: + minItems: 7 + items: + - const: core_clk + - const: bus_aggr_clk + - const: iface_clk + - const: core_clk_unipro + - const: ref_clk + - const: tx_lane0_sync_clk + - const: rx_lane0_sync_clk + - const: rx_lane1_sync_clk + + qcom,ice: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the Inline Crypto Engine node + +required: + - compatible + - reg + +allOf: + - $ref: qcom,ufs-common.yaml + + - if: + properties: + compatible: + contains: + enum: + - qcom,sc7180-ufshc + then: + properties: + clocks: + maxItems: 7 + clock-names: + maxItems: 7 + else: + properties: + clocks: + minItems: 8 + clock-names: + minItems: 8 + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sm8450.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interconnect/qcom,sm8450.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + ufs@1d84000 { + compatible = "qcom,sm8450-ufshc", "qcom,ufshc", + "jedec,ufs-2.0"; + reg = <0x0 0x01d84000 0x0 0x3000>; + interrupts = <GIC_SPI 265 IRQ_TYPE_LEVEL_HIGH>; + phys = <&ufs_mem_phy_lanes>; + phy-names = "ufsphy"; + lanes-per-direction = <2>; + #reset-cells = <1>; + resets = <&gcc GCC_UFS_PHY_BCR>; + reset-names = "rst"; + reset-gpios = <&tlmm 210 GPIO_ACTIVE_LOW>; + + vcc-supply = <&vreg_l7b_2p5>; + vcc-max-microamp = <1100000>; + vccq-supply = <&vreg_l9b_1p2>; + vccq-max-microamp = <1200000>; + + power-domains = <&gcc UFS_PHY_GDSC>; + iommus = <&apps_smmu 0xe0 0x0>; + interconnects = <&aggre1_noc MASTER_UFS_MEM &mc_virt SLAVE_EBI1>, + <&gem_noc MASTER_APPSS_PROC &config_noc SLAVE_UFS_MEM_CFG>; + interconnect-names = "ufs-ddr", "cpu-ufs"; + + clocks = <&gcc GCC_UFS_PHY_AXI_CLK>, + <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>, + <&gcc GCC_UFS_PHY_AHB_CLK>, + <&gcc GCC_UFS_PHY_UNIPRO_CORE_CLK>, + <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_UFS_PHY_TX_SYMBOL_0_CLK>, + <&gcc GCC_UFS_PHY_RX_SYMBOL_0_CLK>, + <&gcc GCC_UFS_PHY_RX_SYMBOL_1_CLK>; + clock-names = "core_clk", + "bus_aggr_clk", + "iface_clk", + "core_clk_unipro", + "ref_clk", + "tx_lane0_sync_clk", + "rx_lane0_sync_clk", + "rx_lane1_sync_clk"; + freq-table-hz = <75000000 300000000>, + <0 0>, + <0 0>, + <75000000 300000000>, + <75000000 300000000>, + <0 0>, + <0 0>, + <0 0>; + qcom,ice = <&ice>; + }; + }; diff --git a/Documentation/devicetree/bindings/ufs/qcom,sm8650-ufshc.yaml b/Documentation/devicetree/bindings/ufs/qcom,sm8650-ufshc.yaml new file mode 100644 index 000000000000..aaa0bbb5bfe1 --- /dev/null +++ b/Documentation/devicetree/bindings/ufs/qcom,sm8650-ufshc.yaml @@ -0,0 +1,178 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ufs/qcom,sm8650-ufshc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8650 and Other SoCs UFS Controllers + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +# Select only our matches, not all jedec,ufs-2.0 +select: + properties: + compatible: + contains: + enum: + - qcom,sm8650-ufshc + - qcom,sm8750-ufshc + required: + - compatible + +properties: + compatible: + items: + - enum: + - qcom,sm8650-ufshc + - qcom,sm8750-ufshc + - const: qcom,ufshc + - const: jedec,ufs-2.0 + + reg: + minItems: 1 + maxItems: 2 + + reg-names: + minItems: 1 + items: + - const: std + - const: mcq + + clocks: + minItems: 8 + maxItems: 8 + + clock-names: + items: + - const: core_clk + - const: bus_aggr_clk + - const: iface_clk + - const: core_clk_unipro + - const: ref_clk + - const: tx_lane0_sync_clk + - const: rx_lane0_sync_clk + - const: rx_lane1_sync_clk + + qcom,ice: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the Inline Crypto Engine node + +required: + - compatible + - reg + +allOf: + - $ref: qcom,ufs-common.yaml + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8650-gcc.h> + #include <dt-bindings/clock/qcom,sm8650-tcsr.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interconnect/qcom,icc.h> + #include <dt-bindings/interconnect/qcom,sm8650-rpmh.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + ufshc@1d84000 { + compatible = "qcom,sm8650-ufshc", "qcom,ufshc", "jedec,ufs-2.0"; + reg = <0x0 0x01d84000 0x0 0x3000>; + + interrupts = <GIC_SPI 265 IRQ_TYPE_LEVEL_HIGH 0>; + + clocks = <&gcc GCC_UFS_PHY_AXI_CLK>, + <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>, + <&gcc GCC_UFS_PHY_AHB_CLK>, + <&gcc GCC_UFS_PHY_UNIPRO_CORE_CLK>, + <&tcsr TCSR_UFS_PAD_CLKREF_EN>, + <&gcc GCC_UFS_PHY_TX_SYMBOL_0_CLK>, + <&gcc GCC_UFS_PHY_RX_SYMBOL_0_CLK>, + <&gcc GCC_UFS_PHY_RX_SYMBOL_1_CLK>; + clock-names = "core_clk", + "bus_aggr_clk", + "iface_clk", + "core_clk_unipro", + "ref_clk", + "tx_lane0_sync_clk", + "rx_lane0_sync_clk", + "rx_lane1_sync_clk"; + + resets = <&gcc GCC_UFS_PHY_BCR>; + reset-names = "rst"; + reset-gpios = <&tlmm 210 GPIO_ACTIVE_LOW>; + + interconnects = <&aggre1_noc MASTER_UFS_MEM QCOM_ICC_TAG_ALWAYS + &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>, + <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ACTIVE_ONLY + &config_noc SLAVE_UFS_MEM_CFG QCOM_ICC_TAG_ACTIVE_ONLY>; + interconnect-names = "ufs-ddr", + "cpu-ufs"; + + power-domains = <&gcc UFS_PHY_GDSC>; + required-opps = <&rpmhpd_opp_nom>; + + operating-points-v2 = <&ufs_opp_table>; + + iommus = <&apps_smmu 0x60 0>; + + lanes-per-direction = <2>; + qcom,ice = <&ice>; + + phys = <&ufs_mem_phy>; + phy-names = "ufsphy"; + + #reset-cells = <1>; + + vcc-supply = <&vreg_l7b_2p5>; + vcc-max-microamp = <1100000>; + vccq-supply = <&vreg_l9b_1p2>; + vccq-max-microamp = <1200000>; + + ufs_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-100000000 { + opp-hz = /bits/ 64 <100000000>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <100000000>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <0>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-201500000 { + opp-hz = /bits/ 64 <201500000>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <201500000>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <0>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-403000000 { + opp-hz = /bits/ 64 <403000000>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <403000000>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <0>, + /bits/ 64 <0>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/ufs/qcom,ufs-common.yaml b/Documentation/devicetree/bindings/ufs/qcom,ufs-common.yaml new file mode 100644 index 000000000000..962dffcd28b4 --- /dev/null +++ b/Documentation/devicetree/bindings/ufs/qcom,ufs-common.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ufs/qcom,ufs-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Universal Flash Storage (UFS) Controller Common Properties + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +properties: + clocks: + minItems: 7 + maxItems: 9 + + clock-names: + minItems: 7 + maxItems: 9 + + dma-coherent: true + + interconnects: + minItems: 2 + maxItems: 2 + + interconnect-names: + items: + - const: ufs-ddr + - const: cpu-ufs + + iommus: + minItems: 1 + maxItems: 2 + + phys: + maxItems: 1 + + phy-names: + items: + - const: ufsphy + + power-domains: + maxItems: 1 + + required-opps: + maxItems: 1 + + resets: + maxItems: 1 + + '#reset-cells': + const: 1 + + reset-names: + items: + - const: rst + + reset-gpios: + maxItems: 1 + description: + GPIO connected to the RESET pin of the UFS memory device. + +allOf: + - $ref: ufs-common.yaml + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml index 6c6043d9809e..1dd41f6d5258 100644 --- a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml +++ b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml @@ -15,7 +15,15 @@ select: properties: compatible: contains: - const: qcom,ufshc + enum: + - qcom,msm8994-ufshc + - qcom,msm8996-ufshc + - qcom,qcs615-ufshc + - qcom,sdm845-ufshc + - qcom,sm6115-ufshc + - qcom,sm6125-ufshc + - qcom,sm6350-ufshc + - qcom,sm8150-ufshc required: - compatible @@ -25,61 +33,15 @@ properties: - enum: - qcom,msm8994-ufshc - qcom,msm8996-ufshc - - qcom,msm8998-ufshc - qcom,qcs615-ufshc - - qcom,qcs8300-ufshc - - qcom,sa8775p-ufshc - - qcom,sc7180-ufshc - - qcom,sc7280-ufshc - - qcom,sc8180x-ufshc - - qcom,sc8280xp-ufshc - qcom,sdm845-ufshc - qcom,sm6115-ufshc - qcom,sm6125-ufshc - qcom,sm6350-ufshc - qcom,sm8150-ufshc - - qcom,sm8250-ufshc - - qcom,sm8350-ufshc - - qcom,sm8450-ufshc - - qcom,sm8550-ufshc - - qcom,sm8650-ufshc - - qcom,sm8750-ufshc - const: qcom,ufshc - const: jedec,ufs-2.0 - clocks: - minItems: 7 - maxItems: 9 - - clock-names: - minItems: 7 - maxItems: 9 - - dma-coherent: true - - interconnects: - minItems: 2 - maxItems: 2 - - interconnect-names: - items: - - const: ufs-ddr - - const: cpu-ufs - - iommus: - minItems: 1 - maxItems: 2 - - phys: - maxItems: 1 - - phy-names: - items: - - const: ufsphy - - power-domains: - maxItems: 1 - qcom,ice: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the Inline Crypto Engine node @@ -93,93 +55,12 @@ properties: - const: std - const: ice - required-opps: - maxItems: 1 - - resets: - maxItems: 1 - - '#reset-cells': - const: 1 - - reset-names: - items: - - const: rst - - reset-gpios: - maxItems: 1 - description: - GPIO connected to the RESET pin of the UFS memory device. - required: - compatible - reg allOf: - - $ref: ufs-common.yaml - - - if: - properties: - compatible: - contains: - enum: - - qcom,sc7180-ufshc - then: - properties: - clocks: - minItems: 7 - maxItems: 7 - clock-names: - items: - - const: core_clk - - const: bus_aggr_clk - - const: iface_clk - - const: core_clk_unipro - - const: ref_clk - - const: tx_lane0_sync_clk - - const: rx_lane0_sync_clk - reg: - maxItems: 1 - reg-names: - maxItems: 1 - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8998-ufshc - - qcom,qcs8300-ufshc - - qcom,sa8775p-ufshc - - qcom,sc7280-ufshc - - qcom,sc8180x-ufshc - - qcom,sc8280xp-ufshc - - qcom,sm8250-ufshc - - qcom,sm8350-ufshc - - qcom,sm8450-ufshc - - qcom,sm8550-ufshc - - qcom,sm8650-ufshc - - qcom,sm8750-ufshc - then: - properties: - clocks: - minItems: 8 - maxItems: 8 - clock-names: - items: - - const: core_clk - - const: bus_aggr_clk - - const: iface_clk - - const: core_clk_unipro - - const: ref_clk - - const: tx_lane0_sync_clk - - const: rx_lane0_sync_clk - - const: rx_lane1_sync_clk - reg: - minItems: 1 - maxItems: 1 - reg-names: - maxItems: 1 + - $ref: qcom,ufs-common.yaml - if: properties: @@ -297,10 +178,10 @@ unevaluatedProperties: false examples: - | - #include <dt-bindings/clock/qcom,gcc-sm8450.h> + #include <dt-bindings/clock/qcom,gcc-sm8150.h> #include <dt-bindings/clock/qcom,rpmh.h> #include <dt-bindings/gpio/gpio.h> - #include <dt-bindings/interconnect/qcom,sm8450.h> + #include <dt-bindings/interconnect/qcom,sm8150.h> #include <dt-bindings/interrupt-controller/arm-gic.h> soc { @@ -308,9 +189,12 @@ examples: #size-cells = <2>; ufs@1d84000 { - compatible = "qcom,sm8450-ufshc", "qcom,ufshc", + compatible = "qcom,sm8150-ufshc", "qcom,ufshc", "jedec,ufs-2.0"; - reg = <0 0x01d84000 0 0x3000>; + reg = <0x0 0x01d84000 0x0 0x2500>, + <0x0 0x01d90000 0x0 0x8000>; + reg-names = "std", "ice"; + interrupts = <GIC_SPI 265 IRQ_TYPE_LEVEL_HIGH>; phys = <&ufs_mem_phy_lanes>; phy-names = "ufsphy"; @@ -326,19 +210,8 @@ examples: vccq-max-microamp = <1200000>; power-domains = <&gcc UFS_PHY_GDSC>; - iommus = <&apps_smmu 0xe0 0x0>; - interconnects = <&aggre1_noc MASTER_UFS_MEM &mc_virt SLAVE_EBI1>, - <&gem_noc MASTER_APPSS_PROC &config_noc SLAVE_UFS_MEM_CFG>; - interconnect-names = "ufs-ddr", "cpu-ufs"; + iommus = <&apps_smmu 0x300 0>; - clock-names = "core_clk", - "bus_aggr_clk", - "iface_clk", - "core_clk_unipro", - "ref_clk", - "tx_lane0_sync_clk", - "rx_lane0_sync_clk", - "rx_lane1_sync_clk"; clocks = <&gcc GCC_UFS_PHY_AXI_CLK>, <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>, <&gcc GCC_UFS_PHY_AHB_CLK>, @@ -346,15 +219,25 @@ examples: <&rpmhcc RPMH_CXO_CLK>, <&gcc GCC_UFS_PHY_TX_SYMBOL_0_CLK>, <&gcc GCC_UFS_PHY_RX_SYMBOL_0_CLK>, - <&gcc GCC_UFS_PHY_RX_SYMBOL_1_CLK>; - freq-table-hz = <75000000 300000000>, + <&gcc GCC_UFS_PHY_RX_SYMBOL_1_CLK>, + <&gcc GCC_UFS_PHY_ICE_CORE_CLK>; + clock-names = "core_clk", + "bus_aggr_clk", + "iface_clk", + "core_clk_unipro", + "ref_clk", + "tx_lane0_sync_clk", + "rx_lane0_sync_clk", + "rx_lane1_sync_clk", + "ice_core_clk"; + freq-table-hz = <37500000 300000000>, + <0 0>, + <0 0>, + <37500000 300000000>, <0 0>, <0 0>, - <75000000 300000000>, - <75000000 300000000>, <0 0>, <0 0>, - <0 0>; - qcom,ice = <&ice>; + <0 300000000>; }; }; diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml index 31fe7f30ff5b..9f04f34d8c5a 100644 --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml @@ -89,6 +89,22 @@ properties: msi-parent: true + limit-hs-gear: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 6 + default: 6 + description: + Restricts the maximum HS gear used in both TX and RX directions. + + limit-gear-rate: + $ref: /schemas/types.yaml#/definitions/string + enum: [rate-a, rate-b] + default: rate-b + description: + Restricts the UFS controller to rate-a or rate-b for both TX and + RX directions. + dependencies: freq-table-hz: [ clocks ] operating-points-v2: [ clocks, clock-names ] diff --git a/Documentation/driver-api/cxl/devices/device-types.rst b/Documentation/driver-api/cxl/devices/device-types.rst index 923f5d89bc04..7f69dfa4509b 100644 --- a/Documentation/driver-api/cxl/devices/device-types.rst +++ b/Documentation/driver-api/cxl/devices/device-types.rst @@ -22,7 +22,7 @@ The basic interaction protocol, similar to PCIe configuration mechanisms. Typically used for initialization, configuration, and I/O access for anything other than memory (CXL.mem) or cache (CXL.cache) operations. -The Linux CXL driver exposes access to .io functionalty via the various sysfs +The Linux CXL driver exposes access to .io functionality via the various sysfs interfaces and /dev/cxl/ devices (which exposes direct access to device mailboxes). diff --git a/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst b/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst index aebda0eb3e17..a4c3fb51ea7d 100644 --- a/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst +++ b/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst @@ -10,7 +10,7 @@ has a single CXL memory expander with a 4GB of memory. Things to note: * Cross-Bridge interleave is not being used. -* The expanders are in two separate but adjascent memory regions. +* The expanders are in two separate but adjacent memory regions. * This CEDT/SRAT describes one node per device * The expanders have the same performance and will be in the same memory tier. diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 5c7e8194bef9..d1aaa961cac4 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -16,7 +16,7 @@ Bus-Independent Device Accesses Introduction ============ -Linux provides an API which abstracts performing IO across all busses +Linux provides an API which abstracts performing IO across all buses and devices, allowing device drivers to be written independently of bus type. @@ -71,7 +71,7 @@ can be compiler optimised, you can use __readb() and friends to indicate the relaxed ordering. Use this with care. While the basic functions are defined to be synchronous with respect to -each other and ordered with respect to each other the busses the devices +each other and ordered with respect to each other the buses the devices sit on may themselves have asynchronicity. In particular many authors are burned by the fact that PCI bus writes are posted asynchronously. A driver author must issue a read from the same device to ensure that diff --git a/Documentation/driver-api/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst index e98d0ab4a9b6..b3f447bf9f07 100644 --- a/Documentation/driver-api/driver-model/overview.rst +++ b/Documentation/driver-api/driver-model/overview.rst @@ -22,7 +22,7 @@ uniformity across the different bus types. The current driver model provides a common, uniform data model for describing a bus and the devices that can appear under the bus. The unified bus -model includes a set of common attributes which all busses carry, and a set +model includes a set of common attributes which all buses carry, and a set of common callbacks, such as device discovery during bus probing, bus shutdown, bus power management, etc. diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst index 7beb8a9648c5..cf5ff48d3115 100644 --- a/Documentation/driver-api/driver-model/platform.rst +++ b/Documentation/driver-api/driver-model/platform.rst @@ -4,7 +4,7 @@ Platform Devices and Drivers See <linux/platform_device.h> for the driver model interface to the platform bus: platform_device, and platform_driver. This pseudo-bus -is used to connect devices on busses with minimal infrastructure, +is used to connect devices on buses with minimal infrastructure, like those used to integrate peripherals on many system-on-chip processors, or some "legacy" PC interconnects; as opposed to large formally specified ones like PCI or USB. diff --git a/Documentation/driver-api/eisa.rst b/Documentation/driver-api/eisa.rst index b33ebe1ec9ed..3563e5f7e98d 100644 --- a/Documentation/driver-api/eisa.rst +++ b/Documentation/driver-api/eisa.rst @@ -8,9 +8,9 @@ This document groups random notes about porting EISA drivers to the new EISA/sysfs API. Starting from version 2.5.59, the EISA bus is almost given the same -status as other much more mainstream busses such as PCI or USB. This +status as other much more mainstream buses such as PCI or USB. This has been possible through sysfs, which defines a nice enough set of -abstractions to manage busses, devices and drivers. +abstractions to manage buses, devices and drivers. Although the new API is quite simple to use, converting existing drivers to the new infrastructure is not an easy task (mostly because @@ -205,7 +205,7 @@ Random notes Converting an EISA driver to the new API mostly involves *deleting* code (since probing is now in the core EISA code). Unfortunately, most drivers share their probing routine between ISA, and EISA. Special -care must be taken when ripping out the EISA code, so other busses +care must be taken when ripping out the EISA code, so other buses won't suffer from these surgical strikes... You *must not* expect any EISA device to be detected when returning diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst index 23a0b93c62b1..fe338f8085db 100644 --- a/Documentation/driver-api/i3c/protocol.rst +++ b/Documentation/driver-api/i3c/protocol.rst @@ -165,8 +165,8 @@ The first thing attached to an HDR command is the HDR mode. There are currently for more details): * HDR-DDR: Double Data Rate mode -* HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices -* HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices +* HDR-TSP: Ternary Symbol Pure. Only usable on buses with no I2C devices +* HDR-TSL: Ternary Symbol Legacy. Usable on buses with I2C devices When sending an HDR command, the whole bus has to enter HDR mode, which is done using a broadcast CCC command. diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst index 2cc6c898ab90..f52ab2df2569 100644 --- a/Documentation/driver-api/ipmi.rst +++ b/Documentation/driver-api/ipmi.rst @@ -617,12 +617,12 @@ Note that the address you give here is the I2C address, not the IPMI address. So if you want your MC address to be 0x60, you put 0x30 here. See the I2C driver info for more details. -Command bridging to other IPMB busses through this interface does not +Command bridging to other IPMB buses through this interface does not work. The receive message queue is not implemented, by design. There is only one receive message queue on a BMC, and that is meant for the host drivers, not something on the IPMB bus. -A BMC may have multiple IPMB busses, which bus your device sits on +A BMC may have multiple IPMB buses, which bus your device sits on depends on how the system is wired. You can fetch the channels with "ipmitool channel info <n>" where <n> is the channel, with the channels being 0-7 and try the IPMB channels. diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst index 0b8c9cde8ee4..22e1b13ecde9 100644 --- a/Documentation/driver-api/media/tx-rx.rst +++ b/Documentation/driver-api/media/tx-rx.rst @@ -12,7 +12,7 @@ CSI-2 receiver in an SoC. Bus types --------- -The following busses are the most common. This section discusses these two only. +The following buses are the most common. This section discusses these two only. MIPI CSI-2 ^^^^^^^^^^ @@ -36,7 +36,7 @@ Transmitter drivers Transmitter drivers generally need to provide the receiver drivers with the configuration of the transmitter. What is required depends on the type of the -bus. These are common for both busses. +bus. These are common for both buses. Media bus pixel code ^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index c205efa4d45b..959ba1cc0263 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -230,7 +230,7 @@ LIBNVDIMM/LIBNDCTL: Bus A bus has a 1:1 relationship with an NFIT. The current expectation for ACPI based systems is that there is only ever one platform-global NFIT. That said, it is trivial to register multiple NFITs, the specification -does not preclude it. The infrastructure supports multiple busses and +does not preclude it. The infrastructure supports multiple buses and we use this capability to test multiple NFIT configurations in the unit test. diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst index 8208924e513e..afc6ddd80fa1 100644 --- a/Documentation/driver-api/pin-control.rst +++ b/Documentation/driver-api/pin-control.rst @@ -1202,22 +1202,24 @@ default state like this: { /* Allocate a state holder named "foo" etc */ struct foo_state *foo = ...; + int ret; foo->p = devm_pinctrl_get(&device); if (IS_ERR(foo->p)) { - /* FIXME: clean up "foo" here */ - return PTR_ERR(foo->p); + ret = PTR_ERR(foo->p); + foo->p = NULL; + return ret; } foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); if (IS_ERR(foo->s)) { - /* FIXME: clean up "foo" here */ + devm_pinctrl_put(foo->p); return PTR_ERR(foo->s); } ret = pinctrl_select_state(foo->p, foo->s); if (ret < 0) { - /* FIXME: clean up "foo" here */ + devm_pinctrl_put(foo->p); return ret; } } diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 8d86d5da4023..36d5c9c9fd11 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -255,7 +255,7 @@ get registered: a child can never be registered, probed or resumed before its parent; and can't be removed or suspended after that parent. The policy is that the device hierarchy should match hardware bus topology. -[Or at least the control bus, for devices which use multiple busses.] +[Or at least the control bus, for devices which use multiple buses.] In particular, this means that a device registration may fail if the parent of the device is suspending (i.e. has been chosen by the PM core as the next device to suspend) or has already suspended, as well as after all of the other @@ -493,7 +493,7 @@ states, like S3). Drivers must also be prepared to notice that the device has been removed while the system was powered down, whenever that's physically possible. -PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses +PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of buses where common Linux platforms will see such removal. Details of how drivers will notice and handle such removals are currently bus-specific, and often involve a separate thread. diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index bf2be96cc2d6..8bbdfb018c53 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -18,7 +18,7 @@ optical drives, test equipment, and medical devices) to a host computer. Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen out of use, the SCSI command set is more widely used than ever to -communicate with devices over a number of different busses. +communicate with devices over a number of different buses. The `SCSI protocol <https://www.t10.org/scsi-3.htm>`__ is a big-endian peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16 @@ -286,7 +286,7 @@ Parallel SCSI (SPI) transport class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The file drivers/scsi/scsi_transport_spi.c defines transport -attributes for traditional (fast/wide/ultra) SCSI busses. +attributes for traditional (fast/wide/ultra) SCSI buses. .. kernel-doc:: drivers/scsi/scsi_transport_spi.c :export: diff --git a/Documentation/driver-api/spi.rst b/Documentation/driver-api/spi.rst index f28887045049..74eca6735042 100644 --- a/Documentation/driver-api/spi.rst +++ b/Documentation/driver-api/spi.rst @@ -13,7 +13,7 @@ additional chipselect line is usually active-low (nCS); four signals are normally used for each peripheral, plus sometimes an interrupt. The SPI bus facilities listed here provide a generalized interface to -declare SPI busses and devices, manage them according to the standard +declare SPI buses and devices, manage them according to the standard Linux driver model, and perform input/output operations. At this time, only "master" side interfaces are supported, where Linux talks to SPI peripherals and does not implement such a peripheral itself. (Interfaces diff --git a/Documentation/driver-api/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst index c21d10838bc5..c679502f01c7 100644 --- a/Documentation/driver-api/thermal/exynos_thermal_emulation.rst +++ b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst @@ -28,13 +28,13 @@ changed into it. delay of changing temperature. However, this node only uses same delay of real sensing time, 938us.) -Exynos emulation mode requires synchronous of value changing and -enabling. It means when you want to update the any value of delay or -next temperature, then you have to enable emulation mode at the same -time. (Or you have to keep the mode enabling.) If you don't, it fails to -change the value to updated one and just use last succeessful value -repeatedly. That's why this node gives users the right to change -termerpature only. Just one interface makes it more simply to use. +Exynos emulation mode requires that value changes and enabling are performed +synchronously. This means that when you want to update any value, such as the +delay or the next temperature, you must enable emulation mode at the same +time (or keep the mode enabled). If you do not, the value will fail to update +and the last successful value will continue to be used. For this reason, +this node only allows users to change the temperature. Providing a single +interface makes it simpler to use. Disabling emulation mode only requires writing value 0 to sysfs node. diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst index c1e13107c50e..12260f704a01 100644 --- a/Documentation/driver-api/usb/hotplug.rst +++ b/Documentation/driver-api/usb/hotplug.rst @@ -5,7 +5,7 @@ Linux Hotplugging ================= -In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices +In hotpluggable buses like USB (and Cardbus PCI), end-users plug devices into the bus with power on. In most cases, users expect the devices to become immediately usable. That means the system must do many things, including: diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index cfa8797ea614..fcb24d0500d9 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -3,6 +3,7 @@ Linux USB API ============= .. toctree:: + :maxdepth: 1 usb gadget diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 976fb4221062..7f2f41e80c1c 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -13,7 +13,7 @@ structure, with the host as the root (the system's master), hubs as interior nodes, and peripherals as leaves (and slaves). Modern PCs support several such trees of USB devices, usually a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy -USB 2.0 (480 MBit/s) busses just in case. +USB 2.0 (480 MBit/s) buses just in case. That master/slave asymmetry was designed-in for a number of reasons, one being ease of use. It is not physically possible to mistake upstream and @@ -42,7 +42,7 @@ two. One is intended for *general-purpose* drivers (exposed through driver frameworks), and the other is for drivers that are *part of the core*. Such core drivers include the *hub* driver (which manages trees of USB devices) and several different kinds of *host controller -drivers*, which control individual busses. +drivers*, which control individual buses. The device model seen by USB drivers is relatively complex. diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 212f7003cfba..a98a5cb0b0d8 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -39,11 +39,13 @@ Also, you will need to select at least one compiled-in font, but if you don't do anything, the kernel configuration tool will select one for you, usually an 8x16 font. -GOTCHA: A common bug report is enabling the framebuffer without enabling the -framebuffer console. Depending on the driver, you may get a blanked or -garbled display, but the system still boots to completion. If you are -fortunate to have a driver that does not alter the graphics chip, then you -will still get a VGA console. +.. admonition:: GOTCHA + + A common bug report is enabling the framebuffer without enabling the + framebuffer console. Depending on the driver, you may get a blanked or + garbled display, but the system still boots to completion. If you are + fortunate to have a driver that does not alter the graphics chip, then you + will still get a VGA console. B. Loading ========== @@ -74,6 +76,7 @@ Possible scenarios: over the console. C. Boot options +=============== The framebuffer console has several, largely unknown, boot options that can change its behavior. @@ -116,9 +119,10 @@ C. Boot options outside the given range will still be controlled by the standard console driver. - NOTE: For x86 machines, the standard console is the VGA console which - is typically located on the same video card. Thus, the consoles that - are controlled by the VGA console will be garbled. + .. note:: + For x86 machines, the standard console is the VGA console which + is typically located on the same video card. Thus, the consoles that + are controlled by the VGA console will be garbled. 4. fbcon=rotate:<n> @@ -140,10 +144,11 @@ C. Boot options Console rotation will only become available if Framebuffer Console Rotation support is compiled in your kernel. - NOTE: This is purely console rotation. Any other applications that - use the framebuffer will remain at their 'normal' orientation. - Actually, the underlying fb driver is totally ignorant of console - rotation. + .. note:: + This is purely console rotation. Any other applications that + use the framebuffer will remain at their 'normal' orientation. + Actually, the underlying fb driver is totally ignorant of console + rotation. 5. fbcon=margin:<color> @@ -172,7 +177,8 @@ C. Boot options The value 'n' overrides the number of bootup logos. 0 disables the logo, and -1 gives the default which is the number of online CPUs. -C. Attaching, Detaching and Unloading +D. Attaching, Detaching and Unloading +===================================== Before going on to how to attach, detach and unload the framebuffer console, an illustration of the dependencies may help. @@ -249,11 +255,11 @@ restored properly. The following is one of the several methods that you can do: echo 1 > /sys/class/vtconsole/vtcon1/bind 8. Once fbcon is unbound, all drivers registered to the system will also -become unbound. This means that fbcon and individual framebuffer drivers -can be unloaded or reloaded at will. Reloading the drivers or fbcon will -automatically bind the console, fbcon and the drivers together. Unloading -all the drivers without unloading fbcon will make it impossible for the -console to bind fbcon. + become unbound. This means that fbcon and individual framebuffer drivers + can be unloaded or reloaded at will. Reloading the drivers or fbcon will + automatically bind the console, fbcon and the drivers together. Unloading + all the drivers without unloading fbcon will make it impossible for the + console to bind fbcon. Notes for vesafb users: ======================= diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index 7434b43c2ff8..83f77f55fc87 100644 --- a/Documentation/features/core/eBPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -7,7 +7,7 @@ | arch |status| ----------------------- | alpha: | TODO | - | arc: | TODO | + | arc: | ok | | arm: | ok | | arm64: | ok | | csky: | TODO | @@ -18,7 +18,7 @@ | mips: | ok | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | ok | | s390: | ok | diff --git a/Documentation/features/core/mseal_sys_mappings/arch-support.txt b/Documentation/features/core/mseal_sys_mappings/arch-support.txt index a3c24233eb9b..fa85381acc43 100644 --- a/Documentation/features/core/mseal_sys_mappings/arch-support.txt +++ b/Documentation/features/core/mseal_sys_mappings/arch-support.txt @@ -20,7 +20,7 @@ | openrisc: | N/A | | parisc: | TODO | | powerpc: | TODO | - | riscv: | TODO | + | riscv: | ok | | s390: | ok | | sh: | N/A | | sparc: | TODO | diff --git a/Documentation/features/core/thread-info-in-task/arch-support.txt b/Documentation/features/core/thread-info-in-task/arch-support.txt index 2afeb6bf6e64..f3d744c76061 100644 --- a/Documentation/features/core/thread-info-in-task/arch-support.txt +++ b/Documentation/features/core/thread-info-in-task/arch-support.txt @@ -24,7 +24,7 @@ | s390: | ok | | sh: | TODO | | sparc: | TODO | - | um: | TODO | + | um: | ok | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index a72330e25542..4f36fcbfb6d5 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -24,7 +24,7 @@ | s390: | ok | | sh: | ok | | sparc: | ok | - | um: | TODO | + | um: | ok | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 713a69fcd697..75c05d348c01 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -17,7 +17,7 @@ | microblaze: | TODO | | mips: | ok | | nios2: | TODO | - | openrisc: | TODO | + | openrisc: | ok | | parisc: | ok | | powerpc: | ok | | riscv: | ok | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 4d4bfac52970..d6100b226de5 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -18,7 +18,7 @@ | mips: | ok | | nios2: | ok | | openrisc: | ok | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | ok | | s390: | ok | diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 7ddb235aee9d..08194f194b94 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -116,7 +116,7 @@ cache_strategy=%s Select a strategy for cached decompression from now on: cluster for further reading. It still does in-place I/O decompression for the rest compressed physical clusters; - readaround Cache the both ends of incomplete compressed + readaround Cache both ends of incomplete compressed physical clusters for further reading. It still does in-place I/O decompression for the rest compressed physical clusters. diff --git a/Documentation/filesystems/ext4/atomic_writes.rst b/Documentation/filesystems/ext4/atomic_writes.rst index aeb47ace738d..ae8995740aa8 100644 --- a/Documentation/filesystems/ext4/atomic_writes.rst +++ b/Documentation/filesystems/ext4/atomic_writes.rst @@ -14,7 +14,7 @@ I/O) on regular files with extents, provided the underlying storage device supports hardware atomic writes. This is supported in the following two ways: 1. **Single-fsblock Atomic Writes**: - EXT4's supports atomic write operations with a single filesystem block since + EXT4 supports atomic write operations with a single filesystem block since v6.13. In this the atomic write unit minimum and maximum sizes are both set to filesystem blocksize. e.g. doing atomic write of 16KB with 16KB filesystem blocksize on 64KB @@ -50,7 +50,7 @@ Multi-fsblock Implementation Details The bigalloc feature changes ext4 to allocate in units of multiple filesystem blocks, also known as clusters. With bigalloc each bit within block bitmap -represents cluster (power of 2 number of blocks) rather than individual +represents a cluster (power of 2 number of blocks) rather than individual filesystem blocks. EXT4 supports multi-fsblock atomic writes with bigalloc, subject to the following constraints. The minimum atomic write size is the larger of the fs @@ -189,7 +189,7 @@ The write must be aligned to the filesystem's block size and not exceed the filesystem's maximum atomic write unit size. See ``generic_atomic_write_valid()`` for more details. -``statx()`` system call with ``STATX_WRITE_ATOMIC`` flag can provides following +``statx()`` system call with ``STATX_WRITE_ATOMIC`` flag can provide following details: * ``stx_atomic_write_unit_min``: Minimum size of an atomic write request. diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index e5bb89452aff..a8d02fe5be83 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -1,8 +1,11 @@ .. SPDX-License-Identifier: GPL-2.0 -========================================== -WHAT IS Flash-Friendly File System (F2FS)? -========================================== +================================= +Flash-Friendly File System (F2FS) +================================= + +Overview +======== NAND flash memory-based storage devices, such as SSD, eMMC, and SD cards, have been equipped on a variety systems ranging from mobile to server systems. Since @@ -173,9 +176,12 @@ data_flush Enable data flushing before checkpoint in order to persist data of regular and symlink. reserve_root=%d Support configuring reserved space which is used for allocation from a privileged user with specified uid or - gid, unit: 4KB, the default limit is 0.2% of user blocks. -resuid=%d The user ID which may use the reserved blocks. -resgid=%d The group ID which may use the reserved blocks. + gid, unit: 4KB, the default limit is 12.5% of user blocks. +reserve_node=%d Support configuring reserved nodes which are used for + allocation from a privileged user with specified uid or + gid, the default limit is 12.5% of all nodes. +resuid=%d The user ID which may use the reserved blocks and nodes. +resgid=%d The group ID which may use the reserved blocks and nodes. fault_injection=%d Enable fault injection in all supported types with specified injection rate. fault_type=%d Support configuring fault injection type, should be @@ -291,9 +297,13 @@ compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo" "lz4", "zstd" and "lzo-rle" algorithm. compress_algorithm=%s:%d Control compress algorithm and its compress level, now, only "lz4" and "zstd" support compress level config. + + ========= =========== algorithm level range + ========= =========== lz4 3 - 16 zstd 1 - 22 + ========= =========== compress_log_size=%u Support configuring compress cluster size. The size will be 4KB * (1 << %u). The default and minimum sizes are 16KB. compress_extension=%s Support adding specified extension, so that f2fs can enable @@ -357,6 +367,7 @@ errors=%s Specify f2fs behavior on critical errors. This supports modes: panic immediately, continue without doing anything, and remount the partition in read-only mode. By default it uses "continue" mode. + ====================== =============== =============== ======== mode continue remount-ro panic ====================== =============== =============== ======== @@ -370,6 +381,25 @@ errors=%s Specify f2fs behavior on critical errors. This supports modes: ====================== =============== =============== ======== nat_bits Enable nat_bits feature to enhance full/empty nat blocks access, by default it's disabled. +lookup_mode=%s Control the directory lookup behavior for casefolded + directories. This option has no effect on directories + that do not have the casefold feature enabled. + + ================== ======================================== + Value Description + ================== ======================================== + perf (Default) Enforces a hash-only lookup. + The linear search fallback is always + disabled, ignoring the on-disk flag. + compat Enables the linear search fallback for + compatibility with directory entries + created by older kernel that used a + different case-folding algorithm. + This mode ignores the on-disk flag. + auto F2FS determines the mode based on the + on-disk `SB_ENC_NO_COMPAT_FALLBACK_FL` + flag. + ================== ======================================== ======================== ============================================================ Debugfs Entries @@ -795,11 +825,13 @@ ioctl(COLD) COLD_DATA WRITE_LIFE_EXTREME extension list " " -- buffered io +------------------------------------------------------------------ N/A COLD_DATA WRITE_LIFE_EXTREME N/A HOT_DATA WRITE_LIFE_SHORT N/A WARM_DATA WRITE_LIFE_NOT_SET -- direct io +------------------------------------------------------------------ WRITE_LIFE_EXTREME COLD_DATA WRITE_LIFE_EXTREME WRITE_LIFE_SHORT HOT_DATA WRITE_LIFE_SHORT WRITE_LIFE_NOT_SET WARM_DATA WRITE_LIFE_NOT_SET @@ -915,24 +947,26 @@ compression enabled files (refer to "Compression implementation" section for how enable compression on a regular inode). 1) compress_mode=fs -This is the default option. f2fs does automatic compression in the writeback of the -compression enabled files. + + This is the default option. f2fs does automatic compression in the writeback of the + compression enabled files. 2) compress_mode=user -This disables the automatic compression and gives the user discretion of choosing the -target file and the timing. The user can do manual compression/decompression on the -compression enabled files using F2FS_IOC_DECOMPRESS_FILE and F2FS_IOC_COMPRESS_FILE -ioctls like the below. -To decompress a file, + This disables the automatic compression and gives the user discretion of choosing the + target file and the timing. The user can do manual compression/decompression on the + compression enabled files using F2FS_IOC_DECOMPRESS_FILE and F2FS_IOC_COMPRESS_FILE + ioctls like the below. + +To decompress a file:: -fd = open(filename, O_WRONLY, 0); -ret = ioctl(fd, F2FS_IOC_DECOMPRESS_FILE); + fd = open(filename, O_WRONLY, 0); + ret = ioctl(fd, F2FS_IOC_DECOMPRESS_FILE); -To compress a file, +To compress a file:: -fd = open(filename, O_WRONLY, 0); -ret = ioctl(fd, F2FS_IOC_COMPRESS_FILE); + fd = open(filename, O_WRONLY, 0); + ret = ioctl(fd, F2FS_IOC_COMPRESS_FILE); NVMe Zoned Namespace devices ---------------------------- @@ -962,32 +996,32 @@ reserved and used by another filesystem or for different purposes. Once that external usage is complete, the device aliasing file can be deleted, releasing the reserved space back to F2FS for its own use. -<use-case> - -# ls /dev/vd* -/dev/vdb (32GB) /dev/vdc (32GB) -# mkfs.ext4 /dev/vdc -# mkfs.f2fs -c /dev/vdc@vdc.file /dev/vdb -# mount /dev/vdb /mnt/f2fs -# ls -l /mnt/f2fs -vdc.file -# df -h -/dev/vdb 64G 33G 32G 52% /mnt/f2fs - -# mount -o loop /dev/vdc /mnt/ext4 -# df -h -/dev/vdb 64G 33G 32G 52% /mnt/f2fs -/dev/loop7 32G 24K 30G 1% /mnt/ext4 -# umount /mnt/ext4 - -# f2fs_io getflags /mnt/f2fs/vdc.file -get a flag on /mnt/f2fs/vdc.file ret=0, flags=nocow(pinned),immutable -# f2fs_io setflags noimmutable /mnt/f2fs/vdc.file -get a flag on noimmutable ret=0, flags=800010 -set a flag on /mnt/f2fs/vdc.file ret=0, flags=noimmutable -# rm /mnt/f2fs/vdc.file -# df -h -/dev/vdb 64G 753M 64G 2% /mnt/f2fs +.. code-block:: + + # ls /dev/vd* + /dev/vdb (32GB) /dev/vdc (32GB) + # mkfs.ext4 /dev/vdc + # mkfs.f2fs -c /dev/vdc@vdc.file /dev/vdb + # mount /dev/vdb /mnt/f2fs + # ls -l /mnt/f2fs + vdc.file + # df -h + /dev/vdb 64G 33G 32G 52% /mnt/f2fs + + # mount -o loop /dev/vdc /mnt/ext4 + # df -h + /dev/vdb 64G 33G 32G 52% /mnt/f2fs + /dev/loop7 32G 24K 30G 1% /mnt/ext4 + # umount /mnt/ext4 + + # f2fs_io getflags /mnt/f2fs/vdc.file + get a flag on /mnt/f2fs/vdc.file ret=0, flags=nocow(pinned),immutable + # f2fs_io setflags noimmutable /mnt/f2fs/vdc.file + get a flag on noimmutable ret=0, flags=800010 + set a flag on /mnt/f2fs/vdc.file ret=0, flags=noimmutable + # rm /mnt/f2fs/vdc.file + # df -h + /dev/vdb 64G 753M 64G 2% /mnt/f2fs So, the key idea is, user can do any file operations on /dev/vdc, and reclaim the space after the use, while the space is counted as /data. diff --git a/Documentation/filesystems/fuse-io-uring.rst b/Documentation/filesystems/fuse/fuse-io-uring.rst index d73dd0dbd238..d73dd0dbd238 100644 --- a/Documentation/filesystems/fuse-io-uring.rst +++ b/Documentation/filesystems/fuse/fuse-io-uring.rst diff --git a/Documentation/filesystems/fuse-io.rst b/Documentation/filesystems/fuse/fuse-io.rst index 6464de4266ad..d736ac4cb483 100644 --- a/Documentation/filesystems/fuse-io.rst +++ b/Documentation/filesystems/fuse/fuse-io.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 ============== -Fuse I/O Modes +FUSE I/O Modes ============== Fuse supports the following I/O modes: diff --git a/Documentation/filesystems/fuse-passthrough.rst b/Documentation/filesystems/fuse/fuse-passthrough.rst index 2b0e7c2da54a..2b0e7c2da54a 100644 --- a/Documentation/filesystems/fuse-passthrough.rst +++ b/Documentation/filesystems/fuse/fuse-passthrough.rst diff --git a/Documentation/filesystems/fuse.rst b/Documentation/filesystems/fuse/fuse.rst index 1e31e87aee68..0fbd5a03fdc9 100644 --- a/Documentation/filesystems/fuse.rst +++ b/Documentation/filesystems/fuse/fuse.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -==== -FUSE -==== +============= +FUSE Overview +============= Definitions =========== @@ -129,6 +129,20 @@ For each connection the following files exist within this directory: connection. This means that all waiting requests will be aborted an error returned for all aborted and new requests. + max_background + The maximum number of background requests that can be outstanding + at a time. When the number of background requests reaches this limit, + further requests will be blocked until some are completed, potentially + causing I/O operations to stall. + + congestion_threshold + The threshold of background requests at which the kernel considers + the filesystem to be congested. When the number of background requests + exceeds this value, the kernel will skip asynchronous readahead + operations, reducing read-ahead optimizations but preserving essential + I/O, as well as suspending non-synchronous writeback operations + (WB_SYNC_NONE), delaying page cache flushing to the filesystem. + Only the owner of the mount may read or write these files. Interrupting filesystem operations diff --git a/Documentation/filesystems/fuse/index.rst b/Documentation/filesystems/fuse/index.rst new file mode 100644 index 000000000000..393a845214da --- /dev/null +++ b/Documentation/filesystems/fuse/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================================== +FUSE (Filesystem in Userspace) Technical Documentation +====================================================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + fuse + fuse-io + fuse-io-uring + fuse-passthrough diff --git a/Documentation/filesystems/gfs2-glocks.rst b/Documentation/filesystems/gfs2-glocks.rst index adc0d4c4d979..ce5ff08cbd59 100644 --- a/Documentation/filesystems/gfs2-glocks.rst +++ b/Documentation/filesystems/gfs2-glocks.rst @@ -105,7 +105,7 @@ go_unlocked Yes No Operations must not drop either the bit lock or the spinlock if its held on entry. go_dump and do_demote_ok must never block. Note that go_dump will only be called if the glock's state - indicates that it is caching uptodate data. + indicates that it is caching up-to-date data. Glock locking order within GFS2: diff --git a/Documentation/filesystems/hpfs.rst b/Documentation/filesystems/hpfs.rst index 7e0dd2f4373e..0f9516b5eb07 100644 --- a/Documentation/filesystems/hpfs.rst +++ b/Documentation/filesystems/hpfs.rst @@ -65,7 +65,7 @@ are case sensitive, so for example when you create a file FOO, you can use 'cat FOO', 'cat Foo', 'cat foo' or 'cat F*' but not 'cat f*'. Note, that you also won't be able to compile linux kernel (and maybe other things) on HPFS because kernel creates different files with names like bootsect.S and -bootsect.s. When searching for file thats name has characters >= 128, codepages +bootsect.s. When searching for file whose name has characters >= 128, codepages are used - see below. OS/2 ignores dots and spaces at the end of file name, so this driver does as well. If you create 'a. ...', the file 'a' will be created, but you can still diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 622187a96bdc..af516e528ded 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -95,10 +95,7 @@ Documentation for filesystem implementations. hfs hfsplus hpfs - fuse - fuse-io - fuse-io-uring - fuse-passthrough + fuse/index inotify isofs nilfs2 diff --git a/Documentation/filesystems/iomap/operations.rst b/Documentation/filesystems/iomap/operations.rst index 067ed8e14ef3..387fd9cc72ca 100644 --- a/Documentation/filesystems/iomap/operations.rst +++ b/Documentation/filesystems/iomap/operations.rst @@ -321,7 +321,7 @@ The fields are as follows: - ``writeback_submit``: Submit the previous built writeback context. Block based file systems should use the iomap_ioend_writeback_submit helper, other file system can implement their own. - File systems can optionall to hook into writeback bio submission. + File systems can optionally hook into writeback bio submission. This might include pre-write space accounting updates, or installing a custom ``->bi_end_io`` function for internal purposes, such as deferring the ioend completion to a workqueue to run metadata update diff --git a/Documentation/filesystems/ocfs2-online-filecheck.rst b/Documentation/filesystems/ocfs2-online-filecheck.rst index 2257bb53edc1..9e8449416e0b 100644 --- a/Documentation/filesystems/ocfs2-online-filecheck.rst +++ b/Documentation/filesystems/ocfs2-online-filecheck.rst @@ -58,33 +58,33 @@ inode, fixing inode and setting the size of result record history. # echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/check # cat /sys/fs/ocfs2/<devname>/filecheck/check -The output is like this:: + The output is like this:: INO DONE ERROR 39502 1 GENERATION - <INO> lists the inode numbers. - <DONE> indicates whether the operation has been finished. - <ERROR> says what kind of errors was found. For the detailed error numbers, - please refer to the file linux/fs/ocfs2/filecheck.h. + <INO> lists the inode numbers. + <DONE> indicates whether the operation has been finished. + <ERROR> says what kind of errors was found. For the detailed error numbers, + please refer to the file linux/fs/ocfs2/filecheck.h. 2. If you determine to fix this inode, do:: # echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/fix # cat /sys/fs/ocfs2/<devname>/filecheck/fix -The output is like this::: + The output is like this:: INO DONE ERROR 39502 1 SUCCESS -This time, the <ERROR> column indicates whether this fix is successful or not. + This time, the <ERROR> column indicates whether this fix is successful or not. 3. The record cache is used to store the history of check/fix results. It's -default size is 10, and can be adjust between the range of 10 ~ 100. You can -adjust the size like this:: + default size is 10, and can be adjust between the range of 10 ~ 100. You can + adjust the size like this:: - # echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set + # echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set Fixing stuff ============ diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 42f2fb9e3c8f..0b86a8022fa1 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -61,19 +61,6 @@ Preface 0.1 Introduction/Credits ------------------------ -This documentation is part of a soon (or so we hope) to be released book on -the SuSE Linux distribution. As there is no complete documentation for the -/proc file system and we've used many freely available sources to write these -chapters, it seems only fair to give the work back to the Linux community. -This work is based on the 2.2.* kernel version and the upcoming 2.4.*. I'm -afraid it's still far from complete, but we hope it will be useful. As far as -we know, it is the first 'all-in-one' document about the /proc file system. It -is focused on the Intel x86 hardware, so if you are looking for PPC, ARM, -SPARC, AXP, etc., features, you probably won't find what you are looking for. -It also only covers IPv4 networking, not IPv6 nor other protocols - sorry. But -additions and patches are welcome and will be added to this document if you -mail them to Bodo. - We'd like to thank Alan Cox, Rik van Riel, and Alexey Kuznetsov and a lot of other people for help compiling this documentation. We'd also like to extend a special thank you to Andi Kleen for documentation, which we relied on heavily @@ -81,17 +68,9 @@ to create this document, as well as the additional information he provided. Thanks to everybody else who contributed source or docs to the Linux kernel and helped create a great piece of software... :) -If you have any comments, corrections or additions, please don't hesitate to -contact Bodo Bauer at bb@ricochet.net. We'll be happy to add them to this -document. - The latest version of this document is available online at https://www.kernel.org/doc/html/latest/filesystems/proc.html -If the above direction does not works for you, you could try the kernel -mailing list at linux-kernel@vger.kernel.org and/or try to reach me at -comandante@zaralinux.com. - 0.2 Legal Stuff --------------- @@ -2180,6 +2159,20 @@ DMA Buffer files where 'size' is the size of the DMA buffer in bytes. 'count' is the file count of the DMA buffer file. 'exp_name' is the name of the DMA buffer exporter. +VFIO Device files +~~~~~~~~~~~~~~~~~ + +:: + + pos: 0 + flags: 02000002 + mnt_id: 17 + ino: 5122 + vfio-device-syspath: /sys/devices/pci0000:e0/0000:e0:01.1/0000:e1:00.0/0000:e2:05.0/0000:e8:00.0 + +where 'vfio-device-syspath' is the sysfs path corresponding to the VFIO device +file. + 3.9 /proc/<pid>/map_files - Information about memory mapped files --------------------------------------------------------------------- This directory contains symbolic links which represent memory mapped files diff --git a/Documentation/filesystems/propagate_umount.txt b/Documentation/filesystems/propagate_umount.txt index c90349e5b889..9a7eb96df300 100644 --- a/Documentation/filesystems/propagate_umount.txt +++ b/Documentation/filesystems/propagate_umount.txt @@ -286,7 +286,7 @@ Trim_one(m) strip the "seen by Trim_ancestors" mark from m remove m from the Candidates list return - + remove_this = false found = false for each n in children(m) @@ -312,7 +312,7 @@ Trim_ancestors(m) } Terminating condition in the loop in Trim_ancestors() is correct, -since that that loop will never run into p belonging to U - p is always +since that loop will never run into p belonging to U - p is always an ancestor of argument of Trim_one() and since U is closed, the argument of Trim_one() would also have to belong to U. But Trim_one() is never called for elements of U. In other words, p belongs to S if and only @@ -361,7 +361,7 @@ such removals. Proof: suppose S was non-shifting, x is a locked element of S, parent of x is not in S and S - {x} is not non-shifting. Then there is an element m in S - {x} and a subtree mounted strictly inside m, such that m contains -an element not in in S - {x}. Since S is non-shifting, everything in +an element not in S - {x}. Since S is non-shifting, everything in that subtree must belong to S. But that means that this subtree must contain x somewhere *and* that parent of x either belongs that subtree or is equal to m. Either way it must belong to S. Contradiction. diff --git a/Documentation/filesystems/resctrl.rst b/Documentation/filesystems/resctrl.rst index 006d23af66e1..b7f35b07876a 100644 --- a/Documentation/filesystems/resctrl.rst +++ b/Documentation/filesystems/resctrl.rst @@ -769,7 +769,7 @@ this would be dependent on number of cores the benchmark is run on. depending on # of threads: For the same SKU in #1, a 'single thread, with 10% bandwidth' and '4 -thread, with 10% bandwidth' can consume upto 10GBps and 40GBps although +thread, with 10% bandwidth' can consume up to 10GBps and 40GBps although they have same percentage bandwidth of 10%. This is simply because as threads start using more cores in an rdtgroup, the actual bandwidth may increase or vary although user specified bandwidth percentage is same. diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst index 1cf56489ed48..8b7dc9159083 100644 --- a/Documentation/filesystems/sharedsubtree.rst +++ b/Documentation/filesystems/sharedsubtree.rst @@ -31,965 +31,960 @@ and versioned filesystem. ----------- Shared subtree provides four different flavors of mounts; struct vfsmount to be -precise +precise: - a. shared mount - b. slave mount - c. private mount - d. unbindable mount +a) A **shared mount** can be replicated to as many mountpoints and all the + replicas continue to be exactly same. -2a) A shared mount can be replicated to as many mountpoints and all the -replicas continue to be exactly same. + Here is an example: - Here is an example: + Let's say /mnt has a mount that is shared:: - Let's say /mnt has a mount that is shared:: + # mount --make-shared /mnt - mount --make-shared /mnt + .. note:: + mount(8) command now supports the --make-shared flag, + so the sample 'smount' program is no longer needed and has been + removed. - Note: mount(8) command now supports the --make-shared flag, - so the sample 'smount' program is no longer needed and has been - removed. + :: - :: + # mount --bind /mnt /tmp - # mount --bind /mnt /tmp + The above command replicates the mount at /mnt to the mountpoint /tmp + and the contents of both the mounts remain identical. - The above command replicates the mount at /mnt to the mountpoint /tmp - and the contents of both the mounts remain identical. + :: - :: + #ls /mnt + a b c - #ls /mnt - a b c + #ls /tmp + a b c - #ls /tmp - a b c + Now let's say we mount a device at /tmp/a:: - Now let's say we mount a device at /tmp/a:: + # mount /dev/sd0 /tmp/a - # mount /dev/sd0 /tmp/a + # ls /tmp/a + t1 t2 t3 - #ls /tmp/a - t1 t2 t3 + # ls /mnt/a + t1 t2 t3 - #ls /mnt/a - t1 t2 t3 + Note that the mount has propagated to the mount at /mnt as well. - Note that the mount has propagated to the mount at /mnt as well. + And the same is true even when /dev/sd0 is mounted on /mnt/a. The + contents will be visible under /tmp/a too. - And the same is true even when /dev/sd0 is mounted on /mnt/a. The - contents will be visible under /tmp/a too. +b) A **slave mount** is like a shared mount except that mount and umount events + only propagate towards it. -2b) A slave mount is like a shared mount except that mount and umount events - only propagate towards it. + All slave mounts have a master mount which is a shared. - All slave mounts have a master mount which is a shared. + Here is an example: - Here is an example: + Let's say /mnt has a mount which is shared:: - Let's say /mnt has a mount which is shared. - # mount --make-shared /mnt + # mount --make-shared /mnt - Let's bind mount /mnt to /tmp - # mount --bind /mnt /tmp + Let's bind mount /mnt to /tmp:: - the new mount at /tmp becomes a shared mount and it is a replica of - the mount at /mnt. + # mount --bind /mnt /tmp - Now let's make the mount at /tmp; a slave of /mnt - # mount --make-slave /tmp + the new mount at /tmp becomes a shared mount and it is a replica of + the mount at /mnt. - let's mount /dev/sd0 on /mnt/a - # mount /dev/sd0 /mnt/a + Now let's make the mount at /tmp; a slave of /mnt:: - #ls /mnt/a - t1 t2 t3 + # mount --make-slave /tmp - #ls /tmp/a - t1 t2 t3 + let's mount /dev/sd0 on /mnt/a:: - Note the mount event has propagated to the mount at /tmp + # mount /dev/sd0 /mnt/a - However let's see what happens if we mount something on the mount at /tmp + # ls /mnt/a + t1 t2 t3 - # mount /dev/sd1 /tmp/b + # ls /tmp/a + t1 t2 t3 - #ls /tmp/b - s1 s2 s3 + Note the mount event has propagated to the mount at /tmp - #ls /mnt/b + However let's see what happens if we mount something on the mount at + /tmp:: - Note how the mount event has not propagated to the mount at - /mnt + # mount /dev/sd1 /tmp/b + # ls /tmp/b + s1 s2 s3 -2c) A private mount does not forward or receive propagation. + # ls /mnt/b - This is the mount we are familiar with. Its the default type. + Note how the mount event has not propagated to the mount at + /mnt -2d) A unbindable mount is a unbindable private mount +c) A **private mount** does not forward or receive propagation. - let's say we have a mount at /mnt and we make it unbindable:: + This is the mount we are familiar with. Its the default type. - # mount --make-unbindable /mnt - Let's try to bind mount this mount somewhere else:: +d) An **unbindable mount** is, as the name suggests, an unbindable private + mount. - # mount --bind /mnt /tmp - mount: wrong fs type, bad option, bad superblock on /mnt, - or too many mounted file systems + let's say we have a mount at /mnt and we make it unbindable:: - Binding a unbindable mount is a invalid operation. + # mount --make-unbindable /mnt + + Let's try to bind mount this mount somewhere else:: + + # mount --bind /mnt /tmp mount: wrong fs type, bad option, bad + superblock on /mnt, or too many mounted file systems + + Binding a unbindable mount is a invalid operation. 3) Setting mount states ----------------------- - The mount command (util-linux package) can be used to set mount - states:: +The mount command (util-linux package) can be used to set mount +states:: - mount --make-shared mountpoint - mount --make-slave mountpoint - mount --make-private mountpoint - mount --make-unbindable mountpoint + mount --make-shared mountpoint + mount --make-slave mountpoint + mount --make-private mountpoint + mount --make-unbindable mountpoint 4) Use cases ------------ - A) A process wants to clone its own namespace, but still wants to - access the CD that got mounted recently. +A) A process wants to clone its own namespace, but still wants to + access the CD that got mounted recently. - Solution: + Solution: - The system administrator can make the mount at /cdrom shared:: + The system administrator can make the mount at /cdrom shared:: - mount --bind /cdrom /cdrom - mount --make-shared /cdrom + mount --bind /cdrom /cdrom + mount --make-shared /cdrom - Now any process that clones off a new namespace will have a - mount at /cdrom which is a replica of the same mount in the - parent namespace. + Now any process that clones off a new namespace will have a + mount at /cdrom which is a replica of the same mount in the + parent namespace. - So when a CD is inserted and mounted at /cdrom that mount gets - propagated to the other mount at /cdrom in all the other clone - namespaces. + So when a CD is inserted and mounted at /cdrom that mount gets + propagated to the other mount at /cdrom in all the other clone + namespaces. - B) A process wants its mounts invisible to any other process, but - still be able to see the other system mounts. +B) A process wants its mounts invisible to any other process, but + still be able to see the other system mounts. - Solution: + Solution: - To begin with, the administrator can mark the entire mount tree - as shareable:: + To begin with, the administrator can mark the entire mount tree + as shareable:: - mount --make-rshared / + mount --make-rshared / - A new process can clone off a new namespace. And mark some part - of its namespace as slave:: + A new process can clone off a new namespace. And mark some part + of its namespace as slave:: - mount --make-rslave /myprivatetree + mount --make-rslave /myprivatetree - Hence forth any mounts within the /myprivatetree done by the - process will not show up in any other namespace. However mounts - done in the parent namespace under /myprivatetree still shows - up in the process's namespace. + Hence forth any mounts within the /myprivatetree done by the + process will not show up in any other namespace. However mounts + done in the parent namespace under /myprivatetree still shows + up in the process's namespace. - Apart from the above semantics this feature provides the - building blocks to solve the following problems: +Apart from the above semantics this feature provides the +building blocks to solve the following problems: - C) Per-user namespace +C) Per-user namespace - The above semantics allows a way to share mounts across - namespaces. But namespaces are associated with processes. If - namespaces are made first class objects with user API to - associate/disassociate a namespace with userid, then each user - could have his/her own namespace and tailor it to his/her - requirements. This needs to be supported in PAM. + The above semantics allows a way to share mounts across + namespaces. But namespaces are associated with processes. If + namespaces are made first class objects with user API to + associate/disassociate a namespace with userid, then each user + could have his/her own namespace and tailor it to his/her + requirements. This needs to be supported in PAM. - D) Versioned files +D) Versioned files - If the entire mount tree is visible at multiple locations, then - an underlying versioning file system can return different - versions of the file depending on the path used to access that - file. + If the entire mount tree is visible at multiple locations, then + an underlying versioning file system can return different + versions of the file depending on the path used to access that + file. - An example is:: + An example is:: - mount --make-shared / - mount --rbind / /view/v1 - mount --rbind / /view/v2 - mount --rbind / /view/v3 - mount --rbind / /view/v4 + mount --make-shared / + mount --rbind / /view/v1 + mount --rbind / /view/v2 + mount --rbind / /view/v3 + mount --rbind / /view/v4 - and if /usr has a versioning filesystem mounted, then that - mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and - /view/v4/usr too + and if /usr has a versioning filesystem mounted, then that + mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and + /view/v4/usr too - A user can request v3 version of the file /usr/fs/namespace.c - by accessing /view/v3/usr/fs/namespace.c . The underlying - versioning filesystem can then decipher that v3 version of the - filesystem is being requested and return the corresponding - inode. + A user can request v3 version of the file /usr/fs/namespace.c + by accessing /view/v3/usr/fs/namespace.c . The underlying + versioning filesystem can then decipher that v3 version of the + filesystem is being requested and return the corresponding + inode. 5) Detailed semantics --------------------- - The section below explains the detailed semantics of - bind, rbind, move, mount, umount and clone-namespace operations. - - Note: the word 'vfsmount' and the noun 'mount' have been used - to mean the same thing, throughout this document. +The section below explains the detailed semantics of +bind, rbind, move, mount, umount and clone-namespace operations. -5a) Mount states +.. Note:: + the word 'vfsmount' and the noun 'mount' have been used + to mean the same thing, throughout this document. - A given mount can be in one of the following states +a) Mount states - 1) shared - 2) slave - 3) shared and slave - 4) private - 5) unbindable + A **propagation event** is defined as event generated on a vfsmount + that leads to mount or unmount actions in other vfsmounts. - A 'propagation event' is defined as event generated on a vfsmount - that leads to mount or unmount actions in other vfsmounts. + A **peer group** is defined as a group of vfsmounts that propagate + events to each other. - A 'peer group' is defined as a group of vfsmounts that propagate - events to each other. + A given mount can be in one of the following states: - (1) Shared mounts + (1) Shared mounts - A 'shared mount' is defined as a vfsmount that belongs to a - 'peer group'. + A **shared mount** is defined as a vfsmount that belongs to a + peer group. - For example:: + For example:: - mount --make-shared /mnt - mount --bind /mnt /tmp + mount --make-shared /mnt + mount --bind /mnt /tmp - The mount at /mnt and that at /tmp are both shared and belong - to the same peer group. Anything mounted or unmounted under - /mnt or /tmp reflect in all the other mounts of its peer - group. + The mount at /mnt and that at /tmp are both shared and belong + to the same peer group. Anything mounted or unmounted under + /mnt or /tmp reflect in all the other mounts of its peer + group. - (2) Slave mounts + (2) Slave mounts - A 'slave mount' is defined as a vfsmount that receives - propagation events and does not forward propagation events. + A **slave mount** is defined as a vfsmount that receives + propagation events and does not forward propagation events. - A slave mount as the name implies has a master mount from which - mount/unmount events are received. Events do not propagate from - the slave mount to the master. Only a shared mount can be made - a slave by executing the following command:: + A slave mount as the name implies has a master mount from which + mount/unmount events are received. Events do not propagate from + the slave mount to the master. Only a shared mount can be made + a slave by executing the following command:: - mount --make-slave mount + mount --make-slave mount - A shared mount that is made as a slave is no more shared unless - modified to become shared. + A shared mount that is made as a slave is no more shared unless + modified to become shared. - (3) Shared and Slave + (3) Shared and Slave - A vfsmount can be both shared as well as slave. This state - indicates that the mount is a slave of some vfsmount, and - has its own peer group too. This vfsmount receives propagation - events from its master vfsmount, and also forwards propagation - events to its 'peer group' and to its slave vfsmounts. + A vfsmount can be both **shared** as well as **slave**. This state + indicates that the mount is a slave of some vfsmount, and + has its own peer group too. This vfsmount receives propagation + events from its master vfsmount, and also forwards propagation + events to its 'peer group' and to its slave vfsmounts. - Strictly speaking, the vfsmount is shared having its own - peer group, and this peer-group is a slave of some other - peer group. + Strictly speaking, the vfsmount is shared having its own + peer group, and this peer-group is a slave of some other + peer group. - Only a slave vfsmount can be made as 'shared and slave' by - either executing the following command:: + Only a slave vfsmount can be made as 'shared and slave' by + either executing the following command:: - mount --make-shared mount + mount --make-shared mount - or by moving the slave vfsmount under a shared vfsmount. + or by moving the slave vfsmount under a shared vfsmount. - (4) Private mount + (4) Private mount - A 'private mount' is defined as vfsmount that does not - receive or forward any propagation events. + A **private mount** is defined as vfsmount that does not + receive or forward any propagation events. - (5) Unbindable mount + (5) Unbindable mount - A 'unbindable mount' is defined as vfsmount that does not - receive or forward any propagation events and cannot - be bind mounted. + A **unbindable mount** is defined as vfsmount that does not + receive or forward any propagation events and cannot + be bind mounted. - State diagram: + State diagram: - The state diagram below explains the state transition of a mount, - in response to various commands:: + The state diagram below explains the state transition of a mount, + in response to various commands:: - ----------------------------------------------------------------------- - | |make-shared | make-slave | make-private |make-unbindab| - --------------|------------|--------------|--------------|-------------| - |shared |shared |*slave/private| private | unbindable | - | | | | | | - |-------------|------------|--------------|--------------|-------------| - |slave |shared | **slave | private | unbindable | - | |and slave | | | | - |-------------|------------|--------------|--------------|-------------| - |shared |shared | slave | private | unbindable | - |and slave |and slave | | | | - |-------------|------------|--------------|--------------|-------------| - |private |shared | **private | private | unbindable | - |-------------|------------|--------------|--------------|-------------| - |unbindable |shared |**unbindable | private | unbindable | - ------------------------------------------------------------------------ + ----------------------------------------------------------------------- + | |make-shared | make-slave | make-private |make-unbindab| + --------------|------------|--------------|--------------|-------------| + |shared |shared |*slave/private| private | unbindable | + | | | | | | + |-------------|------------|--------------|--------------|-------------| + |slave |shared | **slave | private | unbindable | + | |and slave | | | | + |-------------|------------|--------------|--------------|-------------| + |shared |shared | slave | private | unbindable | + |and slave |and slave | | | | + |-------------|------------|--------------|--------------|-------------| + |private |shared | **private | private | unbindable | + |-------------|------------|--------------|--------------|-------------| + |unbindable |shared |**unbindable | private | unbindable | + ------------------------------------------------------------------------ - * if the shared mount is the only mount in its peer group, making it - slave, makes it private automatically. Note that there is no master to - which it can be slaved to. + * if the shared mount is the only mount in its peer group, making it + slave, makes it private automatically. Note that there is no master to + which it can be slaved to. - ** slaving a non-shared mount has no effect on the mount. + ** slaving a non-shared mount has no effect on the mount. - Apart from the commands listed below, the 'move' operation also changes - the state of a mount depending on type of the destination mount. Its - explained in section 5d. + Apart from the commands listed below, the 'move' operation also changes + the state of a mount depending on type of the destination mount. Its + explained in section 5d. -5b) Bind semantics +b) Bind semantics - Consider the following command:: + Consider the following command:: - mount --bind A/a B/b + mount --bind A/a B/b - where 'A' is the source mount, 'a' is the dentry in the mount 'A', 'B' - is the destination mount and 'b' is the dentry in the destination mount. + where 'A' is the source mount, 'a' is the dentry in the mount 'A', 'B' + is the destination mount and 'b' is the dentry in the destination mount. - The outcome depends on the type of mount of 'A' and 'B'. The table - below contains quick reference:: + The outcome depends on the type of mount of 'A' and 'B'. The table + below contains quick reference:: - -------------------------------------------------------------------------- - | BIND MOUNT OPERATION | - |************************************************************************| - |source(A)->| shared | private | slave | unbindable | - | dest(B) | | | | | - | | | | | | | - | v | | | | | - |************************************************************************| - | shared | shared | shared | shared & slave | invalid | - | | | | | | - |non-shared| shared | private | slave | invalid | - ************************************************************************** + -------------------------------------------------------------------------- + | BIND MOUNT OPERATION | + |************************************************************************| + |source(A)->| shared | private | slave | unbindable | + | dest(B) | | | | | + | | | | | | | + | v | | | | | + |************************************************************************| + | shared | shared | shared | shared & slave | invalid | + | | | | | | + |non-shared| shared | private | slave | invalid | + ************************************************************************** - Details: + Details: - 1. 'A' is a shared mount and 'B' is a shared mount. A new mount 'C' - which is clone of 'A', is created. Its root dentry is 'a' . 'C' is - mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... - are created and mounted at the dentry 'b' on all mounts where 'B' - propagates to. A new propagation tree containing 'C1',..,'Cn' is - created. This propagation tree is identical to the propagation tree of - 'B'. And finally the peer-group of 'C' is merged with the peer group - of 'A'. + 1. 'A' is a shared mount and 'B' is a shared mount. A new mount 'C' + which is clone of 'A', is created. Its root dentry is 'a' . 'C' is + mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... + are created and mounted at the dentry 'b' on all mounts where 'B' + propagates to. A new propagation tree containing 'C1',..,'Cn' is + created. This propagation tree is identical to the propagation tree of + 'B'. And finally the peer-group of 'C' is merged with the peer group + of 'A'. - 2. 'A' is a private mount and 'B' is a shared mount. A new mount 'C' - which is clone of 'A', is created. Its root dentry is 'a'. 'C' is - mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... - are created and mounted at the dentry 'b' on all mounts where 'B' - propagates to. A new propagation tree is set containing all new mounts - 'C', 'C1', .., 'Cn' with exactly the same configuration as the - propagation tree for 'B'. + 2. 'A' is a private mount and 'B' is a shared mount. A new mount 'C' + which is clone of 'A', is created. Its root dentry is 'a'. 'C' is + mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... + are created and mounted at the dentry 'b' on all mounts where 'B' + propagates to. A new propagation tree is set containing all new mounts + 'C', 'C1', .., 'Cn' with exactly the same configuration as the + propagation tree for 'B'. - 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. A new - mount 'C' which is clone of 'A', is created. Its root dentry is 'a' . - 'C' is mounted on mount 'B' at dentry 'b'. Also new mounts 'C1', 'C2', - 'C3' ... are created and mounted at the dentry 'b' on all mounts where - 'B' propagates to. A new propagation tree containing the new mounts - 'C','C1',.. 'Cn' is created. This propagation tree is identical to the - propagation tree for 'B'. And finally the mount 'C' and its peer group - is made the slave of mount 'Z'. In other words, mount 'C' is in the - state 'slave and shared'. - - 4. 'A' is a unbindable mount and 'B' is a shared mount. This is a - invalid operation. - - 5. 'A' is a private mount and 'B' is a non-shared(private or slave or - unbindable) mount. A new mount 'C' which is clone of 'A', is created. - Its root dentry is 'a'. 'C' is mounted on mount 'B' at dentry 'b'. - - 6. 'A' is a shared mount and 'B' is a non-shared mount. A new mount 'C' - which is a clone of 'A' is created. Its root dentry is 'a'. 'C' is - mounted on mount 'B' at dentry 'b'. 'C' is made a member of the - peer-group of 'A'. - - 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. A - new mount 'C' which is a clone of 'A' is created. Its root dentry is - 'a'. 'C' is mounted on mount 'B' at dentry 'b'. Also 'C' is set as a - slave mount of 'Z'. In other words 'A' and 'C' are both slave mounts of - 'Z'. All mount/unmount events on 'Z' propagates to 'A' and 'C'. But - mount/unmount on 'A' do not propagate anywhere else. Similarly - mount/unmount on 'C' do not propagate anywhere else. - - 8. 'A' is a unbindable mount and 'B' is a non-shared mount. This is a - invalid operation. A unbindable mount cannot be bind mounted. - -5c) Rbind semantics - - rbind is same as bind. Bind replicates the specified mount. Rbind - replicates all the mounts in the tree belonging to the specified mount. - Rbind mount is bind mount applied to all the mounts in the tree. - - If the source tree that is rbind has some unbindable mounts, - then the subtree under the unbindable mount is pruned in the new - location. - - eg: - - let's say we have the following mount tree:: - - A - / \ - B C - / \ / \ - D E F G - - Let's say all the mount except the mount C in the tree are - of a type other than unbindable. - - If this tree is rbound to say Z - - We will have the following tree at the new location:: - - Z - | - A' - / - B' Note how the tree under C is pruned - / \ in the new location. - D' E' - - - -5d) Move semantics - - Consider the following command - - mount --move A B/b + 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. A new + mount 'C' which is clone of 'A', is created. Its root dentry is 'a' . + 'C' is mounted on mount 'B' at dentry 'b'. Also new mounts 'C1', 'C2', + 'C3' ... are created and mounted at the dentry 'b' on all mounts where + 'B' propagates to. A new propagation tree containing the new mounts + 'C','C1',.. 'Cn' is created. This propagation tree is identical to the + propagation tree for 'B'. And finally the mount 'C' and its peer group + is made the slave of mount 'Z'. In other words, mount 'C' is in the + state 'slave and shared'. + + 4. 'A' is a unbindable mount and 'B' is a shared mount. This is a + invalid operation. + + 5. 'A' is a private mount and 'B' is a non-shared(private or slave or + unbindable) mount. A new mount 'C' which is clone of 'A', is created. + Its root dentry is 'a'. 'C' is mounted on mount 'B' at dentry 'b'. + + 6. 'A' is a shared mount and 'B' is a non-shared mount. A new mount 'C' + which is a clone of 'A' is created. Its root dentry is 'a'. 'C' is + mounted on mount 'B' at dentry 'b'. 'C' is made a member of the + peer-group of 'A'. + + 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. A + new mount 'C' which is a clone of 'A' is created. Its root dentry is + 'a'. 'C' is mounted on mount 'B' at dentry 'b'. Also 'C' is set as a + slave mount of 'Z'. In other words 'A' and 'C' are both slave mounts of + 'Z'. All mount/unmount events on 'Z' propagates to 'A' and 'C'. But + mount/unmount on 'A' do not propagate anywhere else. Similarly + mount/unmount on 'C' do not propagate anywhere else. + + 8. 'A' is a unbindable mount and 'B' is a non-shared mount. This is a + invalid operation. A unbindable mount cannot be bind mounted. + +c) Rbind semantics + + rbind is same as bind. Bind replicates the specified mount. Rbind + replicates all the mounts in the tree belonging to the specified mount. + Rbind mount is bind mount applied to all the mounts in the tree. + + If the source tree that is rbind has some unbindable mounts, + then the subtree under the unbindable mount is pruned in the new + location. + + eg: + + let's say we have the following mount tree:: + + A + / \ + B C + / \ / \ + D E F G + + Let's say all the mount except the mount C in the tree are + of a type other than unbindable. + + If this tree is rbound to say Z + + We will have the following tree at the new location:: + + Z + | + A' + / + B' Note how the tree under C is pruned + / \ in the new location. + D' E' + + + +d) Move semantics + + Consider the following command:: + + mount --move A B/b - where 'A' is the source mount, 'B' is the destination mount and 'b' is - the dentry in the destination mount. + where 'A' is the source mount, 'B' is the destination mount and 'b' is + the dentry in the destination mount. - The outcome depends on the type of the mount of 'A' and 'B'. The table - below is a quick reference:: + The outcome depends on the type of the mount of 'A' and 'B'. The table + below is a quick reference:: - --------------------------------------------------------------------------- - | MOVE MOUNT OPERATION | - |************************************************************************** - | source(A)->| shared | private | slave | unbindable | - | dest(B) | | | | | - | | | | | | | - | v | | | | | - |************************************************************************** - | shared | shared | shared |shared and slave| invalid | - | | | | | | - |non-shared| shared | private | slave | unbindable | - *************************************************************************** + --------------------------------------------------------------------------- + | MOVE MOUNT OPERATION | + |************************************************************************** + | source(A)->| shared | private | slave | unbindable | + | dest(B) | | | | | + | | | | | | | + | v | | | | | + |************************************************************************** + | shared | shared | shared |shared and slave| invalid | + | | | | | | + |non-shared| shared | private | slave | unbindable | + *************************************************************************** - .. Note:: moving a mount residing under a shared mount is invalid. + .. Note:: moving a mount residing under a shared mount is invalid. - Details follow: + Details follow: - 1. 'A' is a shared mount and 'B' is a shared mount. The mount 'A' is - mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', 'A2'...'An' - are created and mounted at dentry 'b' on all mounts that receive - propagation from mount 'B'. A new propagation tree is created in the - exact same configuration as that of 'B'. This new propagation tree - contains all the new mounts 'A1', 'A2'... 'An'. And this new - propagation tree is appended to the already existing propagation tree - of 'A'. + 1. 'A' is a shared mount and 'B' is a shared mount. The mount 'A' is + mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', 'A2'...'An' + are created and mounted at dentry 'b' on all mounts that receive + propagation from mount 'B'. A new propagation tree is created in the + exact same configuration as that of 'B'. This new propagation tree + contains all the new mounts 'A1', 'A2'... 'An'. And this new + propagation tree is appended to the already existing propagation tree + of 'A'. - 2. 'A' is a private mount and 'B' is a shared mount. The mount 'A' is - mounted on mount 'B' at dentry 'b'. Also new mount 'A1', 'A2'... 'An' - are created and mounted at dentry 'b' on all mounts that receive - propagation from mount 'B'. The mount 'A' becomes a shared mount and a - propagation tree is created which is identical to that of - 'B'. This new propagation tree contains all the new mounts 'A1', - 'A2'... 'An'. + 2. 'A' is a private mount and 'B' is a shared mount. The mount 'A' is + mounted on mount 'B' at dentry 'b'. Also new mount 'A1', 'A2'... 'An' + are created and mounted at dentry 'b' on all mounts that receive + propagation from mount 'B'. The mount 'A' becomes a shared mount and a + propagation tree is created which is identical to that of + 'B'. This new propagation tree contains all the new mounts 'A1', + 'A2'... 'An'. - 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. The - mount 'A' is mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', - 'A2'... 'An' are created and mounted at dentry 'b' on all mounts that - receive propagation from mount 'B'. A new propagation tree is created - in the exact same configuration as that of 'B'. This new propagation - tree contains all the new mounts 'A1', 'A2'... 'An'. And this new - propagation tree is appended to the already existing propagation tree of - 'A'. Mount 'A' continues to be the slave mount of 'Z' but it also - becomes 'shared'. + 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. The + mount 'A' is mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', + 'A2'... 'An' are created and mounted at dentry 'b' on all mounts that + receive propagation from mount 'B'. A new propagation tree is created + in the exact same configuration as that of 'B'. This new propagation + tree contains all the new mounts 'A1', 'A2'... 'An'. And this new + propagation tree is appended to the already existing propagation tree of + 'A'. Mount 'A' continues to be the slave mount of 'Z' but it also + becomes 'shared'. - 4. 'A' is a unbindable mount and 'B' is a shared mount. The operation - is invalid. Because mounting anything on the shared mount 'B' can - create new mounts that get mounted on the mounts that receive - propagation from 'B'. And since the mount 'A' is unbindable, cloning - it to mount at other mountpoints is not possible. + 4. 'A' is a unbindable mount and 'B' is a shared mount. The operation + is invalid. Because mounting anything on the shared mount 'B' can + create new mounts that get mounted on the mounts that receive + propagation from 'B'. And since the mount 'A' is unbindable, cloning + it to mount at other mountpoints is not possible. - 5. 'A' is a private mount and 'B' is a non-shared(private or slave or - unbindable) mount. The mount 'A' is mounted on mount 'B' at dentry 'b'. + 5. 'A' is a private mount and 'B' is a non-shared(private or slave or + unbindable) mount. The mount 'A' is mounted on mount 'B' at dentry 'b'. - 6. 'A' is a shared mount and 'B' is a non-shared mount. The mount 'A' - is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a - shared mount. + 6. 'A' is a shared mount and 'B' is a non-shared mount. The mount 'A' + is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a + shared mount. - 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. - The mount 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' - continues to be a slave mount of mount 'Z'. + 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. + The mount 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' + continues to be a slave mount of mount 'Z'. - 8. 'A' is a unbindable mount and 'B' is a non-shared mount. The mount - 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a - unbindable mount. + 8. 'A' is a unbindable mount and 'B' is a non-shared mount. The mount + 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a + unbindable mount. -5e) Mount semantics +e) Mount semantics - Consider the following command:: + Consider the following command:: - mount device B/b + mount device B/b - 'B' is the destination mount and 'b' is the dentry in the destination - mount. + 'B' is the destination mount and 'b' is the dentry in the destination + mount. - The above operation is the same as bind operation with the exception - that the source mount is always a private mount. + The above operation is the same as bind operation with the exception + that the source mount is always a private mount. -5f) Unmount semantics +f) Unmount semantics - Consider the following command:: + Consider the following command:: - umount A + umount A - where 'A' is a mount mounted on mount 'B' at dentry 'b'. + where 'A' is a mount mounted on mount 'B' at dentry 'b'. - If mount 'B' is shared, then all most-recently-mounted mounts at dentry - 'b' on mounts that receive propagation from mount 'B' and does not have - sub-mounts within them are unmounted. + If mount 'B' is shared, then all most-recently-mounted mounts at dentry + 'b' on mounts that receive propagation from mount 'B' and does not have + sub-mounts within them are unmounted. - Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to - each other. + Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to + each other. - let's say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount - 'B1', 'B2' and 'B3' respectively. + let's say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount + 'B1', 'B2' and 'B3' respectively. - let's say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on - mount 'B1', 'B2' and 'B3' respectively. + let's say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on + mount 'B1', 'B2' and 'B3' respectively. - if 'C1' is unmounted, all the mounts that are most-recently-mounted on - 'B1' and on the mounts that 'B1' propagates-to are unmounted. + if 'C1' is unmounted, all the mounts that are most-recently-mounted on + 'B1' and on the mounts that 'B1' propagates-to are unmounted. - 'B1' propagates to 'B2' and 'B3'. And the most recently mounted mount - on 'B2' at dentry 'b' is 'C2', and that of mount 'B3' is 'C3'. + 'B1' propagates to 'B2' and 'B3'. And the most recently mounted mount + on 'B2' at dentry 'b' is 'C2', and that of mount 'B3' is 'C3'. - So all 'C1', 'C2' and 'C3' should be unmounted. + So all 'C1', 'C2' and 'C3' should be unmounted. - If any of 'C2' or 'C3' has some child mounts, then that mount is not - unmounted, but all other mounts are unmounted. However if 'C1' is told - to be unmounted and 'C1' has some sub-mounts, the umount operation is - failed entirely. + If any of 'C2' or 'C3' has some child mounts, then that mount is not + unmounted, but all other mounts are unmounted. However if 'C1' is told + to be unmounted and 'C1' has some sub-mounts, the umount operation is + failed entirely. -5g) Clone Namespace +g) Clone Namespace - A cloned namespace contains all the mounts as that of the parent - namespace. + A cloned namespace contains all the mounts as that of the parent + namespace. - Let's say 'A' and 'B' are the corresponding mounts in the parent and the - child namespace. + Let's say 'A' and 'B' are the corresponding mounts in the parent and the + child namespace. - If 'A' is shared, then 'B' is also shared and 'A' and 'B' propagate to - each other. + If 'A' is shared, then 'B' is also shared and 'A' and 'B' propagate to + each other. - If 'A' is a slave mount of 'Z', then 'B' is also the slave mount of - 'Z'. + If 'A' is a slave mount of 'Z', then 'B' is also the slave mount of + 'Z'. - If 'A' is a private mount, then 'B' is a private mount too. + If 'A' is a private mount, then 'B' is a private mount too. - If 'A' is unbindable mount, then 'B' is a unbindable mount too. + If 'A' is unbindable mount, then 'B' is a unbindable mount too. 6) Quiz ------- - A. What is the result of the following command sequence? +A. What is the result of the following command sequence? - :: + :: - mount --bind /mnt /mnt - mount --make-shared /mnt - mount --bind /mnt /tmp - mount --move /tmp /mnt/1 + mount --bind /mnt /mnt + mount --make-shared /mnt + mount --bind /mnt /tmp + mount --move /tmp /mnt/1 - what should be the contents of /mnt /mnt/1 /mnt/1/1 should be? - Should they all be identical? or should /mnt and /mnt/1 be - identical only? + what should be the contents of /mnt /mnt/1 /mnt/1/1 should be? + Should they all be identical? or should /mnt and /mnt/1 be + identical only? - B. What is the result of the following command sequence? +B. What is the result of the following command sequence? - :: + :: - mount --make-rshared / - mkdir -p /v/1 - mount --rbind / /v/1 + mount --make-rshared / + mkdir -p /v/1 + mount --rbind / /v/1 - what should be the content of /v/1/v/1 be? + what should be the content of /v/1/v/1 be? - C. What is the result of the following command sequence? +C. What is the result of the following command sequence? - :: + :: - mount --bind /mnt /mnt - mount --make-shared /mnt - mkdir -p /mnt/1/2/3 /mnt/1/test - mount --bind /mnt/1 /tmp - mount --make-slave /mnt - mount --make-shared /mnt - mount --bind /mnt/1/2 /tmp1 - mount --make-slave /mnt + mount --bind /mnt /mnt + mount --make-shared /mnt + mkdir -p /mnt/1/2/3 /mnt/1/test + mount --bind /mnt/1 /tmp + mount --make-slave /mnt + mount --make-shared /mnt + mount --bind /mnt/1/2 /tmp1 + mount --make-slave /mnt - At this point we have the first mount at /tmp and - its root dentry is 1. Let's call this mount 'A' - And then we have a second mount at /tmp1 with root - dentry 2. Let's call this mount 'B' - Next we have a third mount at /mnt with root dentry - mnt. Let's call this mount 'C' + At this point we have the first mount at /tmp and + its root dentry is 1. Let's call this mount 'A' + And then we have a second mount at /tmp1 with root + dentry 2. Let's call this mount 'B' + Next we have a third mount at /mnt with root dentry + mnt. Let's call this mount 'C' - 'B' is the slave of 'A' and 'C' is a slave of 'B' - A -> B -> C + 'B' is the slave of 'A' and 'C' is a slave of 'B' + A -> B -> C - at this point if we execute the following command + at this point if we execute the following command:: - mount --bind /bin /tmp/test + mount --bind /bin /tmp/test - The mount is attempted on 'A' + The mount is attempted on 'A' - will the mount propagate to 'B' and 'C' ? + will the mount propagate to 'B' and 'C' ? - what would be the contents of - /mnt/1/test be? + what would be the contents of + /mnt/1/test be? 7) FAQ ------ - Q1. Why is bind mount needed? How is it different from symbolic links? - symbolic links can get stale if the destination mount gets - unmounted or moved. Bind mounts continue to exist even if the - other mount is unmounted or moved. +1. Why is bind mount needed? How is it different from symbolic links? - Q2. Why can't the shared subtree be implemented using exportfs? + symbolic links can get stale if the destination mount gets + unmounted or moved. Bind mounts continue to exist even if the + other mount is unmounted or moved. - exportfs is a heavyweight way of accomplishing part of what - shared subtree can do. I cannot imagine a way to implement the - semantics of slave mount using exportfs? +2. Why can't the shared subtree be implemented using exportfs? - Q3 Why is unbindable mount needed? + exportfs is a heavyweight way of accomplishing part of what + shared subtree can do. I cannot imagine a way to implement the + semantics of slave mount using exportfs? - Let's say we want to replicate the mount tree at multiple - locations within the same subtree. +3. Why is unbindable mount needed? - if one rbind mounts a tree within the same subtree 'n' times - the number of mounts created is an exponential function of 'n'. - Having unbindable mount can help prune the unneeded bind - mounts. Here is an example. + Let's say we want to replicate the mount tree at multiple + locations within the same subtree. - step 1: - let's say the root tree has just two directories with - one vfsmount:: + if one rbind mounts a tree within the same subtree 'n' times + the number of mounts created is an exponential function of 'n'. + Having unbindable mount can help prune the unneeded bind + mounts. Here is an example. - root - / \ - tmp usr + step 1: + let's say the root tree has just two directories with + one vfsmount:: - And we want to replicate the tree at multiple - mountpoints under /root/tmp + root + / \ + tmp usr - step 2: - :: + And we want to replicate the tree at multiple + mountpoints under /root/tmp + step 2: + :: - mount --make-shared /root - mkdir -p /tmp/m1 + mount --make-shared /root - mount --rbind /root /tmp/m1 + mkdir -p /tmp/m1 - the new tree now looks like this:: + mount --rbind /root /tmp/m1 - root - / \ - tmp usr - / - m1 - / \ - tmp usr - / - m1 + the new tree now looks like this:: - it has two vfsmounts + root + / \ + tmp usr + / + m1 + / \ + tmp usr + / + m1 - step 3: - :: + it has two vfsmounts - mkdir -p /tmp/m2 - mount --rbind /root /tmp/m2 + step 3: + :: - the new tree now looks like this:: + mkdir -p /tmp/m2 + mount --rbind /root /tmp/m2 - root - / \ - tmp usr - / \ - m1 m2 - / \ / \ - tmp usr tmp usr - / \ / - m1 m2 m1 - / \ / \ - tmp usr tmp usr - / / \ - m1 m1 m2 - / \ - tmp usr - / \ - m1 m2 + the new tree now looks like this:: - it has 6 vfsmounts + root + / \ + tmp usr + / \ + m1 m2 + / \ / \ + tmp usr tmp usr + / \ / + m1 m2 m1 + / \ / \ + tmp usr tmp usr + / / \ + m1 m1 m2 + / \ + tmp usr + / \ + m1 m2 - step 4: - :: - mkdir -p /tmp/m3 - mount --rbind /root /tmp/m3 + it has 6 vfsmounts - I won't draw the tree..but it has 24 vfsmounts + step 4: + :: + mkdir -p /tmp/m3 + mount --rbind /root /tmp/m3 - at step i the number of vfsmounts is V[i] = i*V[i-1]. - This is an exponential function. And this tree has way more - mounts than what we really needed in the first place. + I won't draw the tree..but it has 24 vfsmounts - One could use a series of umount at each step to prune - out the unneeded mounts. But there is a better solution. - Unclonable mounts come in handy here. - step 1: - let's say the root tree has just two directories with - one vfsmount:: + at step i the number of vfsmounts is V[i] = i*V[i-1]. + This is an exponential function. And this tree has way more + mounts than what we really needed in the first place. - root - / \ - tmp usr + One could use a series of umount at each step to prune + out the unneeded mounts. But there is a better solution. + Unclonable mounts come in handy here. - How do we set up the same tree at multiple locations under - /root/tmp + step 1: + let's say the root tree has just two directories with + one vfsmount:: - step 2: - :: + root + / \ + tmp usr + How do we set up the same tree at multiple locations under + /root/tmp - mount --bind /root/tmp /root/tmp + step 2: + :: - mount --make-rshared /root - mount --make-unbindable /root/tmp - mkdir -p /tmp/m1 + mount --bind /root/tmp /root/tmp - mount --rbind /root /tmp/m1 + mount --make-rshared /root + mount --make-unbindable /root/tmp - the new tree now looks like this:: + mkdir -p /tmp/m1 - root - / \ - tmp usr - / - m1 - / \ - tmp usr + mount --rbind /root /tmp/m1 - step 3: - :: + the new tree now looks like this:: - mkdir -p /tmp/m2 - mount --rbind /root /tmp/m2 + root + / \ + tmp usr + / + m1 + / \ + tmp usr - the new tree now looks like this:: + step 3: + :: - root - / \ - tmp usr - / \ - m1 m2 - / \ / \ - tmp usr tmp usr + mkdir -p /tmp/m2 + mount --rbind /root /tmp/m2 - step 4: - :: + the new tree now looks like this:: - mkdir -p /tmp/m3 - mount --rbind /root /tmp/m3 + root + / \ + tmp usr + / \ + m1 m2 + / \ / \ + tmp usr tmp usr - the new tree now looks like this:: + step 4: + :: - root - / \ - tmp usr - / \ \ - m1 m2 m3 - / \ / \ / \ - tmp usr tmp usr tmp usr + mkdir -p /tmp/m3 + mount --rbind /root /tmp/m3 + + the new tree now looks like this:: + + root + / \ + tmp usr + / \ \ + m1 m2 m3 + / \ / \ / \ + tmp usr tmp usr tmp usr 8) Implementation ----------------- -8A) Datastructure +A) Datastructure + + Several new fields are introduced to struct vfsmount: + + ->mnt_share + Links together all the mount to/from which this vfsmount + send/receives propagation events. - 4 new fields are introduced to struct vfsmount: + ->mnt_slave_list + Links all the mounts to which this vfsmount propagates + to. - * ->mnt_share - * ->mnt_slave_list - * ->mnt_slave - * ->mnt_master + ->mnt_slave + Links together all the slaves that its master vfsmount + propagates to. - ->mnt_share - links together all the mount to/from which this vfsmount - send/receives propagation events. + ->mnt_master + Points to the master vfsmount from which this vfsmount + receives propagation. - ->mnt_slave_list - links all the mounts to which this vfsmount propagates - to. + ->mnt_flags + Takes two more flags to indicate the propagation status of + the vfsmount. MNT_SHARE indicates that the vfsmount is a shared + vfsmount. MNT_UNCLONABLE indicates that the vfsmount cannot be + replicated. - ->mnt_slave - links together all the slaves that its master vfsmount - propagates to. + All the shared vfsmounts in a peer group form a cyclic list through + ->mnt_share. - ->mnt_master - points to the master vfsmount from which this vfsmount - receives propagation. + All vfsmounts with the same ->mnt_master form on a cyclic list anchored + in ->mnt_master->mnt_slave_list and going through ->mnt_slave. - ->mnt_flags - takes two more flags to indicate the propagation status of - the vfsmount. MNT_SHARE indicates that the vfsmount is a shared - vfsmount. MNT_UNCLONABLE indicates that the vfsmount cannot be - replicated. + ->mnt_master can point to arbitrary (and possibly different) members + of master peer group. To find all immediate slaves of a peer group + you need to go through _all_ ->mnt_slave_list of its members. + Conceptually it's just a single set - distribution among the + individual lists does not affect propagation or the way propagation + tree is modified by operations. - All the shared vfsmounts in a peer group form a cyclic list through - ->mnt_share. + All vfsmounts in a peer group have the same ->mnt_master. If it is + non-NULL, they form a contiguous (ordered) segment of slave list. - All vfsmounts with the same ->mnt_master form on a cyclic list anchored - in ->mnt_master->mnt_slave_list and going through ->mnt_slave. + A example propagation tree looks as shown in the figure below. - ->mnt_master can point to arbitrary (and possibly different) members - of master peer group. To find all immediate slaves of a peer group - you need to go through _all_ ->mnt_slave_list of its members. - Conceptually it's just a single set - distribution among the - individual lists does not affect propagation or the way propagation - tree is modified by operations. + .. note:: + Though it looks like a forest, if we consider all the shared + mounts as a conceptual entity called 'pnode', it becomes a tree. - All vfsmounts in a peer group have the same ->mnt_master. If it is - non-NULL, they form a contiguous (ordered) segment of slave list. + :: - A example propagation tree looks as shown in the figure below. - [ NOTE: Though it looks like a forest, if we consider all the shared - mounts as a conceptual entity called 'pnode', it becomes a tree]:: + A <--> B <--> C <---> D + /|\ /| |\ + / F G J K H I + / + E<-->K + /|\ + M L N - A <--> B <--> C <---> D - /|\ /| |\ - / F G J K H I - / - E<-->K - /|\ - M L N + In the above figure A,B,C and D all are shared and propagate to each + other. 'A' has got 3 slave mounts 'E' 'F' and 'G' 'C' has got 2 slave + mounts 'J' and 'K' and 'D' has got two slave mounts 'H' and 'I'. + 'E' is also shared with 'K' and they propagate to each other. And + 'K' has 3 slaves 'M', 'L' and 'N' - In the above figure A,B,C and D all are shared and propagate to each - other. 'A' has got 3 slave mounts 'E' 'F' and 'G' 'C' has got 2 slave - mounts 'J' and 'K' and 'D' has got two slave mounts 'H' and 'I'. - 'E' is also shared with 'K' and they propagate to each other. And - 'K' has 3 slaves 'M', 'L' and 'N' + A's ->mnt_share links with the ->mnt_share of 'B' 'C' and 'D' - A's ->mnt_share links with the ->mnt_share of 'B' 'C' and 'D' + A's ->mnt_slave_list links with ->mnt_slave of 'E', 'K', 'F' and 'G' - A's ->mnt_slave_list links with ->mnt_slave of 'E', 'K', 'F' and 'G' + E's ->mnt_share links with ->mnt_share of K - E's ->mnt_share links with ->mnt_share of K + 'E', 'K', 'F', 'G' have their ->mnt_master point to struct vfsmount of 'A' - 'E', 'K', 'F', 'G' have their ->mnt_master point to struct vfsmount of 'A' + 'M', 'L', 'N' have their ->mnt_master point to struct vfsmount of 'K' - 'M', 'L', 'N' have their ->mnt_master point to struct vfsmount of 'K' + K's ->mnt_slave_list links with ->mnt_slave of 'M', 'L' and 'N' - K's ->mnt_slave_list links with ->mnt_slave of 'M', 'L' and 'N' + C's ->mnt_slave_list links with ->mnt_slave of 'J' and 'K' - C's ->mnt_slave_list links with ->mnt_slave of 'J' and 'K' + J and K's ->mnt_master points to struct vfsmount of C - J and K's ->mnt_master points to struct vfsmount of C + and finally D's ->mnt_slave_list links with ->mnt_slave of 'H' and 'I' - and finally D's ->mnt_slave_list links with ->mnt_slave of 'H' and 'I' + 'H' and 'I' have their ->mnt_master pointing to struct vfsmount of 'D'. - 'H' and 'I' have their ->mnt_master pointing to struct vfsmount of 'D'. + NOTE: The propagation tree is orthogonal to the mount tree. - NOTE: The propagation tree is orthogonal to the mount tree. +B) Locking: -8B Locking: + ->mnt_share, ->mnt_slave, ->mnt_slave_list, ->mnt_master are protected + by namespace_sem (exclusive for modifications, shared for reading). - ->mnt_share, ->mnt_slave, ->mnt_slave_list, ->mnt_master are protected - by namespace_sem (exclusive for modifications, shared for reading). + Normally we have ->mnt_flags modifications serialized by vfsmount_lock. + There are two exceptions: do_add_mount() and clone_mnt(). + The former modifies a vfsmount that has not been visible in any shared + data structures yet. + The latter holds namespace_sem and the only references to vfsmount + are in lists that can't be traversed without namespace_sem. - Normally we have ->mnt_flags modifications serialized by vfsmount_lock. - There are two exceptions: do_add_mount() and clone_mnt(). - The former modifies a vfsmount that has not been visible in any shared - data structures yet. - The latter holds namespace_sem and the only references to vfsmount - are in lists that can't be traversed without namespace_sem. +C) Algorithm: -8C Algorithm: + The crux of the implementation resides in rbind/move operation. - The crux of the implementation resides in rbind/move operation. + The overall algorithm breaks the operation into 3 phases: (look at + attach_recursive_mnt() and propagate_mnt()) - The overall algorithm breaks the operation into 3 phases: (look at - attach_recursive_mnt() and propagate_mnt()) + 1. Prepare phase. - 1. prepare phase. - 2. commit phases. - 3. abort phases. + For each mount in the source tree: - Prepare phase: + a) Create the necessary number of mount trees to + be attached to each of the mounts that receive + propagation from the destination mount. + b) Do not attach any of the trees to its destination. + However note down its ->mnt_parent and ->mnt_mountpoint + c) Link all the new mounts to form a propagation tree that + is identical to the propagation tree of the destination + mount. - for each mount in the source tree: + If this phase is successful, there should be 'n' new + propagation trees; where 'n' is the number of mounts in the + source tree. Go to the commit phase - a) Create the necessary number of mount trees to - be attached to each of the mounts that receive - propagation from the destination mount. - b) Do not attach any of the trees to its destination. - However note down its ->mnt_parent and ->mnt_mountpoint - c) Link all the new mounts to form a propagation tree that - is identical to the propagation tree of the destination - mount. + Also there should be 'm' new mount trees, where 'm' is + the number of mounts to which the destination mount + propagates to. - If this phase is successful, there should be 'n' new - propagation trees; where 'n' is the number of mounts in the - source tree. Go to the commit phase + If any memory allocations fail, go to the abort phase. - Also there should be 'm' new mount trees, where 'm' is - the number of mounts to which the destination mount - propagates to. + 2. Commit phase. - if any memory allocations fail, go to the abort phase. + Attach each of the mount trees to their corresponding + destination mounts. - Commit phase - attach each of the mount trees to their corresponding - destination mounts. + 3. Abort phase. - Abort phase - delete all the newly created trees. + Delete all the newly created trees. - .. Note:: - all the propagation related functionality resides in the file pnode.c + .. Note:: + all the propagation related functionality resides in the file pnode.c ------------------------------------------------------------------------ diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst index c32993bc83c7..2703c04af7d0 100644 --- a/Documentation/filesystems/sysfs.rst +++ b/Documentation/filesystems/sysfs.rst @@ -243,8 +243,8 @@ Other notes: - show() methods should return the number of bytes printed into the buffer. -- show() should only use sysfs_emit() or sysfs_emit_at() when formatting - the value to be returned to user space. +- New implementations of show() methods should only use sysfs_emit() or + sysfs_emit_at() when formatting the value to be returned to user space. - store() should return the number of bytes used from the buffer. If the entire buffer has been used, just return the count argument. @@ -299,7 +299,6 @@ The top level sysfs directory looks like:: hypervisor/ kernel/ module/ - net/ power/ devices/ contains a filesystem representation of the device tree. It maps @@ -313,7 +312,7 @@ kernel. Each bus's directory contains two subdirectories:: drivers/ devices/ contains symlinks for each device discovered in the system -that point to the device's directory under root/. +that point to the device's directory under /sys/devices. drivers/ contains a directory for each device driver that is loaded for devices on that particular bus (this assumes that drivers do not @@ -321,22 +320,36 @@ span multiple bus types). fs/ contains a directory for some filesystems. Currently each filesystem wanting to export attributes must create its own hierarchy -below fs/ (see ./fuse.rst for an example). +below fs/ (see fuse/fuse.rst for an example). module/ contains parameter values and state information for all loaded system modules, for both builtin and loadable modules. dev/ contains two directories: char/ and block/. Inside these two directories there are symlinks named <major>:<minor>. These symlinks -point to the sysfs directory for the given device. /sys/dev provides a +point to the directories under /sys/devices for each device. /sys/dev provides a quick way to lookup the sysfs interface for a device from the result of a stat(2) operation. More information on driver-model specific features can be found in Documentation/driver-api/driver-model/. +block/ contains symlinks to all the block devices discovered on the system. +These symlinks point to directories under /sys/devices. -TODO: Finish this section. +class/ contains a directory for each device class, grouped by functional type. +Each directory in class/ contains symlinks to devices in the /sys/devices directory. + +firmware/ contains system firmware data and configuration such as firmware tables, +ACPI information, and device tree data. + +hypervisor/ contains virtualization platform information and provides an interface to +the underlying hypervisor. It is only present when running on a virtual machine. + +kernel/ contains runtime kernel parameters, configuration settings, and status. + +power/ contains power management subsystem information including +sleep states, suspend/resume capabilities, and policies. Current Interfaces diff --git a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst index e231d127cd40..8cbcd3c26434 100644 --- a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst +++ b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst @@ -454,7 +454,7 @@ filesystem so that it can apply pending filesystem updates to the staging information. Once the scan is done, the owning object is re-locked, the live data is used to write a new ondisk structure, and the repairs are committed atomically. -The hooks are disabled and the staging staging area is freed. +The hooks are disabled and the staging area is freed. Finally, the storage from the old data structure are carefully reaped. Introducing concurrency helps online repair avoid various locking problems, but @@ -475,7 +475,7 @@ operation, which may cause application failure or an unplanned filesystem shutdown. Inspiration for the secondary metadata repair strategy was drawn from section -2.4 of Srinivasan above, and sections 2 ("NSF: Inded Build Without Side-File") +2.4 of Srinivasan above, and sections 2 ("NSF: Index Build Without Side-File") and 3.1.1 ("Duplicate Key Insert Problem") in C. Mohan, `"Algorithms for Creating Indexes for Very Large Tables Without Quiescing Updates" <https://dl.acm.org/doi/10.1145/130283.130337>`_, 1992. @@ -2185,7 +2185,7 @@ The chapter about :ref:`secondary metadata<secondary_metadata>` mentioned that checking and repairing of secondary metadata commonly requires coordination between a live metadata scan of the filesystem and writer threads that are updating that metadata. -Keeping the scan data up to date requires requires the ability to propagate +Keeping the scan data up to date requires the ability to propagate metadata updates from the filesystem into the data being collected by the scan. This *can* be done by appending concurrent updates into a separate log file and applying them before writing the new metadata to disk, but this leads to @@ -4179,7 +4179,7 @@ When the exchange is initiated, the sequence of operations is as follows: This will be discussed in more detail in subsequent sections. If the filesystem goes down in the middle of an operation, log recovery will -find the most recent unfinished maping exchange log intent item and restart +find the most recent unfinished mapping exchange log intent item and restart from there. This is how atomic file mapping exchanges guarantees that an outside observer will either see the old broken structure or the new one, and never a mismash of diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index 80c914f6eae7..37b6a5670c2f 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -204,6 +204,27 @@ per-CPU data structures on a non PREEMPT_RT kernel. local_lock is not suitable to protect against preemption or interrupts on a PREEMPT_RT kernel due to the PREEMPT_RT specific spinlock_t semantics. +CPU local scope and bottom-half +------------------------------- + +Per-CPU variables that are accessed only in softirq context should not rely on +the assumption that this context is implicitly protected due to being +non-preemptible. In a PREEMPT_RT kernel, softirq context is preemptible, and +synchronizing every bottom-half-disabled section via implicit context results +in an implicit per-CPU "big kernel lock." + +A local_lock_t together with local_lock_nested_bh() and +local_unlock_nested_bh() for locking operations help to identify the locking +scope. + +When lockdep is enabled, these functions verify that data structure access +occurs within softirq context. +Unlike local_lock(), local_unlock_nested_bh() does not disable preemption and +does not add overhead when used without lockdep. + +On a PREEMPT_RT kernel, local_lock_t behaves as a real lock and +local_unlock_nested_bh() serializes access to the data structure, which allows +removal of serialization via local_bh_disable(). raw_spinlock_t and spinlock_t ============================= diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst index ec6411d02ac8..3fb7ea3ab22a 100644 --- a/Documentation/locking/seqlock.rst +++ b/Documentation/locking/seqlock.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ====================================== Sequence counters and sequential locks ====================================== diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst index 0a36831814ea..0c21f203cf7a 100644 --- a/Documentation/maintainer/configure-git.rst +++ b/Documentation/maintainer/configure-git.rst @@ -28,31 +28,3 @@ You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file):: export GPG_TTY=$(tty) - - -Creating commit links to lore.kernel.org ----------------------------------------- - -The web site https://lore.kernel.org is meant as a grand archive of all mail -list traffic concerning or influencing the kernel development. Storing archives -of patches here is a recommended practice, and when a maintainer applies a -patch to a subsystem tree, it is a good idea to provide a Link: tag with a -reference back to the lore archive so that people that browse the commit -history can find related discussions and rationale behind a certain change. -The link tag will look like this:: - - Link: https://lore.kernel.org/r/<message-id> - -This can be configured to happen automatically any time you issue ``git am`` -by adding the following hook into your git:: - - $ git config am.messageid true - $ cat >.git/hooks/applypatch-msg <<'EOF' - #!/bin/sh - . git-sh-setup - perl -pi -e 's|^Message-I[dD]:\s*<?([^>]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1" - test -x "$GIT_DIR/hooks/commit-msg" && - exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"} - : - EOF - $ chmod a+x .git/hooks/applypatch-msg diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index cda5d691e967..d36dd892a78a 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -59,6 +59,7 @@ week) that patches might be considered for merging and when patches need to wait for the next -rc. At a minimum: - Last -rc for new feature submissions: + New feature submissions targeting the next merge window should have their first posting for consideration before this point. Patches that are submitted after this point should be clear that they are targeting @@ -68,6 +69,7 @@ wait for the next -rc. At a minimum: submissions should appear before -rc5. - Last -rc to merge features: Deadline for merge decisions + Indicate to contributors the point at which an as yet un-applied patch set will need to wait for the NEXT+1 merge window. Of course there is no obligation to ever accept any given patchset, but if the review has not diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst index 9af11b5bd145..b76183545e5b 100644 --- a/Documentation/mm/physical_memory.rst +++ b/Documentation/mm/physical_memory.rst @@ -171,6 +171,8 @@ nodes with particular properties as defined by ``enum node_states``: The node has memory(regular, high, movable) ``N_CPU`` The node has one or more CPUs +``N_GENERIC_INITIATOR`` + The node has one or more Generic Initiators For each node that has a property described above, the bit corresponding to the node ID in the ``node_states[<property>]`` bitmask is set. diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst index 7650c4b5be5f..f93049f03a37 100644 --- a/Documentation/networking/can.rst +++ b/Documentation/networking/can.rst @@ -539,7 +539,7 @@ CAN Filter Usage Optimisation The CAN filters are processed in per-device filter lists at CAN frame reception time. To reduce the number of checks that need to be performed while walking through the filter lists the CAN core provides an optimized -filter handling when the filter subscription focusses on a single CAN ID. +filter handling when the filter subscription focuses on a single CAN ID. For the possible 2048 SFF CAN identifiers the identifier is used as an index to access the corresponding subscription list without any further checks. diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst index 0b0a3eef6aae..7cfcd183054f 100644 --- a/Documentation/networking/device_drivers/ethernet/index.rst +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -50,6 +50,7 @@ Contents: neterion/s2io netronome/nfp pensando/ionic + pensando/ionic_rdma qualcomm/ppe/ppe smsc/smc9 stmicro/stmmac diff --git a/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst b/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst index 05fe2b11bb18..a0029b6db31e 100644 --- a/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst +++ b/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst @@ -13,6 +13,7 @@ Contents - Identifying the Adapter - Enabling the driver - Configuring the driver +- RDMA Support via Auxiliary Device - Statistics - Support @@ -105,6 +106,15 @@ XDP Support for XDP includes the basics, plus Jumbo frames, Redirect and ndo_xmit. There is no current support for zero-copy sockets or HW offload. +RDMA Support via Auxiliary Device +================================= + +The ionic driver supports RDMA (Remote Direct Memory Access) functionality +through the Linux auxiliary device framework when advertised by the firmware. +RDMA capability is detected during device initialization, and if supported, +the ethernet driver will create an auxiliary device that allows the RDMA +driver to bind and provide InfiniBand/RoCE functionality. + Statistics ========== diff --git a/Documentation/networking/device_drivers/ethernet/pensando/ionic_rdma.rst b/Documentation/networking/device_drivers/ethernet/pensando/ionic_rdma.rst new file mode 100644 index 000000000000..42eb461d5f85 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/pensando/ionic_rdma.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +=========================================================== +RDMA Driver for the AMD Pensando(R) Ethernet adapter family +=========================================================== + +AMD Pensando RDMA driver. +Copyright (C) 2018-2025, Advanced Micro Devices, Inc. + +Overview +======== + +The ionic_rdma driver provides Remote Direct Memory Access functionality +for AMD Pensando DSC (Distributed Services Card) devices. This driver +implements RDMA capabilities as an auxiliary driver that operates in +conjunction with the ionic ethernet driver. + +The ionic ethernet driver detects RDMA capability during device +initialization and creates auxiliary devices that the ionic_rdma driver +binds to, establishing the RDMA data path and control interfaces. + +Identifying the Adapter +======================= + +See Documentation/networking/device_drivers/ethernet/pensando/ionic.rst +for more information on identifying the adapter. + +Enabling the driver +=================== + +The ionic_rdma driver depends on the ionic ethernet driver. +See Documentation/networking/device_drivers/ethernet/pensando/ionic.rst +for detailed information on enabling and configuring the ionic driver. + +The ionic_rdma driver is enabled via the standard kernel configuration system, +using the make command:: + + make oldconfig/menuconfig/etc. + +The driver is located in the menu structure at: + + -> Device Drivers + -> InfiniBand support + -> AMD Pensando DSC RDMA/RoCE Support + +Support +======= + +For general Linux RDMA support, please use the RDMA mailing +list, which is monitored by AMD Pensando personnel:: + + linux-rdma@vger.kernel.org diff --git a/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst index 25fd9aa284e2..f0424597aac1 100644 --- a/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst @@ -42,7 +42,7 @@ Port's netdev devices have to be in UP before joining to the bridge to avoid overwriting of bridge configuration as CPSW switch driver completely reloads its configuration when first port changes its state to UP. -When the both interfaces joined the bridge - CPSW switch driver will enable +When both interfaces have joined the bridge - CPSW switch driver will enable marking packets with offload_fwd_mark flag. All configuration is implemented via switchdev API. diff --git a/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst index 464dce938ed1..2f3c43a32bfc 100644 --- a/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst @@ -92,7 +92,7 @@ Port's netdev devices have to be in UP before joining to the bridge to avoid overwriting of bridge configuration as CPSW switch driver copletly reloads its configuration when first Port changes its state to UP. -When the both interfaces joined the bridge - CPSW switch driver will enable +When both interfaces have joined the bridge - CPSW switch driver will enable marking packets with offload_fwd_mark flag unless "ale_bypass=0" All configuration is implemented via switchdev API. diff --git a/Documentation/networking/rds.rst b/Documentation/networking/rds.rst index 41b0a6182fe4..4261146e9d92 100644 --- a/Documentation/networking/rds.rst +++ b/Documentation/networking/rds.rst @@ -339,7 +339,7 @@ The send path rds_sendmsg() - struct rds_message built from incoming data - CMSGs parsed (e.g. RDMA ops) - - transport connection alloced and connected if not already + - transport connection allocated and connected if not already - rds_message placed on send queue - send worker awoken diff --git a/Documentation/power/pci.rst b/Documentation/power/pci.rst index 9ebecb7b00b2..38e614d92a4a 100644 --- a/Documentation/power/pci.rst +++ b/Documentation/power/pci.rst @@ -472,7 +472,7 @@ in the device tree from the root bridge to a leaf device contains both of them). The pci_pm_suspend_noirq() routine is executed after suspend_device_irqs() has been called, which means that the device driver's interrupt handler won't be invoked while this routine is running. It first checks if the device's driver -implements legacy PCI suspends routines (Section 3), in which case the legacy +implements legacy PCI suspend routines (Section 3), in which case the legacy late suspend routine is called and its result is returned (the standard configuration registers of the device are saved if the driver's callback hasn't done that). Second, if the device driver's struct dev_pm_ops object is not @@ -544,7 +544,7 @@ result is then returned). The resume phase is carried out asynchronously for PCI devices, like the suspend phase described above, which means that if two PCI devices don't depend on each other in a known way, the pci_pm_resume() routine may be executed for -the both of them in parallel. +both of them in parallel. The pci_pm_complete() routine only executes the device driver's pm->complete() callback, if defined. diff --git a/Documentation/power/suspend-and-cpuhotplug.rst b/Documentation/power/suspend-and-cpuhotplug.rst index ebedb6c75db9..641d09a6546b 100644 --- a/Documentation/power/suspend-and-cpuhotplug.rst +++ b/Documentation/power/suspend-and-cpuhotplug.rst @@ -13,7 +13,7 @@ infrastructure uses it internally? And where do they share common code? Well, a picture is worth a thousand words... So ASCII art follows :-) -[This depicts the current design in the kernel, and focusses only on the +[This depicts the current design in the kernel, and focuses only on the interactions involving the freezer and CPU hotplug and also tries to explain the locking involved. It outlines the notifications involved as well. But please note that here, only the call paths are illustrated, with the aim diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 22fa925353cf..9999bcbdccc9 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -207,10 +207,9 @@ document with a specification implemented by the patch:: Link: https://example.com/somewhere.html optional-other-stuff -Many maintainers when applying a patch also add this tag to link to the -latest public review posting of the patch; often this is automatically done -by tools like b4 or a git hook like the one described in -'Documentation/maintainer/configure-git.rst'. +As per guidance from the Chief Penguin, a Link: tag should only be added to +a commit if it leads to useful information that is not found in the commit +itself. If the URL points to a public bug report being fixed by the patch, use the "Closes:" tag instead:: diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index b38622b0d525..62951cdb13ad 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -61,7 +61,7 @@ Sphinx\ [#f1]_ 3.4.3 sphinx-build --version GNU tar 1.28 tar --version gtags (optional) 6.6.5 gtags --version mkimage (optional) 2017.01 mkimage --version -Python (optional) 3.9.x python3 --version +Python 3.9.x python3 --version GNU AWK (optional) 5.1.0 gawk --version ====================== =============== ======================================== @@ -154,6 +154,13 @@ Perl You will need perl 5 and the following modules: ``Getopt::Long``, ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. +Python +------ + +Several config options require it: it is required for arm/arm64 +default configs, CONFIG_LTO_CLANG, some DRM optional configs, +the kernel-doc tool, and docs build (Sphinx), among others. + BC -- diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index f5277993b195..b6919bf606c3 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -49,7 +49,7 @@ hosting infrastructure, regardless of how good the security practices for the latter may be. The above guiding principle is the reason why this guide is needed. We -want to make sure that by placing trust into developers we do not simply +want to make sure that by placing trust into developers we do not merely shift the blame for potential future security incidents to someone else. The goal is to provide a set of guidelines developers can use to create a secure working environment and safeguard the PGP keys used to @@ -60,7 +60,7 @@ establish the integrity of the Linux kernel itself. PGP tools ========= -Use GnuPG 2.2 or later +Use GnuPG 2.4 or later ---------------------- Your distro should already have GnuPG installed by default, you just @@ -69,9 +69,9 @@ To check, run:: $ gpg --version | head -n1 -If you have version 2.2 or above, then you are good to go. If you have a -version that is prior than 2.2, then some commands from this guide may -not work. +If you have version 2.4 or above, then you are good to go. If you have +an earlier version, then you are using a release of GnuPG that is no +longer maintained and some commands from this guide may not work. Configure gpg-agent options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -199,13 +199,6 @@ separate signing subkey:: $ gpg --quick-addkey [fpr] ed25519 sign -.. note:: ECC support in GnuPG - - Note, that if you intend to use a hardware token that does not - support ED25519 ECC keys, you should choose "nistp256" instead or - "ed25519." See the section below on recommended hardware devices. - - Back up your Certify key for disaster recovery ---------------------------------------------- @@ -213,7 +206,7 @@ The more signatures you have on your PGP key from other developers, the more reasons you have to create a backup version that lives on something other than digital media, for disaster recovery reasons. -The best way to create a printable hardcopy of your private key is by +A good way to create a printable hardcopy of your private key is by using the ``paperkey`` software written for this very purpose. See ``man paperkey`` for more details on the output format and its benefits over other solutions. Paperkey should already be packaged for most @@ -224,11 +217,11 @@ key:: $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt -Print out that file (or pipe the output straight to lpr), then take a -pen and write your passphrase on the margin of the paper. **This is -strongly recommended** because the key printout is still encrypted with -that passphrase, and if you ever change it you will not remember what it -used to be when you had created the backup -- *guaranteed*. +Print out that file, then take a pen and write your passphrase on the +margin of the paper. **This is strongly recommended** because the key +printout is still encrypted with that passphrase, and if you ever change +it you will not remember what it used to be when you had created the +backup -- *guaranteed*. Put the resulting printout and the hand-written passphrase into an envelope and store in a secure and well-protected place, preferably away from your @@ -236,10 +229,9 @@ home, such as your bank vault. .. note:: - Your printer is probably no longer a simple dumb device connected to - your parallel port, but since the output is still encrypted with - your passphrase, printing out even to "cloud-integrated" modern - printers should remain a relatively safe operation. + The key is still encrypted with your passphrase, so printing out + even to "cloud-integrated" modern printers should remain a + relatively safe operation. Back up your whole GnuPG directory ---------------------------------- @@ -255,16 +247,17 @@ on these external copies whenever you need to use your Certify key -- such as when making changes to your own key or signing other people's keys after conferences and summits. -Start by getting a small USB "thumb" drive (preferably two!) that you -will use for backup purposes. You will need to encrypt them using LUKS --- refer to your distro's documentation on how to accomplish this. +Start by getting an external media card (preferably two!) that you will +use for backup purposes. You will need to create an encrypted partition +on this device using LUKS -- refer to your distro's documentation on how +to accomplish this. For the encryption passphrase, you can use the same one as on your PGP key. -Once the encryption process is over, re-insert the USB drive and make -sure it gets properly mounted. Copy your entire ``.gnupg`` directory -over to the encrypted storage:: +Once the encryption process is over, re-insert your device and make sure +it gets properly mounted. Copy your entire ``.gnupg`` directory over to +the encrypted storage:: $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup @@ -273,11 +266,10 @@ You should now test to make sure everything still works:: $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] If you don't get any errors, then you should be good to go. Unmount the -USB drive, distinctly label it so you don't blow it away next time you -need to use a random USB drive, and put in a safe place -- but not too -far away, because you'll need to use it every now and again for things -like editing identities, adding or revoking subkeys, or signing other -people's keys. +device, distinctly label it so you don't overwrite it by accident, and +put in a safe place -- but not too far away, because you'll need to use +it every now and again for things like editing identities, adding or +revoking subkeys, or signing other people's keys. Remove the Certify key from your homedir ---------------------------------------- @@ -303,7 +295,7 @@ and store it on offline storage. your GnuPG directory in its entirety. What we are about to do will render your key useless if you do not have a usable backup! -First, identify the keygrip of your Certify key:: +First, identify the "keygrip" of your Certify key:: $ gpg --with-keygrip --list-key [fpr] @@ -328,8 +320,8 @@ Certify key fingerprint). This will correspond directly to a file in your 2222000000000000000000000000000000000000.key 3333000000000000000000000000000000000000.key -All you have to do is simply remove the .key file that corresponds to -the Certify key keygrip:: +It is sufficient to remove the .key file that corresponds to the Certify +key keygrip:: $ cd ~/.gnupg/private-keys-v1.d $ rm 1111000000000000000000000000000000000000.key @@ -372,7 +364,7 @@ GnuPG operation is performed, the keys are loaded into system memory and can be stolen from there by sufficiently advanced malware (think Meltdown and Spectre). -The best way to completely protect your keys is to move them to a +A good way to completely protect your keys is to move them to a specialized hardware device that is capable of smartcard operations. The benefits of smartcards @@ -383,11 +375,11 @@ private keys and performing crypto operations directly on the card itself. Because the key contents never leave the smartcard, the operating system of the computer into which you plug in the hardware device is not able to retrieve the private keys themselves. This is very -different from the encrypted USB storage device we used earlier for -backup purposes -- while that USB device is plugged in and mounted, the +different from the encrypted media storage device we used earlier for +backup purposes -- while that device is plugged in and mounted, the operating system is able to access the private key contents. -Using external encrypted USB media is not a substitute to having a +Using external encrypted media is not a substitute to having a smartcard-capable device. Available smartcard devices @@ -398,17 +390,15 @@ easiest is to get a specialized USB device that implements smartcard functionality. There are several options available: - `Nitrokey Start`_: Open hardware and Free Software, based on FSI - Japan's `Gnuk`_. One of the few available commercial devices that - support ED25519 ECC keys, but offer fewest security features (such as - resistance to tampering or some side-channel attacks). -- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more - tamper-resistant and offers more security features. Pro 2 supports ECC - cryptography (NISTP). + Japan's `Gnuk`_. One of the cheapest options, but offers fewest + security features (such as resistance to tampering or some + side-channel attacks). +- `Nitrokey 3`_: Similar to the Nitrokey Start, but more + tamper-resistant and offers more security features and USB + form-factors. Supports ECC cryptography (ED25519 and NISTP). - `Yubikey 5`_: proprietary hardware and software, but cheaper than - Nitrokey Pro and comes available in the USB-C form that is more useful - with newer laptops. Offers additional security features such as FIDO - U2F, among others, and now finally supports NISTP and ED25519 ECC - keys. + Nitrokey with a similar set of features. Supports ECC cryptography + (ED25519 and NISTP). Your choice will depend on cost, shipping availability in your geographical region, and open/proprietary hardware considerations. @@ -419,8 +409,8 @@ geographical region, and open/proprietary hardware considerations. you `qualify for a free Nitrokey Start`_ courtesy of The Linux Foundation. -.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 -.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 +.. _`Nitrokey Start`: https://www.nitrokey.com/products/nitrokeys +.. _`Nitrokey 3`: https://www.nitrokey.com/products/nitrokeys .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html @@ -455,7 +445,7 @@ the smartcard). You so rarely need to use the Admin PIN, that you will inevitably forget what it is if you do not record it. Getting back to the main card menu, you can also set other values (such -as name, sex, login data, etc), but it's not necessary and will +as name, gender, login data, etc), but it's not necessary and will additionally leak information about your smartcard should you lose it. .. note:: @@ -615,7 +605,7 @@ run:: You can also use a specific date if that is easier to remember (e.g. your birthday, January 1st, or Canada Day):: - $ gpg --quick-set-expire [fpr] 2025-07-01 + $ gpg --quick-set-expire [fpr] 2038-07-01 Remember to send the updated key back to keyservers:: @@ -656,9 +646,9 @@ hundreds of cloned repositories floating around, how does anyone verify that their copy of linux.git has not been tampered with by a malicious third party? -Or what happens if a backdoor is discovered in the code and the "Author" -line in the commit says it was done by you, while you're pretty sure you -had `nothing to do with it`_? +Or what happens if malicious code is discovered in the kernel and the +"Author" line in the commit says it was done by you, while you're pretty +sure you had `nothing to do with it`_? To address both of these issues, Git introduced PGP integration. Signed tags prove the repository integrity by assuring that its contents are @@ -681,8 +671,7 @@ should be used (``[fpr]`` is the fingerprint of your key):: How to work with signed tags ---------------------------- -To create a signed tag, simply pass the ``-s`` switch to the tag -command:: +To create a signed tag, pass the ``-s`` switch to the tag command:: $ git tag -s [tagname] @@ -693,7 +682,7 @@ not been maliciously altered. How to verify signed tags ~~~~~~~~~~~~~~~~~~~~~~~~~ -To verify a signed tag, simply use the ``verify-tag`` command:: +To verify a signed tag, use the ``verify-tag`` command:: $ git verify-tag [tagname] @@ -712,9 +701,9 @@ The merge message will contain something like this:: # gpg: Signature made [...] # gpg: Good signature from [...] -If you are verifying someone else's git tag, then you will need to -import their PGP key. Please refer to the -":ref:`verify_identities`" section below. +If you are verifying someone else's git tag, you will first need to +import their PGP key. Please refer to the ":ref:`verify_identities`" +section below. Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -728,16 +717,16 @@ configuration option:: How to work with signed commits ------------------------------- -It is easy to create signed commits, but it is much more difficult to -use them in Linux kernel development, since it relies on patches sent to -the mailing list, and this workflow does not preserve PGP commit -signatures. Furthermore, when rebasing your repository to match -upstream, even your own PGP commit signatures will end up discarded. For -this reason, most kernel developers don't bother signing their commits -and will ignore signed commits in any external repositories that they -rely upon in their work. +It is also possible to create signed commits, but they have limited +usefulness in Linux kernel development. The kernel contribution workflow +relies on sending in patches, and converting commits to patches does not +preserve git commit signatures. Furthermore, when rebasing your own +repository on a newer upstream, PGP commit signatures will end up +discarded. For this reason, most kernel developers don't bother signing +their commits and will ignore signed commits in any external +repositories that they rely upon in their work. -However, if you have your working git tree publicly available at some +That said, if you have your working git tree publicly available at some git hosting service (kernel.org, infradead.org, ozlabs.org, or others), then the recommendation is that you sign all your git commits even if upstream developers do not directly benefit from this practice. @@ -748,7 +737,7 @@ We recommend this for the following reasons: provenance, even externally maintained trees carrying PGP commit signatures will be valuable for such purposes. 2. If you ever need to re-clone your local repository (for example, - after a disk failure), this lets you easily verify the repository + after reinstalling your system), this lets you verify the repository integrity before resuming your work. 3. If someone needs to cherry-pick your commits, this allows them to quickly verify their integrity before applying them. @@ -756,9 +745,8 @@ We recommend this for the following reasons: Creating signed commits ~~~~~~~~~~~~~~~~~~~~~~~ -To create a signed commit, you just need to pass the ``-S`` flag to the -``git commit`` command (it's capital ``-S`` due to collision with -another flag):: +To create a signed commit, pass the ``-S`` flag to the ``git commit`` +command (it's capital ``-S`` due to collision with another flag):: $ git commit -S @@ -775,7 +763,6 @@ You can tell git to always sign commits:: .. _verify_identities: - How to work with signed patches ------------------------------- @@ -793,6 +780,11 @@ headers (a-la DKIM): Installing and configuring patatt ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + + If you use B4 to send in your patches, patatt is already installed + and integrated into your workflow. + Patatt is packaged for many distributions already, so please check there first. You can also install it from pypi using "``pip install patatt``". @@ -835,9 +827,9 @@ encounters, for example:: How to verify kernel developer identities ========================================= -Signing tags and commits is easy, but how does one go about verifying -that the key used to sign something belongs to the actual kernel -developer and not to a malicious imposter? +Signing tags and commits is straightforward, but how does one go about +verifying that the key used to sign something belongs to the actual +kernel developer and not to a malicious imposter? Configure auto-key-retrieval using WKD and DANE ----------------------------------------------- @@ -884,7 +876,7 @@ various software makers dictating who should be your trusted certifying entity, PGP leaves this responsibility to each user. Unfortunately, very few people understand how the Web of Trust works. -While it remains an important aspect of the OpenPGP specification, +While it is still an important part of the OpenPGP specification, recent versions of GnuPG (2.2 and above) have implemented an alternative mechanism called "Trust on First Use" (TOFU). You can think of TOFU as "the SSH-like approach to trust." With SSH, the first time you connect @@ -894,8 +886,8 @@ to connect, forcing you to make a decision on whether you choose to trust the changed key or not. Similarly, the first time you import someone's PGP key, it is assumed to be valid. If at any point in the future GnuPG comes across another key with the same identity, both the -previously imported key and the new key will be marked as invalid and -you will need to manually figure out which one to keep. +previously imported key and the new key will be marked for verification +and you will need to manually figure out which one to keep. We recommend that you use the combined TOFU+PGP trust model (which is the new default in GnuPG v2). To set it, add (or modify) the diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index cede4e7b29af..910e8fc9e3c8 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -343,7 +343,7 @@ https://en.wikipedia.org/wiki/Posting_style#Interleaved_style As is frequently quoted on the mailing list:: A: http://en.wikipedia.org/wiki/Top_post - Q: Were do I find info about this thing called top-posting? + Q: Where do I find info about this thing called top-posting? A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing? A: Top-posting. @@ -602,8 +602,8 @@ future. Note, this is one of only three tags you might be able to use without explicit permission of the person named (see 'Tagging people requires permission' below for details). -A Fixes: tag indicates that the patch fixes an issue in a previous commit. It -is used to make it easy to determine where a bug originated, which can help +A Fixes: tag indicates that the patch fixes a bug in a previous commit. It +is used to make it easy to determine where an issue originated, which can help review a bug fix. This tag also assists the stable kernel team in determining which stable kernel versions should receive your fix. This is the preferred method for indicating a bug fixed by the patch. See :ref:`describe_changes` diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 563033f764bb..1d9dada40a74 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -244,7 +244,7 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None): return contnode # -# Variant of markup_abi_ref() that warns whan a reference is not found +# Variant of markup_abi_ref() that warns when a reference is not found # def markup_abi_file_ref(docname, app, match): return markup_abi_ref(docname, app, match, warning=True) diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py deleted file mode 100644 index 3dc285dc70f5..000000000000 --- a/Documentation/sphinx/cdomain.py +++ /dev/null @@ -1,247 +0,0 @@ -# -*- coding: utf-8; mode: python -*- -# SPDX-License-Identifier: GPL-2.0 -# pylint: disable=W0141,C0113,C0103,C0325 -""" - cdomain - ~~~~~~~ - - Replacement for the sphinx c-domain. - - :copyright: Copyright (C) 2016 Markus Heiser - :license: GPL Version 2, June 1991 see Linux/COPYING for details. - - List of customizations: - - * Moved the *duplicate C object description* warnings for function - declarations in the nitpicky mode. See Sphinx documentation for - the config values for ``nitpick`` and ``nitpick_ignore``. - - * Add option 'name' to the "c:function:" directive. With option 'name' the - ref-name of a function can be modified. E.g.:: - - .. c:function:: int ioctl( int fd, int request ) - :name: VIDIOC_LOG_STATUS - - The func-name (e.g. ioctl) remains in the output but the ref-name changed - from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by:: - - * :c:func:`VIDIOC_LOG_STATUS` or - * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) - - * Handle signatures of function-like macros well. Don't try to deduce - arguments types of function-like macros. - -""" - -from docutils import nodes -from docutils.parsers.rst import directives - -import sphinx -from sphinx import addnodes -from sphinx.domains.c import c_funcptr_sig_re, c_sig_re -from sphinx.domains.c import CObject as Base_CObject -from sphinx.domains.c import CDomain as Base_CDomain -from itertools import chain -import re - -__version__ = '1.1' - -# Namespace to be prepended to the full name -namespace = None - -# -# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags -# - Store the namespace if ".. c:namespace::" tag is found -# -RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') - -def markup_namespace(match): - global namespace - - namespace = match.group(1) - - return "" - -# -# Handle c:macro for function-style declaration -# -RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$') -def markup_macro(match): - return ".. c:function:: " + match.group(1) + ' ' + match.group(2) - -# -# Handle newer c domain tags that are evaluated as .. c:type: for -# backward-compatibility with Sphinx < 3.0 -# -RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$') - -def markup_ctype(match): - return ".. c:type:: " + match.group(2) - -# -# Handle newer c domain tags that are evaluated as :c:type: for -# backward-compatibility with Sphinx < 3.0 -# -RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`') -def markup_ctype_refs(match): - return ":c:type:`" + match.group(2) + '`' - -# -# Simply convert :c:expr: and :c:texpr: into a literal block. -# -RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') -def markup_c_expr(match): - return '\\ ``' + match.group(2) + '``\\ ' - -# -# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones -# -def c_markups(app, docname, source): - result = "" - markup_func = { - RE_namespace: markup_namespace, - RE_expr: markup_c_expr, - RE_macro: markup_macro, - RE_ctype: markup_ctype, - RE_ctype_refs: markup_ctype_refs, - } - - lines = iter(source[0].splitlines(True)) - for n in lines: - match_iterators = [regex.finditer(n) for regex in markup_func] - matches = sorted(chain(*match_iterators), key=lambda m: m.start()) - for m in matches: - n = n[:m.start()] + markup_func[m.re](m) + n[m.end():] - - result = result + n - - source[0] = result - -# -# Now implements support for the cdomain namespacing logic -# - -def setup(app): - - # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace:: - app.connect('source-read', c_markups) - app.add_domain(CDomain, override=True) - - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) - -class CObject(Base_CObject): - - """ - Description of a C language object. - """ - option_spec = { - "name" : directives.unchanged - } - - def handle_func_like_macro(self, sig, signode): - """Handles signatures of function-like macros. - - If the objtype is 'function' and the signature ``sig`` is a - function-like macro, the name of the macro is returned. Otherwise - ``False`` is returned. """ - - global namespace - - if not self.objtype == 'function': - return False - - m = c_funcptr_sig_re.match(sig) - if m is None: - m = c_sig_re.match(sig) - if m is None: - raise ValueError('no match') - - rettype, fullname, arglist, _const = m.groups() - arglist = arglist.strip() - if rettype or not arglist: - return False - - arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup - arglist = [a.strip() for a in arglist.split(",")] - - # has the first argument a type? - if len(arglist[0].split(" ")) > 1: - return False - - # This is a function-like macro, its arguments are typeless! - signode += addnodes.desc_name(fullname, fullname) - paramlist = addnodes.desc_parameterlist() - signode += paramlist - - for argname in arglist: - param = addnodes.desc_parameter('', '', noemph=True) - # separate by non-breaking space in the output - param += nodes.emphasis(argname, argname) - paramlist += param - - if namespace: - fullname = namespace + "." + fullname - - return fullname - - def handle_signature(self, sig, signode): - """Transform a C signature into RST nodes.""" - - global namespace - - fullname = self.handle_func_like_macro(sig, signode) - if not fullname: - fullname = super(CObject, self).handle_signature(sig, signode) - - if "name" in self.options: - if self.objtype == 'function': - fullname = self.options["name"] - else: - # FIXME: handle :name: value of other declaration types? - pass - else: - if namespace: - fullname = namespace + "." + fullname - - return fullname - - def add_target_and_index(self, name, sig, signode): - # for C API items we add a prefix since names are usually not qualified - # by a module name and so easily clash with e.g. section titles - targetname = 'c.' + name - if targetname not in self.state.document.ids: - signode['names'].append(targetname) - signode['ids'].append(targetname) - signode['first'] = (not self.names) - self.state.document.note_explicit_target(signode) - inv = self.env.domaindata['c']['objects'] - if (name in inv and self.env.config.nitpicky): - if self.objtype == 'function': - if ('c:func', name) not in self.env.config.nitpick_ignore: - self.state_machine.reporter.warning( - 'duplicate C object description of %s, ' % name + - 'other instance in ' + self.env.doc2path(inv[name][0]), - line=self.lineno) - inv[name] = (self.env.docname, self.objtype) - - indextext = self.get_index_text(name) - if indextext: - self.indexnode['entries'].append( - ('single', indextext, targetname, '', None)) - -class CDomain(Base_CDomain): - - """C language domain.""" - name = 'c' - label = 'C' - directives = { - 'function': CObject, - 'member': CObject, - 'macro': CObject, - 'type': CObject, - 'var': CObject, - } diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index e3a51867f27b..aaac76892ceb 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -40,9 +40,11 @@ import sys from docutils import nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive -from docutils.utils.error_reporting import ErrorString from sphinx.util.docutils import switch_source_input +def ErrorString(exc): # Shamelessly stolen from docutils + return f'{exc.__class__.__name}: {exc}' + __version__ = '1.0' def setup(app): diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 1e566e87ebcd..f94412cd17c9 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -1,31 +1,82 @@ #!/usr/bin/env python3 -# -*- coding: utf-8; mode: python -*- # SPDX-License-Identifier: GPL-2.0 -# pylint: disable=R0903, C0330, R0914, R0912, E0401 +# pylint: disable=R0903, R0912, R0914, R0915, C0209,W0707 + """ - kernel-include - ~~~~~~~~~~~~~~ +Implementation of the ``kernel-include`` reST-directive. + +:copyright: Copyright (C) 2016 Markus Heiser +:license: GPL Version 2, June 1991 see linux/COPYING for details. + +The ``kernel-include`` reST-directive is a replacement for the ``include`` +directive. The ``kernel-include`` directive expand environment variables in +the path name and allows to include files from arbitrary locations. + +.. hint:: + + Including files from arbitrary locations (e.g. from ``/etc``) is a + security risk for builders. This is why the ``include`` directive from + docutils *prohibit* pathnames pointing to locations *above* the filesystem + tree where the reST document with the include directive is placed. + +Substrings of the form $name or ${name} are replaced by the value of +environment variable name. Malformed variable names and references to +non-existing variables are left unchanged. + +**Supported Sphinx Include Options**: + +:param literal: + If present, the included file is inserted as a literal block. + +:param code: + Specify the language for syntax highlighting (e.g., 'c', 'python'). + +:param encoding: + Specify the encoding of the included file (default: 'utf-8'). + +:param tab-width: + Specify the number of spaces that a tab represents. + +:param start-line: + Line number at which to start including the file (1-based). + +:param end-line: + Line number at which to stop including the file (inclusive). + +:param start-after: + Include lines after the first line matching this text. + +:param end-before: + Include lines before the first line matching this text. - Implementation of the ``kernel-include`` reST-directive. +:param number-lines: + Number the included lines (integer specifies start number). + Only effective with 'literal' or 'code' options. - :copyright: Copyright (C) 2016 Markus Heiser - :license: GPL Version 2, June 1991 see linux/COPYING for details. +:param class: + Specify HTML class attribute for the included content. - The ``kernel-include`` reST-directive is a replacement for the ``include`` - directive. The ``kernel-include`` directive expand environment variables in - the path name and allows to include files from arbitrary locations. +**Kernel-specific Extensions**: - .. hint:: +:param generate-cross-refs: + If present, instead of directly including the file, it calls + ParseDataStructs() to convert C data structures into cross-references + that link to comprehensive documentation in other ReST files. - Including files from arbitrary locations (e.g. from ``/etc``) is a - security risk for builders. This is why the ``include`` directive from - docutils *prohibit* pathnames pointing to locations *above* the filesystem - tree where the reST document with the include directive is placed. +:param exception-file: + (Used with generate-cross-refs) - Substrings of the form $name or ${name} are replaced by the value of - environment variable name. Malformed variable names and references to - non-existing variables are left unchanged. + Path to a file containing rules for handling special cases: + - Ignore specific C data structures + - Use alternative reference names + - Specify different reference types + +:param warn-broken: + (Used with generate-cross-refs) + + Enables warnings when auto-generated cross-references don't point to + existing documentation targets. """ # ============================================================================== @@ -33,161 +84,366 @@ # ============================================================================== import os.path +import re +import sys from docutils import io, nodes, statemachine -from docutils.utils.error_reporting import SafeString, ErrorString -from docutils.parsers.rst import directives +from docutils.statemachine import ViewList +from docutils.parsers.rst import Directive, directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines -from docutils.parsers.rst.directives.misc import Include -__version__ = '1.0' +from sphinx.util import logging -# ============================================================================== -def setup(app): -# ============================================================================== +srctree = os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "tools/docs/lib")) - app.add_directive("kernel-include", KernelInclude) - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) +from parse_data_structs import ParseDataStructs -# ============================================================================== -class KernelInclude(Include): -# ============================================================================== +__version__ = "1.0" +logger = logging.getLogger(__name__) - """KernelInclude (``kernel-include``) directive""" +RE_DOMAIN_REF = re.compile(r'\\ :(ref|c:type|c:func):`([^<`]+)(?:<([^>]+)>)?`\\') +RE_SIMPLE_REF = re.compile(r'`([^`]+)`') - def run(self): - env = self.state.document.settings.env - path = os.path.realpath( - os.path.expandvars(self.arguments[0])) +def ErrorString(exc): # Shamelessly stolen from docutils + return f'{exc.__class__.__name}: {exc}' - # to get a bit security back, prohibit /etc: - if path.startswith(os.sep + "etc"): - raise self.severe( - 'Problems with "%s" directive, prohibited path: %s' - % (self.name, path)) - self.arguments[0] = path +# ============================================================================== +class KernelInclude(Directive): + """ + KernelInclude (``kernel-include``) directive - env.note_dependency(os.path.abspath(path)) + Most of the stuff here came from Include directive defined at: + docutils/parsers/rst/directives/misc.py - #return super(KernelInclude, self).run() # won't work, see HINTs in _run() - return self._run() + Yet, overriding the class don't has any benefits: the original class + only have run() and argument list. Not all of them are implemented, + when checked against latest Sphinx version, as with time more arguments + were added. - def _run(self): - """Include a file as part of the content of this reST file.""" + So, keep its own list of supported arguments + """ - # HINT: I had to copy&paste the whole Include.run method. I'am not happy - # with this, but due to security reasons, the Include.run method does - # not allow absolute or relative pathnames pointing to locations *above* - # the filesystem tree where the reST document is placed. + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'literal': directives.flag, + 'code': directives.unchanged, + 'encoding': directives.encoding, + 'tab-width': int, + 'start-line': int, + 'end-line': int, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, + # ignored except for 'literal' or 'code': + 'number-lines': directives.unchanged, # integer or None + 'class': directives.class_option, - if not self.state.document.settings.file_insertion_enabled: - raise self.warning('"%s" directive disabled.' % self.name) - source = self.state_machine.input_lines.source( - self.lineno - self.state_machine.input_offset - 1) - source_dir = os.path.dirname(os.path.abspath(source)) - path = directives.path(self.arguments[0]) - if path.startswith('<') and path.endswith('>'): - path = os.path.join(self.standard_include_path, path[1:-1]) - path = os.path.normpath(os.path.join(source_dir, path)) + # Arguments that aren't from Sphinx Include directive + 'generate-cross-refs': directives.flag, + 'warn-broken': directives.flag, + 'toc': directives.flag, + 'exception-file': directives.unchanged, + } - # HINT: this is the only line I had to change / commented out: - #path = utils.relative_path(None, path) + def read_rawtext(self, path, encoding): + """Read and process file content with error handling""" + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput(source_path=path, + encoding=encoding, + error_handler=self.state.document.settings.input_encoding_error_handler) + except UnicodeEncodeError: + raise self.severe('Problems with directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % path) + except IOError as error: + raise self.severe('Problems with directive path:\n%s.' % ErrorString(error)) - encoding = self.options.get( - 'encoding', self.state.document.settings.input_encoding) - e_handler=self.state.document.settings.input_encoding_error_handler - tab_width = self.options.get( - 'tab-width', self.state.document.settings.tab_width) - try: - self.state.document.settings.record_dependencies.add(path) - include_file = io.FileInput(source_path=path, - encoding=encoding, - error_handler=e_handler) - except UnicodeEncodeError as error: - raise self.severe('Problems with "%s" directive path:\n' - 'Cannot encode input file path "%s" ' - '(wrong locale?).' % - (self.name, SafeString(path))) - except IOError as error: - raise self.severe('Problems with "%s" directive path:\n%s.' % - (self.name, ErrorString(error))) + try: + return include_file.read() + except UnicodeError as error: + raise self.severe('Problem with directive:\n%s' % ErrorString(error)) + + def apply_range(self, rawtext): + """ + Handles start-line, end-line, start-after and end-before parameters + """ + + # Get to-be-included content startline = self.options.get('start-line', None) endline = self.options.get('end-line', None) try: if startline or (endline is not None): - lines = include_file.readlines() - rawtext = ''.join(lines[startline:endline]) - else: - rawtext = include_file.read() + lines = rawtext.splitlines() + rawtext = '\n'.join(lines[startline:endline]) except UnicodeError as error: - raise self.severe('Problem with "%s" directive:\n%s' % - (self.name, ErrorString(error))) + raise self.severe(f'Problem with "{self.name}" directive:\n' + + io.error_string(error)) # start-after/end-before: no restrictions on newlines in match-text, # and no restrictions on matching inside lines vs. line boundaries - after_text = self.options.get('start-after', None) + after_text = self.options.get("start-after", None) if after_text: # skip content in rawtext before *and incl.* a matching text after_index = rawtext.find(after_text) if after_index < 0: raise self.severe('Problem with "start-after" option of "%s" ' - 'directive:\nText not found.' % self.name) - rawtext = rawtext[after_index + len(after_text):] - before_text = self.options.get('end-before', None) + "directive:\nText not found." % self.name) + rawtext = rawtext[after_index + len(after_text) :] + before_text = self.options.get("end-before", None) if before_text: # skip content in rawtext after *and incl.* a matching text before_index = rawtext.find(before_text) if before_index < 0: raise self.severe('Problem with "end-before" option of "%s" ' - 'directive:\nText not found.' % self.name) + "directive:\nText not found." % self.name) rawtext = rawtext[:before_index] + return rawtext + + def xref_text(self, env, path, tab_width): + """ + Read and add contents from a C file parsed to have cross references. + + There are two types of supported output here: + - A C source code with cross-references; + - a TOC table containing cross references. + """ + parser = ParseDataStructs() + parser.parse_file(path) + + if 'exception-file' in self.options: + source_dir = os.path.dirname(os.path.abspath( + self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1))) + exceptions_file = os.path.join(source_dir, self.options['exception-file']) + parser.process_exceptions(exceptions_file) + + # Store references on a symbol dict to be used at check time + if 'warn-broken' in self.options: + env._xref_files.add(path) + + if "toc" not in self.options: + + rawtext = ".. parsed-literal::\n\n" + parser.gen_output() + self.apply_range(rawtext) + + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + + # Sphinx always blame the ".. <directive>", so placing + # line numbers here won't make any difference + + self.state_machine.insert_input(include_lines, path) + return [] + + # TOC output is a ReST file, not a literal. So, we can add line + # numbers + + rawtext = parser.gen_toc() + include_lines = statemachine.string2lines(rawtext, tab_width, convert_whitespace=True) - if 'literal' in self.options: - # Convert tabs to spaces, if `tab_width` is positive. - if tab_width >= 0: - text = rawtext.expandtabs(tab_width) - else: - text = rawtext - literal_block = nodes.literal_block(rawtext, source=path, - classes=self.options.get('class', [])) - literal_block.line = 1 - self.add_name(literal_block) - if 'number-lines' in self.options: - try: - startline = int(self.options['number-lines'] or 1) - except ValueError: - raise self.error(':number-lines: with non-integer ' - 'start value') - endline = startline + len(include_lines) - if text.endswith('\n'): - text = text[:-1] - tokens = NumberLines([([], text)], startline, endline) - for classes, value in tokens: - if classes: - literal_block += nodes.inline(value, value, - classes=classes) - else: - literal_block += nodes.Text(value, value) - else: - literal_block += nodes.Text(text, text) - return [literal_block] - if 'code' in self.options: - self.options['source'] = path - codeblock = CodeBlock(self.name, - [self.options.pop('code')], # arguments - self.options, - include_lines, # content - self.lineno, - self.content_offset, - self.block_text, - self.state, - self.state_machine) - return codeblock.run() - self.state_machine.insert_input(include_lines, path) + + # Append line numbers data + + startline = self.options.get('start-line', None) + + result = ViewList() + if startline and startline > 0: + offset = startline - 1 + else: + offset = 0 + + for ln, line in enumerate(include_lines, start=offset): + result.append(line, path, ln) + + self.state_machine.insert_input(result, path) + return [] + + def literal(self, path, tab_width, rawtext): + """Output a literal block""" + + # Convert tabs to spaces, if `tab_width` is positive. + if tab_width >= 0: + text = rawtext.expandtabs(tab_width) + else: + text = rawtext + literal_block = nodes.literal_block(rawtext, source=path, + classes=self.options.get("class", [])) + literal_block.line = 1 + self.add_name(literal_block) + if "number-lines" in self.options: + try: + startline = int(self.options["number-lines"] or 1) + except ValueError: + raise self.error(":number-lines: with non-integer start value") + endline = startline + len(include_lines) + if text.endswith("\n"): + text = text[:-1] + tokens = NumberLines([([], text)], startline, endline) + for classes, value in tokens: + if classes: + literal_block += nodes.inline(value, value, + classes=classes) + else: + literal_block += nodes.Text(value, value) + else: + literal_block += nodes.Text(text, text) + return [literal_block] + + def code(self, path, tab_width): + """Output a code block""" + + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + + self.options["source"] = path + codeblock = CodeBlock(self.name, + [self.options.pop("code")], # arguments + self.options, + include_lines, + self.lineno, + self.content_offset, + self.block_text, + self.state, + self.state_machine) + return codeblock.run() + + def run(self): + """Include a file as part of the content of this reST file.""" + env = self.state.document.settings.env + + # + # The include logic accepts only patches relative to the + # Kernel source tree. The logic does check it to prevent + # directory traverse issues. + # + + srctree = os.path.abspath(os.environ["srctree"]) + + path = os.path.expandvars(self.arguments[0]) + src_path = os.path.join(srctree, path) + + if os.path.isfile(src_path): + base = srctree + path = src_path + else: + raise self.warning(f'File "%s" doesn\'t exist', path) + + abs_base = os.path.abspath(base) + abs_full_path = os.path.abspath(os.path.join(base, path)) + + try: + if os.path.commonpath([abs_full_path, abs_base]) != abs_base: + raise self.severe('Problems with "%s" directive, prohibited path: %s' % + (self.name, path)) + except ValueError: + # Paths don't have the same drive (Windows) or other incompatibility + raise self.severe('Problems with "%s" directive, invalid path: %s' % + (self.name, path)) + + self.arguments[0] = path + + # + # Add path location to Sphinx dependencies to ensure proper cache + # invalidation check. + # + + env.note_dependency(os.path.abspath(path)) + + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + source = self.state_machine.input_lines.source(self.lineno - + self.state_machine.input_offset - 1) + source_dir = os.path.dirname(os.path.abspath(source)) + path = directives.path(self.arguments[0]) + if path.startswith("<") and path.endswith(">"): + path = os.path.join(self.standard_include_path, path[1:-1]) + path = os.path.normpath(os.path.join(source_dir, path)) + + # HINT: this is the only line I had to change / commented out: + # path = utils.relative_path(None, path) + + encoding = self.options.get("encoding", + self.state.document.settings.input_encoding) + tab_width = self.options.get("tab-width", + self.state.document.settings.tab_width) + + # Get optional arguments to related to cross-references generation + if "generate-cross-refs" in self.options: + return self.xref_text(env, path, tab_width) + + rawtext = self.read_rawtext(path, encoding) + rawtext = self.apply_range(rawtext) + + if "code" in self.options: + return self.code(path, tab_width, rawtext) + + return self.literal(path, tab_width, rawtext) + +# ============================================================================== + +reported = set() + +def check_missing_refs(app, env, node, contnode): + """Check broken refs for the files it creates xrefs""" + if not node.source: + return None + + try: + xref_files = env._xref_files + except AttributeError: + logger.critical("FATAL: _xref_files not initialized!") + raise + + # Only show missing references for kernel-include reference-parsed files + if node.source not in xref_files: + return None + + target = node.get('reftarget', '') + domain = node.get('refdomain', 'std') + reftype = node.get('reftype', '') + + msg = f"can't link to: {domain}:{reftype}:: {target}" + + # Don't duplicate warnings + data = (node.source, msg) + if data in reported: + return None + reported.add(data) + + logger.warning(msg, location=node, type='ref', subtype='missing') + + return None + +def merge_xref_info(app, env, docnames, other): + """ + As each process modify env._xref_files, we need to merge them back. + """ + if not hasattr(other, "_xref_files"): + return + env._xref_files.update(getattr(other, "_xref_files", set())) + +def init_xref_docs(app, env, docnames): + """Initialize a list of files that we're generating cross references¨""" + app.env._xref_files = set() + +# ============================================================================== + +def setup(app): + """Setup Sphinx exension""" + + app.connect("env-before-read-docs", init_xref_docs) + app.connect("env-merge-info", merge_xref_info) + app.add_directive("kernel-include", KernelInclude) + app.connect("missing-reference", check_missing_refs) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index d31cff867436..519ad18685b2 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -22,10 +22,12 @@ import re import os.path from docutils import statemachine -from docutils.utils.error_reporting import ErrorString from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include +def ErrorString(exc): # Shamelessly stolen from docutils + return f'{exc.__class__.__name}: {exc}' + __version__ = '1.0' def setup(app): diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl deleted file mode 100755 index 7b1458544e2e..000000000000 --- a/Documentation/sphinx/parse-headers.pl +++ /dev/null @@ -1,404 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 -# Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@kernel.org>. - -use strict; -use Text::Tabs; -use Getopt::Long; -use Pod::Usage; - -my $debug; -my $help; -my $man; - -GetOptions( - "debug" => \$debug, - 'usage|?' => \$help, - 'help' => \$man -) or pod2usage(2); - -pod2usage(1) if $help; -pod2usage(-exitstatus => 0, -verbose => 2) if $man; -pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3); - -my ($file_in, $file_out, $file_exceptions) = @ARGV; - -my $data; -my %ioctls; -my %defines; -my %typedefs; -my %enums; -my %enum_symbols; -my %structs; - -require Data::Dumper if ($debug); - -# -# read the file and get identifiers -# - -my $is_enum = 0; -my $is_comment = 0; -open IN, $file_in or die "Can't open $file_in"; -while (<IN>) { - $data .= $_; - - my $ln = $_; - if (!$is_comment) { - $ln =~ s,/\*.*(\*/),,g; - - $is_comment = 1 if ($ln =~ s,/\*.*,,); - } else { - if ($ln =~ s,^(.*\*/),,) { - $is_comment = 0; - } else { - next; - } - } - - if ($is_enum && $ln =~ m/^\s*([_\w][\w\d_]+)\s*[\,=]?/) { - my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; - - $enum_symbols{$s} = "\\ :ref:`$s <$n>`\\ "; - - $is_enum = 0 if ($is_enum && m/\}/); - next; - } - $is_enum = 0 if ($is_enum && m/\}/); - - if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+_IO/) { - my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - - $ioctls{$s} = "\\ :ref:`$s <$n>`\\ "; - next; - } - - if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+/) { - my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; - - $defines{$s} = "\\ :ref:`$s <$n>`\\ "; - next; - } - - if ($ln =~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) { - my $s = $2; - my $n = $3; - - $typedefs{$n} = "\\ :c:type:`$n <$s>`\\ "; - next; - } - if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/ - || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) { - my $s = $1; - - $enums{$s} = "enum :c:type:`$s`\\ "; - - $is_enum = $1; - next; - } - if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/ - || $ln =~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/ - ) { - my $s = $1; - - $structs{$s} = "struct $s\\ "; - next; - } -} -close IN; - -# -# Handle multi-line typedefs -# - -my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g, - $data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,); -foreach my $m (@matches) { - my $s = $m; - - $typedefs{$s} = "\\ :c:type:`$s`\\ "; - next; -} - -# -# Handle exceptions, if any -# - -my %def_reftype = ( - "ioctl" => ":ref", - "define" => ":ref", - "symbol" => ":ref", - "typedef" => ":c:type", - "enum" => ":c:type", - "struct" => ":c:type", -); - -if ($file_exceptions) { - open IN, $file_exceptions or die "Can't read $file_exceptions"; - while (<IN>) { - next if (m/^\s*$/ || m/^\s*#/); - - # Parsers to ignore a symbol - - if (m/^ignore\s+ioctl\s+(\S+)/) { - delete $ioctls{$1} if (exists($ioctls{$1})); - next; - } - if (m/^ignore\s+define\s+(\S+)/) { - delete $defines{$1} if (exists($defines{$1})); - next; - } - if (m/^ignore\s+typedef\s+(\S+)/) { - delete $typedefs{$1} if (exists($typedefs{$1})); - next; - } - if (m/^ignore\s+enum\s+(\S+)/) { - delete $enums{$1} if (exists($enums{$1})); - next; - } - if (m/^ignore\s+struct\s+(\S+)/) { - delete $structs{$1} if (exists($structs{$1})); - next; - } - if (m/^ignore\s+symbol\s+(\S+)/) { - delete $enum_symbols{$1} if (exists($enum_symbols{$1})); - next; - } - - # Parsers to replace a symbol - my ($type, $old, $new, $reftype); - - if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) { - $type = $1; - $old = $2; - $new = $3; - } else { - die "Can't parse $file_exceptions: $_"; - } - - if ($new =~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) { - $reftype = ":c:$1"; - $new = $2; - } elsif ($new =~ m/\:ref\:\`(.+)\`/) { - $reftype = ":ref"; - $new = $1; - } else { - $reftype = $def_reftype{$type}; - } - $new = "$reftype:`$old <$new>`"; - - if ($type eq "ioctl") { - $ioctls{$old} = $new if (exists($ioctls{$old})); - next; - } - if ($type eq "define") { - $defines{$old} = $new if (exists($defines{$old})); - next; - } - if ($type eq "symbol") { - $enum_symbols{$old} = $new if (exists($enum_symbols{$old})); - next; - } - if ($type eq "typedef") { - $typedefs{$old} = $new if (exists($typedefs{$old})); - next; - } - if ($type eq "enum") { - $enums{$old} = $new if (exists($enums{$old})); - next; - } - if ($type eq "struct") { - $structs{$old} = $new if (exists($structs{$old})); - next; - } - - die "Can't parse $file_exceptions: $_"; - } -} - -if ($debug) { - print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls); - print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs); - print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums); - print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs); - print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines); - print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols); -} - -# -# Align block -# -$data = expand($data); -$data = " " . $data; -$data =~ s/\n/\n /g; -$data =~ s/\n\s+$/\n/g; -$data =~ s/\n\s+\n/\n\n/g; - -# -# Add escape codes for special characters -# -$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; - -$data =~ s,DEPRECATED,**DEPRECATED**,g; - -# -# Add references -# - -my $start_delim = "[ \n\t\(\=\*\@]"; -my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)"; - -foreach my $r (keys %ioctls) { - my $s = $ioctls{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %defines) { - my $s = $defines{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %enum_symbols) { - my $s = $enum_symbols{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %enums) { - my $s = $enums{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/enum\s+($r)$end_delim/$s$2/g; -} - -foreach my $r (keys %structs) { - my $s = $structs{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/struct\s+($r)$end_delim/$s$2/g; -} - -foreach my $r (keys %typedefs) { - my $s = $typedefs{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -$data =~ s/\\ ([\n\s])/\1/g; - -# -# Generate output file -# - -my $title = $file_in; -$title =~ s,.*/,,; - -open OUT, "> $file_out" or die "Can't open $file_out"; -print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n"; -print OUT "$title\n"; -print OUT "=" x length($title); -print OUT "\n\n.. parsed-literal::\n\n"; -print OUT $data; -close OUT; - -__END__ - -=head1 NAME - -parse_headers.pl - parse a C file, in order to identify functions, structs, -enums and defines and create cross-references to a Sphinx book. - -=head1 SYNOPSIS - -B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] - -Where <options> can be: --debug, --help or --usage. - -=head1 OPTIONS - -=over 8 - -=item B<--debug> - -Put the script in verbose mode, useful for debugging. - -=item B<--usage> - -Prints a brief help message and exits. - -=item B<--help> - -Prints a more detailed help message and exits. - -=back - -=head1 DESCRIPTION - -Convert a C header or source file (C_FILE), into a ReStructured Text -included via ..parsed-literal block with cross-references for the -documentation files that describe the API. It accepts an optional -EXCEPTIONS_FILE with describes what elements will be either ignored or -be pointed to a non-default reference. - -The output is written at the (OUT_FILE). - -It is capable of identifying defines, functions, structs, typedefs, -enums and enum symbols and create cross-references for all of them. -It is also capable of distinguish #define used for specifying a Linux -ioctl. - -The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or -to replace the default references by a custom one. - -Please read Documentation/doc-guide/parse-headers.rst at the Kernel's -tree for more details. - -=head1 BUGS - -Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org> - -=head1 COPYRIGHT - -Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@kernel.org>. - -License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. - -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -=cut diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html index 41f1efbe64bb..b84969bd31c4 100644 --- a/Documentation/sphinx/templates/kernel-toc.html +++ b/Documentation/sphinx/templates/kernel-toc.html @@ -1,4 +1,5 @@ -<!-- SPDX-License-Identifier: GPL-2.0 --> +{# SPDX-License-Identifier: GPL-2.0 #} + {# Create a local TOC the kernel way #} <p> <h3 class="kernel-toc-contents">Contents</h3> diff --git a/Documentation/sphinx/templates/translations.html b/Documentation/sphinx/templates/translations.html index 8df5d42d8dcd..351586f41938 100644 --- a/Documentation/sphinx/templates/translations.html +++ b/Documentation/sphinx/templates/translations.html @@ -1,5 +1,5 @@ -<!-- SPDX-License-Identifier: GPL-2.0 --> -<!-- Copyright © 2023, Oracle and/or its affiliates. --> +{# SPDX-License-Identifier: GPL-2.0 #} +{# Copyright © 2023, Oracle and/or its affiliates. #} {# Create a language menu for translations #} {% if languages|length > 0: %} diff --git a/Documentation/staging/remoteproc.rst b/Documentation/staging/remoteproc.rst index 348ee7e508ac..5c226fa076d6 100644 --- a/Documentation/staging/remoteproc.rst +++ b/Documentation/staging/remoteproc.rst @@ -104,7 +104,7 @@ Typical usage rproc_shutdown(my_rproc); } -API for implementors +API for implementers ==================== :: diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst index 3efac10adb36..651f3a2c01de 100644 --- a/Documentation/trace/boottime-trace.rst +++ b/Documentation/trace/boottime-trace.rst @@ -19,7 +19,7 @@ this uses bootconfig file to describe tracing feature programming. Options in the Boot Config ========================== -Here is the list of available options list for boot time tracing in +Here is the list of available options for boot time tracing in boot config file [1]_. All options are under "ftrace." or "kernel." prefix. See kernel parameters for the options which starts with "kernel." prefix [2]_. diff --git a/Documentation/trace/debugging.rst b/Documentation/trace/debugging.rst index d54bc500af80..4d88c346fc38 100644 --- a/Documentation/trace/debugging.rst +++ b/Documentation/trace/debugging.rst @@ -59,7 +59,7 @@ There is various methods of acquiring the state of the system when a kernel crash occurs. This could be from the oops message in printk, or one could use kexec/kdump. But these just show what happened at the time of the crash. It can be very useful in knowing what happened up to the point of the crash. -The tracing ring buffer, by default, is a circular buffer than will +The tracing ring buffer, by default, is a circular buffer that will overwrite older events with newer ones. When a crash happens, the content of the ring buffer will be all the events that lead up to the crash. diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index 2d88a2acacc0..18d112963dec 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -629,8 +629,8 @@ following: - tracing synthetic events from in-kernel code - the low-level "dynevent_cmd" API -7.1 Dyamically creating synthetic event definitions ---------------------------------------------------- +7.1 Dynamically creating synthetic event definitions +---------------------------------------------------- There are a couple ways to create a new synthetic event from a kernel module or other kernel code. @@ -944,8 +944,8 @@ Note that synth_event_trace_end() must be called at the end regardless of whether any of the add calls failed (say due to a bad field name being passed in). -7.3 Dyamically creating kprobe and kretprobe event definitions --------------------------------------------------------------- +7.3 Dynamically creating kprobe and kretprobe event definitions +--------------------------------------------------------------- To create a kprobe or kretprobe trace event from kernel code, the kprobe_event_gen_cmd_start() or kretprobe_event_gen_cmd_start() diff --git a/Documentation/trace/fprobe.rst b/Documentation/trace/fprobe.rst index 71cd40472d36..06b0edad0179 100644 --- a/Documentation/trace/fprobe.rst +++ b/Documentation/trace/fprobe.rst @@ -81,7 +81,7 @@ Same as ftrace, the registered callbacks will start being called some time after the register_fprobe() is called and before it returns. See :file:`Documentation/trace/ftrace.rst`. -Also, the unregister_fprobe() will guarantee that the both enter and exit +Also, the unregister_fprobe() will guarantee that both enter and exit handlers are no longer being called by functions after unregister_fprobe() returns as same as unregister_ftrace_function(). diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst index e198854ace79..e225cc46b71e 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -193,7 +193,7 @@ FTRACE_OPS_FL_RECURSION Note, if this flag is set, then the callback will always be called with preemption disabled. If it is not set, then it is possible (but not guaranteed) that the callback will be called in - preemptable context. + preemptible context. FTRACE_OPS_FL_IPMODIFY Requires FTRACE_OPS_FL_SAVE_REGS set. If the callback is to "hijack" diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index af66a05e18cc..aef674df3afd 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -30,7 +30,7 @@ disabled and enabled, as well as for preemption and from a time a task is woken to the task is actually scheduled in. One of the most common uses of ftrace is the event tracing. -Throughout the kernel is hundreds of static event points that +Throughout the kernel are hundreds of static event points that can be enabled via the tracefs file system to see what is going on in certain parts of the kernel. @@ -383,7 +383,7 @@ of ftrace. Here is a list of some of the key files: not be listed in this count. If the callback registered to be traced by a function with - the "save regs" attribute (thus even more overhead), a 'R' + the "save regs" attribute (thus even more overhead), an 'R' will be displayed on the same line as the function that is returning registers. @@ -392,7 +392,7 @@ of ftrace. Here is a list of some of the key files: an 'I' will be displayed on the same line as the function that can be overridden. - If a non ftrace trampoline is attached (BPF) a 'D' will be displayed. + If a non-ftrace trampoline is attached (BPF) a 'D' will be displayed. Note, normal ftrace trampolines can also be attached, but only one "direct" trampoline can be attached to a given function at a time. @@ -402,7 +402,7 @@ of ftrace. Here is a list of some of the key files: If a function had either the "ip modify" or a "direct" call attached to it in the past, a 'M' will be shown. This flag is never cleared. It is - used to know if a function was every modified by the ftrace infrastructure, + used to know if a function was ever modified by the ftrace infrastructure, and can be used for debugging. If the architecture supports it, it will also show what callback @@ -418,7 +418,7 @@ of ftrace. Here is a list of some of the key files: This file contains all the functions that ever had a function callback to it via the ftrace infrastructure. It has the same format as - enabled_functions but shows all functions that have every been + enabled_functions but shows all functions that have ever been traced. To see any function that has every been modified by "ip modify" or a @@ -517,7 +517,7 @@ of ftrace. Here is a list of some of the key files: Whenever an event is recorded into the ring buffer, a "timestamp" is added. This stamp comes from a specified clock. By default, ftrace uses the "local" clock. This - clock is very fast and strictly per cpu, but on some + clock is very fast and strictly per CPU, but on some systems it may not be monotonic with respect to other CPUs. In other words, the local clocks may not be in sync with local clocks on other CPUs. @@ -868,7 +868,7 @@ Here is the list of current tracers that may be configured. "mmiotrace" - A special tracer that is used to trace binary module. + A special tracer that is used to trace binary modules. It will trace all the calls that a module makes to the hardware. Everything it writes and reads from the I/O as well. diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index 5765eb3e9efa..ae71b5bf97c6 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -11,13 +11,14 @@ histograms work and how the individual pieces map to the data structures used to implement them in trace_events_hist.c and tracing_map.c. -Note: All the ftrace histogram command examples assume the working - directory is the ftrace /tracing directory. For example:: +.. note:: + All the ftrace histogram command examples assume the working + directory is the ftrace /tracing directory. For example:: # cd /sys/kernel/tracing -Also, the histogram output displayed for those commands will be -generally be truncated - only enough to make the point is displayed. + Also, the histogram output displayed for those commands will be + generally be truncated - only enough to make the point is displayed. 'hist_debug' trace event files ============================== @@ -142,30 +143,30 @@ elements for a couple hypothetical keys and values.:: +--------------+ | | n_keys = n_fields - n_vals | | -The hist_data n_vals and n_fields delineate the extent of the fields[] | | -array and separate keys from values for the rest of the code. | | - -Below is a run-time representation of the tracing_map part of the | | -histogram, with pointers from various parts of the fields[] array | | -to corresponding parts of the tracing_map. | | - -The tracing_map consists of an array of tracing_map_entrys and a set | | -of preallocated tracing_map_elts (abbreviated below as map_entry and | | -map_elt). The total number of map_entrys in the hist_data.map array = | | -map->max_elts (actually map->map_size but only max_elts of those are | | -used. This is a property required by the map_insert() algorithm). | | - -If a map_entry is unused, meaning no key has yet hashed into it, its | | -.key value is 0 and its .val pointer is NULL. Once a map_entry has | | -been claimed, the .key value contains the key's hash value and the | | -.val member points to a map_elt containing the full key and an entry | | -for each key or value in the map_elt.fields[] array. There is an | | -entry in the map_elt.fields[] array corresponding to each hist_field | | -in the histogram, and this is where the continually aggregated sums | | -corresponding to each histogram value are kept. | | - -The diagram attempts to show the relationship between the | | -hist_data.fields[] and the map_elt.fields[] with the links drawn | | +The hist_data n_vals and n_fields delineate the extent of the fields[] +array and separate keys from values for the rest of the code. + +Below is a run-time representation of the tracing_map part of the +histogram, with pointers from various parts of the fields[] array +to corresponding parts of the tracing_map. + +The tracing_map consists of an array of tracing_map_entrys and a set +of preallocated tracing_map_elts (abbreviated below as map_entry and +map_elt). The total number of map_entrys in the hist_data.map array = +map->max_elts (actually map->map_size but only max_elts of those are +used. This is a property required by the map_insert() algorithm). + +If a map_entry is unused, meaning no key has yet hashed into it, its +.key value is 0 and its .val pointer is NULL. Once a map_entry has +been claimed, the .key value contains the key's hash value and the +.val member points to a map_elt containing the full key and an entry +for each key or value in the map_elt.fields[] array. There is an +entry in the map_elt.fields[] array corresponding to each hist_field +in the histogram, and this is where the continually aggregated sums +corresponding to each histogram value are kept. + +The diagram attempts to show the relationship between the +hist_data.fields[] and the map_elt.fields[] with the links drawn between diagrams:: +-----------+ | | @@ -380,7 +381,9 @@ entry, ts0, corresponding to the ts0 variable in the sched_waking trigger above. sched_waking histogram -----------------------:: +---------------------- + +.. code-block:: +------------------+ | hist_data |<-------------------------------------------------------+ @@ -440,31 +443,31 @@ sched_waking histogram n_keys = n_fields - n_vals | | | | | | -This is very similar to the basic case. In the above diagram, we can | | | -see a new .flags member has been added to the struct hist_field | | | -struct, and a new entry added to hist_data.fields representing the ts0 | | | -variable. For a normal val hist_field, .flags is just 0 (modulo | | | -modifier flags), but if the value is defined as a variable, the .flags | | | -contains a set FL_VAR bit. | | | - -As you can see, the ts0 entry's .var.idx member contains the index | | | -into the tracing_map_elts' .vars[] array containing variable values. | | | -This idx is used whenever the value of the variable is set or read. | | | -The map_elt.vars idx assigned to the given variable is assigned and | | | -saved in .var.idx by create_tracing_map_fields() after it calls | | | -tracing_map_add_var(). | | | - -Below is a representation of the histogram at run-time, which | | | -populates the map, along with correspondence to the above hist_data and | | | -hist_field data structures. | | | - -The diagram attempts to show the relationship between the | | | -hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with | | | -the links drawn between diagrams. For each of the map_elts, you can | | | -see that the .fields[] members point to the .sum or .offset of a key | | | -or val and the .vars[] members point to the value of a variable. The | | | -arrows between the two diagrams show the linkages between those | | | -tracing_map members and the field definitions in the corresponding | | | +This is very similar to the basic case. In the above diagram, we can +see a new .flags member has been added to the struct hist_field +struct, and a new entry added to hist_data.fields representing the ts0 +variable. For a normal val hist_field, .flags is just 0 (modulo +modifier flags), but if the value is defined as a variable, the .flags +contains a set FL_VAR bit. + +As you can see, the ts0 entry's .var.idx member contains the index +into the tracing_map_elts' .vars[] array containing variable values. +This idx is used whenever the value of the variable is set or read. +The map_elt.vars idx assigned to the given variable is assigned and +saved in .var.idx by create_tracing_map_fields() after it calls +tracing_map_add_var(). + +Below is a representation of the histogram at run-time, which +populates the map, along with correspondence to the above hist_data and +hist_field data structures. + +The diagram attempts to show the relationship between the +hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with +the links drawn between diagrams. For each of the map_elts, you can +see that the .fields[] members point to the .sum or .offset of a key +or val and the .vars[] members point to the value of a variable. The +arrows between the two diagrams show the linkages between those +tracing_map members and the field definitions in the corresponding hist_data fields[] members.:: +-----------+ | | | @@ -565,40 +568,40 @@ hist_data fields[] members.:: | | | | +---------------+ | | -For each used map entry, there's a map_elt pointing to an array of | | -.vars containing the current value of the variables associated with | | -that histogram entry. So in the above, the timestamp associated with | | -pid 999 is 113345679876, and the timestamp variable in the same | | -.var.idx for pid 4444 is 213499240729. | | - -sched_switch histogram | | ----------------------- | | - -The sched_switch histogram paired with the above sched_waking | | -histogram is shown below. The most important aspect of the | | -sched_switch histogram is that it references a variable on the | | -sched_waking histogram above. | | - -The histogram diagram is very similar to the others so far displayed, | | -but it adds variable references. You can see the normal hitcount and | | -key fields along with a new wakeup_lat variable implemented in the | | -same way as the sched_waking ts0 variable, but in addition there's an | | -entry with the new FL_VAR_REF (short for HIST_FIELD_FL_VAR_REF) flag. | | - -Associated with the new var ref field are a couple of new hist_field | | -members, var.hist_data and var_ref_idx. For a variable reference, the | | -var.hist_data goes with the var.idx, which together uniquely identify | | -a particular variable on a particular histogram. The var_ref_idx is | | -just the index into the var_ref_vals[] array that caches the values of | | -each variable whenever a hist trigger is updated. Those resulting | | -values are then finally accessed by other code such as trace action | | -code that uses the var_ref_idx values to assign param values. | | - -The diagram below describes the situation for the sched_switch | | +For each used map entry, there's a map_elt pointing to an array of +.vars containing the current value of the variables associated with +that histogram entry. So in the above, the timestamp associated with +pid 999 is 113345679876, and the timestamp variable in the same +.var.idx for pid 4444 is 213499240729. + +sched_switch histogram +---------------------- + +The sched_switch histogram paired with the above sched_waking +histogram is shown below. The most important aspect of the +sched_switch histogram is that it references a variable on the +sched_waking histogram above. + +The histogram diagram is very similar to the others so far displayed, +but it adds variable references. You can see the normal hitcount and +key fields along with a new wakeup_lat variable implemented in the +same way as the sched_waking ts0 variable, but in addition there's an +entry with the new FL_VAR_REF (short for HIST_FIELD_FL_VAR_REF) flag. + +Associated with the new var ref field are a couple of new hist_field +members, var.hist_data and var_ref_idx. For a variable reference, the +var.hist_data goes with the var.idx, which together uniquely identify +a particular variable on a particular histogram. The var_ref_idx is +just the index into the var_ref_vals[] array that caches the values of +each variable whenever a hist trigger is updated. Those resulting +values are then finally accessed by other code such as trace action +code that uses the var_ref_idx values to assign param values. + +The diagram below describes the situation for the sched_switch histogram referred to before:: - # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> | | - events/sched/sched_switch/trigger | | + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> + events/sched/sched_switch/trigger | | +------------------+ | | | hist_data | | | diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index 2b98c1720a54..340bcb5099e7 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -186,8 +186,8 @@ Documentation written by Tom Zanussi The examples below provide a more concrete illustration of the concepts and typical usage patterns discussed above. -'special' event fields ------------------------- +2.1. 'special' event fields +--------------------------- There are a number of 'special event fields' available for use as keys or values in a hist trigger. These look like and behave as if @@ -204,16 +204,16 @@ Documentation written by Tom Zanussi common_cpu int the cpu on which the event occurred. ====================== ==== ======================================= -Extended error information --------------------------- +2.2. Extended error information +------------------------------- For some error conditions encountered when invoking a hist trigger command, extended error information is available via the - tracing/error_log file. See Error Conditions in - :file:`Documentation/trace/ftrace.rst` for details. + tracing/error_log file. See "Error conditions" section in + Documentation/trace/ftrace.rst for details. -6.2 'hist' trigger examples ---------------------------- +2.3. 'hist' trigger examples +---------------------------- The first set of examples creates aggregations using the kmalloc event. The fields that can be used for the hist trigger are listed @@ -840,7 +840,7 @@ Extended error information The compound key examples used a key and a sum value (hitcount) to sort the output, but we can just as easily use two keys instead. - Here's an example where we use a compound key composed of the the + Here's an example where we use a compound key composed of the common_pid and size event fields. Sorting with pid as the primary key and 'size' as the secondary key allows us to display an ordered summary of the recvfrom sizes, with counts, received by @@ -1608,8 +1608,8 @@ Extended error information Entries: 7 Dropped: 0 -2.2 Inter-event hist triggers ------------------------------ +2.4. Inter-event hist triggers +------------------------------ Inter-event hist triggers are hist triggers that combine values from one or more other events and create a histogram using that data. Data @@ -1685,8 +1685,8 @@ pseudo-file. These features are described in more detail in the following sections. -2.2.1 Histogram Variables -------------------------- +2.5. Histogram Variables +------------------------ Variables are simply named locations used for saving and retrieving values between matching events. A 'matching' event is defined as an @@ -1789,8 +1789,8 @@ or assigned to a variable and referenced in a subsequent expression:: Variables can even hold stacktraces, which are useful with synthetic events. -2.2.2 Synthetic Events ----------------------- +2.6. Synthetic Events +--------------------- Synthetic events are user-defined events generated from hist trigger variables or fields associated with one or more other events. Their @@ -1846,7 +1846,7 @@ the command that defined it with a '!':: At this point, there isn't yet an actual 'wakeup_latency' event instantiated in the event subsystem - for this to happen, a 'hist trigger action' needs to be instantiated and bound to actual fields -and variables defined on other events (see Section 2.2.3 below on +and variables defined on other events (see Section 2.7. below on how that is done using hist trigger 'onmatch' action). Once that is done, the 'wakeup_latency' synthetic event instance is created. @@ -2094,8 +2094,8 @@ histogram:: Entries: 7 Dropped: 0 -2.2.3 Hist trigger 'handlers' and 'actions' -------------------------------------------- +2.7. Hist trigger 'handlers' and 'actions' +------------------------------------------ A hist trigger 'action' is a function that's executed (in most cases conditionally) whenever a histogram entry is added or updated. @@ -2526,8 +2526,8 @@ The following commonly-used handler.action pairs are available: kworker/3:2-135 [003] d..3 49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120 <idle>-0 [004] ..s7 49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312 -3. User space creating a trigger --------------------------------- +2.8. User space creating a trigger +---------------------------------- Writing into /sys/kernel/tracing/trace_marker writes into the ftrace ring buffer. This can also act like an event, by writing into the trigger diff --git a/Documentation/trace/rv/monitor_synthesis.rst b/Documentation/trace/rv/monitor_synthesis.rst index ac808a7554f5..3a7d7b2f6cb6 100644 --- a/Documentation/trace/rv/monitor_synthesis.rst +++ b/Documentation/trace/rv/monitor_synthesis.rst @@ -181,7 +181,7 @@ which is the list of atomic propositions present in the LTL specification functions interacting with the Buchi automaton. While generating code, `rvgen` cannot understand the meaning of the atomic -propositions. Thus, that task is left for manual work. The recommended pratice +propositions. Thus, that task is left for manual work. The recommended practice is adding tracepoints to places where the atomic propositions change; and in the tracepoints' handlers: the Buchi automaton is executed using:: diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 77db13c4022b..7e93833b4511 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -46,7 +46,6 @@ util-linux 2.10o mount --version kmod 13 depmod -V e2fsprogs 1.41.4 e2fsck -V jfsutils 1.1.3 fsck.jfs -V -reiserfsprogs 3.6.3 reiserfsck -V xfsprogs 2.6.0 xfs_db -V squashfs-tools 4.0 mksquashfs -version btrfs-progs 0.18 btrfsck @@ -260,14 +259,6 @@ Sono disponibili i seguenti strumenti: - sono disponibili altri strumenti per il file-system. -Reiserfsprogs -------------- - -Il pacchetto reiserfsprogs dovrebbe essere usato con reiserfs-3.6.x (Linux -kernel 2.4.x). Questo è un pacchetto combinato che contiene versioni -funzionanti di ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` e -``reiserfsck``. Questi programmi funzionano sulle piattaforme i386 e alpha. - Xfsprogs -------- @@ -479,11 +470,6 @@ JFSutils - <https://jfs.sourceforge.net/> -Reiserfsprogs -------------- - -- <https://git.kernel.org/pub/scm/linux/kernel/git/jeffm/reiserfsprogs.git/> - Xfsprogs -------- diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt index 547062759e60..b17c9f638628 100644 --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -282,7 +282,7 @@ drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序 假定驱动没有跨越多个总线类型)。 fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须 -在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.rst)。 +在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse/fuse.rst)。 dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以 <major>:<minor> 格式命名的符号链接。这些符号链接指向 sysfs 目录 diff --git a/Documentation/translations/zh_TW/filesystems/sysfs.txt b/Documentation/translations/zh_TW/filesystems/sysfs.txt index 978462d5fe14..d1cee02ef1de 100644 --- a/Documentation/translations/zh_TW/filesystems/sysfs.txt +++ b/Documentation/translations/zh_TW/filesystems/sysfs.txt @@ -285,7 +285,7 @@ drivers/ 包含了每個已爲特定總線上的設備而掛載的驅動程序 假定驅動沒有跨越多個總線類型)。 fs/ 包含了一個爲文件系統設立的目錄。現在每個想要導出屬性的文件系統必須 -在 fs/ 下創建自己的層次結構(參見Documentation/filesystems/fuse.rst)。 +在 fs/ 下創建自己的層次結構(參見Documentation/filesystems/fuse/fuse.rst)。 dev/ 包含兩個子目錄： char/ 和 block/。在這兩個子目錄中，有以 <major>:<minor> 格式命名的符號鏈接。這些符號鏈接指向 sysfs 目錄 diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile deleted file mode 100644 index 3d8aaf5c253b..000000000000 --- a/Documentation/userspace-api/media/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Rules to convert a .h file to inline RST documentation - -SRC_DIR=$(srctree)/Documentation/userspace-api/media -PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl -UAPI = $(srctree)/include/uapi/linux -KAPI = $(srctree)/include/linux - -FILES = ca.h.rst dmx.h.rst frontend.h.rst net.h.rst \ - videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst - -TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) - -gen_rst = \ - echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \ - ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions - -quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \ - ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions - -silent_gen_rst = ${gen_rst} - -$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/media.h.rst: ${UAPI}/media.h ${PARSER} $(SRC_DIR)/media.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/cec.h.rst: ${UAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions - @$($(quiet)gen_rst) - -# Media build rules - -.PHONY: all html texinfo epub xml latex - -all: $(IMGDOT) $(BUILDDIR) ${TARGETS} -html: all -texinfo: all -epub: all -xml: all -latex: $(IMGPDF) all -linkcheck: - -clean: - -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null - -$(BUILDDIR): - $(Q)mkdir -p $@ diff --git a/Documentation/userspace-api/media/cec/cec-header.rst b/Documentation/userspace-api/media/cec/cec-header.rst index d70736ac2b1d..f67003bb8740 100644 --- a/Documentation/userspace-api/media/cec/cec-header.rst +++ b/Documentation/userspace-api/media/cec/cec-header.rst @@ -6,5 +6,6 @@ CEC Header File *************** -.. kernel-include:: $BUILDDIR/cec.h.rst - +.. kernel-include:: include/uapi/linux/cec.h + :generate-cross-refs: + :exception-file: cec.h.rst.exceptions diff --git a/Documentation/userspace-api/media/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec/cec.h.rst.exceptions index 15fa1752d4ef..15fa1752d4ef 100644 --- a/Documentation/userspace-api/media/cec.h.rst.exceptions +++ b/Documentation/userspace-api/media/cec/cec.h.rst.exceptions diff --git a/Documentation/userspace-api/media/ca.h.rst.exceptions b/Documentation/userspace-api/media/dvb/ca.h.rst.exceptions index f6828238eb48..f6828238eb48 100644 --- a/Documentation/userspace-api/media/ca.h.rst.exceptions +++ b/Documentation/userspace-api/media/dvb/ca.h.rst.exceptions diff --git a/Documentation/userspace-api/media/dmx.h.rst.exceptions b/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions index afc14d384b83..afc14d384b83 100644 --- a/Documentation/userspace-api/media/dmx.h.rst.exceptions +++ b/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions diff --git a/Documentation/userspace-api/media/frontend.h.rst.exceptions b/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions index dcaf5740de7e..dcaf5740de7e 100644 --- a/Documentation/userspace-api/media/frontend.h.rst.exceptions +++ b/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions diff --git a/Documentation/userspace-api/media/dvb/headers.rst b/Documentation/userspace-api/media/dvb/headers.rst index 88c3eb33a89e..c75f64cf21d5 100644 --- a/Documentation/userspace-api/media/dvb/headers.rst +++ b/Documentation/userspace-api/media/dvb/headers.rst @@ -7,10 +7,19 @@ Digital TV uAPI header files Digital TV uAPI headers *********************** -.. kernel-include:: $BUILDDIR/frontend.h.rst +.. kernel-include:: include/uapi/linux/dvb/frontend.h + :generate-cross-refs: + :exception-file: frontend.h.rst.exceptions -.. kernel-include:: $BUILDDIR/dmx.h.rst +.. kernel-include:: include/uapi/linux/dvb/dmx.h + :generate-cross-refs: + :exception-file: dmx.h.rst.exceptions -.. kernel-include:: $BUILDDIR/ca.h.rst +.. kernel-include:: include/uapi/linux/dvb/ca.h + :generate-cross-refs: + :exception-file: ca.h.rst.exceptions + +.. kernel-include:: include/uapi/linux/dvb/net.h + :generate-cross-refs: + :exception-file: net.h.rst.exceptions -.. kernel-include:: $BUILDDIR/net.h.rst diff --git a/Documentation/userspace-api/media/net.h.rst.exceptions b/Documentation/userspace-api/media/dvb/net.h.rst.exceptions index 5159aa4bbbb9..5159aa4bbbb9 100644 --- a/Documentation/userspace-api/media/net.h.rst.exceptions +++ b/Documentation/userspace-api/media/dvb/net.h.rst.exceptions diff --git a/Documentation/userspace-api/media/mediactl/media-header.rst b/Documentation/userspace-api/media/mediactl/media-header.rst index c674271c93f5..d561d2845f3d 100644 --- a/Documentation/userspace-api/media/mediactl/media-header.rst +++ b/Documentation/userspace-api/media/mediactl/media-header.rst @@ -6,5 +6,6 @@ Media Controller Header File **************************** -.. kernel-include:: $BUILDDIR/media.h.rst - +.. kernel-include:: include/uapi/linux/media.h + :generate-cross-refs: + :exception-file: media.h.rst.exceptions diff --git a/Documentation/userspace-api/media/media.h.rst.exceptions b/Documentation/userspace-api/media/mediactl/media.h.rst.exceptions index 9b4c26502d95..9b4c26502d95 100644 --- a/Documentation/userspace-api/media/media.h.rst.exceptions +++ b/Documentation/userspace-api/media/mediactl/media.h.rst.exceptions diff --git a/Documentation/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst index 54cb40b8a065..a53328327847 100644 --- a/Documentation/userspace-api/media/rc/lirc-header.rst +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -6,5 +6,7 @@ LIRC Header File **************** -.. kernel-include:: $BUILDDIR/lirc.h.rst +.. kernel-include:: include/uapi/linux/lirc.h + :generate-cross-refs: + :exception-file: lirc.h.rst.exceptions diff --git a/Documentation/userspace-api/media/lirc.h.rst.exceptions b/Documentation/userspace-api/media/rc/lirc.h.rst.exceptions index 1aeb7d7afe13..1aeb7d7afe13 100644 --- a/Documentation/userspace-api/media/lirc.h.rst.exceptions +++ b/Documentation/userspace-api/media/rc/lirc.h.rst.exceptions diff --git a/Documentation/userspace-api/media/v4l/videodev.rst b/Documentation/userspace-api/media/v4l/videodev.rst index c866fec417eb..cde485bc9a5f 100644 --- a/Documentation/userspace-api/media/v4l/videodev.rst +++ b/Documentation/userspace-api/media/v4l/videodev.rst @@ -6,4 +6,6 @@ Video For Linux Two Header File ******************************* -.. kernel-include:: $BUILDDIR/videodev2.h.rst +.. kernel-include:: include/uapi/linux/videodev2.h + :generate-cross-refs: + :exception-file: videodev2.h.rst.exceptions diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions index 35d3456cc812..35d3456cc812 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 6aa40ee05a4a..c17a87a0a5ac 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -6414,6 +6414,15 @@ most one mapping per page, i.e. binding multiple memory regions to a single guest_memfd range is not allowed (any number of memory regions can be bound to a single guest_memfd file, but the bound ranges must not overlap). +When the capability KVM_CAP_GUEST_MEMFD_MMAP is supported, the 'flags' field +supports GUEST_MEMFD_FLAG_MMAP. Setting this flag on guest_memfd creation +enables mmap() and faulting of guest_memfd memory to host userspace. + +When the KVM MMU performs a PFN lookup to service a guest fault and the backing +guest_memfd has the GUEST_MEMFD_FLAG_MMAP set, then the fault will always be +consumed from guest_memfd, regardless of whether it is a shared or a private +fault. + See KVM_SET_USER_MEMORY_REGION2 for additional details. 4.143 KVM_PRE_FAULT_MEMORY diff --git a/Documentation/virt/kvm/review-checklist.rst b/Documentation/virt/kvm/review-checklist.rst index debac54e14e7..053f00c50d66 100644 --- a/Documentation/virt/kvm/review-checklist.rst +++ b/Documentation/virt/kvm/review-checklist.rst @@ -98,7 +98,7 @@ New APIs It is important to demonstrate your use case. This can be as simple as explaining that the feature is already in use on bare metal, or it can be a proof-of-concept implementation in userspace. The latter need not be - open source, though that is of course preferrable for easier testing. + open source, though that is of course preferable for easier testing. Selftests should test corner cases of the APIs, and should also cover basic host and guest operation if no open source VMM uses the feature. diff --git a/Documentation/w1/masters/ds2482.rst b/Documentation/w1/masters/ds2482.rst index 17ebe8f660cd..5862024e4b15 100644 --- a/Documentation/w1/masters/ds2482.rst +++ b/Documentation/w1/masters/ds2482.rst @@ -22,7 +22,7 @@ Description ----------- The Maxim/Dallas Semiconductor DS2482 is a I2C device that provides -one (DS2482-100) or eight (DS2482-800) 1-wire busses. +one (DS2482-100) or eight (DS2482-800) 1-wire buses. General Remarks diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst index cc40189909fd..871442c7f195 100644 --- a/Documentation/w1/masters/index.rst +++ b/Documentation/w1/masters/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 ===================== 1-wire Master Drivers diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst index d0697b202f09..a210f38c889c 100644 --- a/Documentation/w1/slaves/index.rst +++ b/Documentation/w1/slaves/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 ==================== 1-wire Slave Drivers |